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.

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

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

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

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

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”].

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.

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.

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/help/operations/Detokenize

For this example, the payload is:

{

“APIKey”:”$[tokenex_api_key]”,

“TokenExID”:”$[tokenex_id]”,

“Token”:”$[token]”

}

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

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.

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.

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

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.

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.”

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);

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.

To learn more about tokenization, download our free eBook here: