Integrating with ServiceNow

How to add a mandatory tag to the External ServiceNow workflow change request?

Follow these steps to add a mandatory tag to the change request for the External ServiceNow workflow integration:

1. Login to your ServiceNow instance as an administrator.

2. Open an existing Change Request.

   

3. Click the additional actions icon to open up the additional options.

   

4. Click Configure and select the Form Layout.

   

5. In the Form Layout under Form view and section, select Change Request and create a new field with Name exactly as Appconfiguration tag, Type as String, and Field length as Medium (100).

   Make sure to enter the field Name exactly as Appconfiguration tag (case sensitive).

   

6. Click Add. Once added, the new field will be shown in the Available section.

   

7. Select Appconfiguration tag from the Available section and add it to Selected section.

   

8. You can see the new field appearing in the change request.

   

   Field value is added by App Configuration service while creating new change requests. Hence, do not modify the value or add any other value to Appconfiguration tag field. Modifying or adding any other value to the field can lead to ignoring the change request events.

How to register or add webhook script to your External ServiceNow instance?

Follow these steps to register or add webhook script to your ServiceNow instance:

1. Login to your ServiceNow instance as an administrator.

2. Click the All tab and search for Business Rules listed under System Definitions.

   

3. In the Business Rules page, click the New button.

   

4. In the new record, add the Name, select the table to be Change Request. Select the Advanced check box to see the advanced option tab.

   

5. In the Advanced option tab, add the webhook script.

   (function executeRule(current, previous /*null when async*/) {
      try {
         if (current.u_appconfiguration_tag == "appconfig-workflow" && (current.state == -1 || current.state == -5 || current.state == 4)) {
               //creating the glider Encrypt object
               var glideEncrypt = new GlideEncrypter();
               //fetching the sys_property that contains the IAM key
               var encryptedIbmIAMKey = gs.getProperty('<Add System property name which holds the IBM IAM key (Case Sensitive)>');
               //example: var encryptedKey = gs.getProperty('WorkflowAppConfigIamKey'); 
               //Decrypting the key
               var decryptedIAMKey = glideEncrypt.decrypt(encryptedIbmIAMKey);
               gs.addInfoMessage("IBM KEY DECRYPTION COMPLETED");
               if (Object.keys(decryptedIAMKey).length !== 0) {
                  gs.addInfoMessage("CHANGE REQUEST IDENTIFIED AS WORKFLOW RELATED");
                  //Adding the decrypted key to the IAM token generation body
                  var bodyContent = "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=" + decryptedIAMKey;
                  //Making POST call to IBM IAM to generate token
                  var ibmIamTokenRequest = new sn_ws.RESTMessageV2();
                  ibmIamTokenRequest.setHttpMethod('POST');
                  ibmIamTokenRequest.setEndpoint('https://iam.cloud.ibm.com/identity/token');
                  ibmIamTokenRequest.setRequestBody(bodyContent);
                  ibmIamTokenResponse = ibmIamTokenRequest.execute();
                  var ibmIamTokenResponseCode = ibmIamTokenResponse.getStatusCode();
                  gs.addInfoMessage("IBM IAM TOKEN CREATION HTTP RESPONSE CODE: " + ibmIamTokenResponseCode);
                  if (ibmIamTokenResponseCode == 200) {
                     //parsing json response to extract the access_token
                     var ibmIamTokenResponseData = JSON.parse(ibmIamTokenResponse.getBody());
   
                     //extracting the access_token
                     var access_token = ibmIamTokenResponseData.access_token;
                     var encryptedInstanceId = gs.getProperty('<Add System property name which holds the AppConfig InstanceId (Case Sensitive)>');
                     //example: var encryptedInstanceId = gs.getProperty('WorkflowIbmAppConfigInstanceId');
                     var decryptedInstanceId = glideEncrypt.decrypt(encryptedInstanceId);
                     gs.addInfoMessage("IBM APP CONFIG INSTANCE ID DECRYPTION COMPLETED");
                     //preparing webhook request to forward
                     var webHookRequest = new sn_ws.RESTMessageV2();
                     //Refer link https://cloud.ibm.com/apidocs/app-configuration#endpoints-urls for more info on base URL
                     //Choose the base url from below based on your AppConfig instance region
                     //Dallas: https://us-south.apprapp.cloud.ibm.com
                     //Washington DC: https://us-east.apprapp.cloud.ibm.com
                     //London: https://eu-gb.apprapp.cloud.ibm.com
                     //Sydney: https://au-syd.apprapp.cloud.ibm.com
                     //Frankfurt: https://eu-de.apprapp.cloud.ibm.com
   
                     webHookRequest.setEndpoint('{{AppConfigRegionBaseURL}}/apprapp/workflow/v1/instances/' + decryptedInstanceId + '/crevents');
                     webHookRequest.setRequestHeader('Authorization', 'Bearer ' + access_token);
                     webHookRequest.setHttpMethod('POST');
                     webHookRequest.setRequestHeader("Accept", "application/json");
                     webHookRequest.setRequestHeader("Content-Type", "application/json");
   
                     //preparing the data for the webhook request
                     var webHookReqDataObject = new Object();
                     //BELOW ARE THE DATA THAT IS NEEDED TO PROCESS THE REQUEST, MODIFYING OR ALTERING THE DATA OR THE ATTRIBUTE WILL RESULT IN WEBHOOK REQUEST FAILURE.
                     webHookReqDataObject.operation = String(current.operation());
                     webHookReqDataObject.short_description = String(current.short_description);
                     webHookReqDataObject.change_request_id = String(current.number);
                     webHookReqDataObject.description = String(current.description);
                     webHookReqDataObject.cr_state = String(current.state);
                     webHookReqDataObject.cr_approval_assignment_group = String(current.assignment_group);
                     webHookReqDataObject.appconfiguration_tag = String(current.u_appconfiguration_tag);
                     webHookReqDataObject.implementation_time = String(current.work_start);
                     var webHookJsonStringData = JSON.stringify(webHookReqDataObject);
                     gs.addInfoMessage(webHookJsonStringData);
                     webHookRequest.setRequestBody(webHookJsonStringData);
   
                     //checking the change request has the tag, we only accept the CR with the below mentioned tag id 
                     gs.addInfoMessage("SENDING REQUEST TO APP CONFIGURATION WEBHOOK HANDLER");
                     var webHookResponse = webHookRequest.execute();
                     httpResponseStatus = webHookResponse.getStatusCode();
                     gs.addInfoMessage("APP CONFIGURATION WEBHOOK HANDLER RESPONSE CODE:  " + httpResponseStatus);
                     if (httpResponseStatus == 200) {
                           gs.addInfoMessage("SUCCESSFULLY EXECUTED THE WEBHOOK CALL");
                     } else {
                           //try once more
                           webHookResponse = webHookRequest.execute();
                           httpResponseStatus = webHookResponse.getStatusCode();
                           gs.addInfoMessage("WEBHOOK CALL RETRY STATUS CODE:  " + httpResponseStatus);
                           gs.addInfoMessage(webHookResponse.getBody());
                     }
                  } else {
                     gs.addInfoMessage("IBM IAM TOKEN GENERATION FAILED");
                  }
               } else {
                  gs.addInfoMessage("DECRYPTED IAM KEY IS EMPTY OR NOT FOUND");
               }
         } else {
               gs.addInfoMessage("CR STATE : " + current.state + " CR APPCONFIGURATION TAG VALUE : " + current.u_appconfiguration_tag);
               gs.addInfoMessage("CHANGE REQUEST DOES NOT BELONG TO WORKFLOW INTEGRATION OR STATE OF THE CR IS NOT VALID");
         }
      } catch (ex) {
         var message = ex.getMessage();
         gs.info(message);
      }
   })(current, previous);
   

