TokenEx API Integration with ServiceNow

TokenEx’s cloud-based API can integrate with the ServiceNow application to sanitize sensitive data within a user’s ServiceNow environment. This is manageable using the Rest Message feature available within the ServiceNow management interface.

In this example, we will make use of the TokenEx Token Services API and integrate with a basic ServiceNow application. This application will contain a form with three input fields (Name, DOB, SSN). When a new entry is submitted, a call will be made to the TokenEx API to tokenize the SSN. The token will replace the SSN and be stored within the application environment. When an entry is clicked to view the details, another call will be made to detokenize the token so that the SSN is visible.

 

To begin, find the Rest Message page via the navigation panel. Then you will need to click “New” to add an entry to the list of existing messages.RyansBlogImage1

After entering a name for your new REST Message, enter the following test tokenize endpoint: https://test-api.tokenex.com/TokenServices.svc/REST/Tokenize

 

Next, add Accept and Content-Type headers with a value of Application/JSON for both entries.RyansBlogImage2-1

 

Under HTTP Methods, we will need to add a new entry. This is where the actual call to TokenEx takes place. RyansBlogImage3

 

Add a name for the new REST Message entry. Then, paste the same endpoint into the endpoint input.RyansBlogImage4

For the TokenEx API, the validation exists within the JSON payload sent to the TokenEx API endpoint, so no setting needs to be changed on the Authentication tab.

Click on the HTTP Request tab. This will bring up a place for optional headers, parameters, and content. Within the Content box, you will need to enter a JSON template for the typical request your application will send to TokenEx.

In this example the following payload is used:

{

“APIKey”:”$[tokenex_api_key]”,

“TokenExID”:”$[tokenex_id]”,

“Data”:”$[data]”,

“TokenScheme”:”$[tokenex_token_scheme]”,

}

 

In order to utilize dynamic values, ServiceNow provides the ability to use variables within various inputs within the application. The format, as seen above, is: $[“EXAMPLE”].RyansBlogImage5

 

Once the content is entered and the variables are set up, click the “Auto generate variables” link. This will then generate the variables within the Variable Substitution list. Once that list is populated, test values can be entered for each variable.RyansBlogImage6

 

Once test values have been entered, click the “Test” link to run the request against the TokenEx API and validate that a successful call was made.RyansBlogImage7

 

The next step is to create a similar HTTP Method for the request to the TokenEx Detokenize API endpoint. The URL for that endpoint is: https://test-api.tokenex.com/TokenServices.svc/REST/Detokenize

 

For this example, the payload is:

{

“APIKey”:”$[tokenex_api_key]”,

“TokenExID”:”$[tokenex_id]”,

“Token”:”$[token]”

}

RyansBlogImage8

 

Just like the Tokenize HTTP Method, we need to hit the “Test” link and verify a successful detokenization.RyansBlogImage9

 

For both the Tokenize and Detokenize HTTP Methods, there is a sample script generated which can be found by clicking the “Preview Script Usage.” Copy the scripts for both method calls. They will be used as a baseline for our next step: setting up Business Rules.RyansBlogImage10

 

To bring it all together, navigate to Business Rules. A rule will need to be set up for both tokenize and detokenize calls. These rules tell your application when to make the HTTP Method calls set up previously.RyansBlogImage11

 

For the Tokenize Business Rule on the “When to run” tab, set the “When” option to “before” and mark the checkbox for “Insert”.RyansBlogImage12

 

Once that’s complete, click on the “Advanced” tab to bring up the text area for the Script that will be used to call the HTTP Method. Here you can paste in the sample script from the Tokenize HTTP Method copied earlier. Then, we’ll use that as a template to make some modifications to finish up the process.RyansBlogImage15

 

For the following script to work, we set up system variables to store the TokenEx ID and API Key for the purpose of reusability. It’s always a good idea to store static values in a config area when possible.

In order to set up these variables, follow the directions found here: https://docs.servicenow.com/bundle/orlando-platform-administration/page/administer/reference-pages/task/t_AddAPropertyUsingSysPropsList.html

The system variables set up for this demo are 'x_514161_tokenex_p.tx_api_key' and 'x_514161_tokenex_p.tx_tokenex_id'

The script below is for the tokenize call. Once the script is in place, the desired input in a form submission should be tokenized.

(function executeRule(current, previous /*null when async*/ ) {

   try {      

       var r = new sn_ws.RESTMessageV2('x_514161_tokenex_p.TokenizeRestCall', 'TokenizePost');

//The following four lines are set up to grab the system parameter values to API Key and TokenExID.

       var apiKey = gs.getProperty('x_514161_tokenex_p.tx_api_key');

       r.setStringParameterNoEscape('tokenex_api_key', apiKey);

 

       var tokenexId = gs.getProperty('x_514161_tokenex_p.tx_tokenex_id');

       r.setStringParameterNoEscape('tokenex_id', tokenexId);

 

//The following two lines are set up to grab the SSN field value from the form submission.

       r.setStringParameterNoEscape('tokenex_token_scheme', '4');

       r.setStringParameterNoEscape('data', current.ssn);

 

                                var response = r.executeAsync();

//This delay of 5 seconds is not ideal and is only for this demo to verify the call completes.

                                response.waitForResponse(5);

                                var responseBody = response.getBody();

//To log something, use gs.info(). Below logs the full response.

                                gs.info(responseBody);             

//Here we parse the JSON payload we get from the TokenEx API and pull out the Token value.

                                var parsedData = JSON.parse(responseBody);             

                                current.ssn = parsedData.Token;

       var httpStatus = response.getStatusCode();

   } catch (ex) {

       var message = ex.message;

   }

})(current, previous);

 

Next, a business rule needs to be set up for the detokenize portion of the call. We will set up this rule to run when a data entry is displayed. To do that, set the “When” dropdown value to “display.”RyansBlogImage14

 

The script below is for the detokenize call. Once the script is in place, the desired input in a form submission should be tokenized.

(function executeRule(current, previous /*null when async*/ ) {

   try {

       var r = new sn_ws.RESTMessageV2('x_514161_tokenex_p.DetokenizeRestCall', 'Detokenize');

//Pull in the SSN Token from the data record.

       r.setStringParameterNoEscape('token', current.ssn);

//Load the API Key and TokenExID from the system property values.

       var apiKey = gs.getProperty('x_514161_tokenex_p.tx_detokenize_api_key');

       r.setStringParameterNoEscape('tokenex_api_key', apiKey);

       var tokenexId = gs.getProperty('x_514161_tokenex_p.tx_tokenex_id');

       r.setStringParameterNoEscape('tokenex_id', tokenexId);

       var response = r.executeAsync();

       response.waitForResponse(5);

       var responseBody = response.getBody();

       var parsedData = JSON.parse(responseBody);

       gs.info(parsedData);

       gs.info("PII is:" + parsedData.Value);

       current.ssn = parsedData.Value;

       var httpStatus = response.getStatusCode();

   } catch (ex) {

       var message = ex.message;

   }

})(current, previous);

RyansBlogImage15

 

Now, the business rules for tokenize and detokenize have been set up. Once a new record is submitted, the designated input’s data will be tokenized as seen below.RyansBlogImage16

RyansBlogImage17

To download this blog as a PDF, click HERE.

 

Topic(s): payments

Keep Up With Our PCI & Privacy Blog