6. Modify the copied script with your IBM IAM token or App Configuration service credentials' API key and App Configuration instance ID.

7. Navigate to When to run tab and select the Update checkbox.

   

8. Click Submit to save the details.

How to add IBM IAM token or App Configuration service credentials' API key for the webhook script?

Webhook script needs IBM IAM token for the webhook calls or App Configuration service credentials' API key, where you can store the API key to generate the token.

Follow these steps:

1. Login to your ServiceNow instance as an administrator.

2. Click the All tab and search for sys_properties.LIST and press Enter. Alternately, you can go to https://{{instanceid}}.service-now.com/sys_properties_list.do, where instanceid is your ServiceNow instance ID.

   

3. The System properties details gets displayed.

   

4. Click New to create a new system property.

   

5. Add the following details to add the token. Use the password2 type to store the key. This type will encrypt the data and can only be decrypted with the ServiceNow instance.

   

6. Click Submit to save the key in ServiceNow instance. Once saved, you can see that the data is encrypted.

How to add the App Configuration instance ID to ServiceNow system property for the webhook script?

Follow these steps:

1. Login to your ServiceNow instance as an administrator.

2. Click the All tab and search for sys_properties.LIST and press Enter. Alternately, you can go to https://{{instanceid}}.service-now.com/sys_properties_list.do, where instanceid is your ServiceNow instance ID.

   

3. The System properties details gets displayed.

   

4. Click New to create a new system property.

   

5. Add the App Configuration instance ID. Use the password2 type to store the key. This type will encrypt the data and can only be decrypted with the ServiceNow instance.

   

6. Click Submit to save the key in ServiceNow instance. Once saved, you can see that the data is encrypted.