Integrating with ServiceNow

External Workflow

For External workflow, below are the steps to follow.

1. Enter the URL of the ServiceNow instance.

2. Enter the Username to be used for connecting to the ServiceNow instance.

3. Enter the Password to be used for authenticating the Username mentioned earlier to authenticate in the ServiceNow instance.

4. Enter the Client ID needed to retrieve the OAuth access token.

5. Enter the Client secret required for authenticating the Client ID provided earlier.

Client ID and Client secret are required for accessing your ServiceNow instance. For creating a Client ID and Client secret, check the service now documentation on how to create an OAuth API endpoint for external clients.

1. Enter the approval Group Name defined in ServiceNow. The approval Group Name will contain set of people who are authorized to approve the Change Requests created in the ServiceNow workflow.

2. Set the Change request expiration time (in hours). Minimum 1 to maximum 999 hours.

3. Set the Enabled toggle switch to ON to enable the workflow for selected scope.

Only one approval workflow can be created for a resource.

When you create a workflow for an environment, an approval is required for the modification or deletion of the resources in the selected scope during workflow creation (for example, all flags, all properties, or environment deletion).

A change request is created for each action, and the resource cannot be modified or deleted in that environment until the change request is approved. The resource awaiting approval in one environment can still be modified in other environments.

To view your change request, hover over the CR icon next to the resource name being modified. You will see the link to your change request.

For example, if you selected all flags in the scope, toggling a feature flag to the On or Off state in that environment initiates a change request that must go through the approval process.

Feature flags or properties that were already enabled before applying the workflow continue to function normally, but any subsequent modifications require approval. If you disable a feature flag, apply the workflow, and then attempt to enable the feature flag, its status changes to Success! Change request workflow initiated and a change request is created.

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/apis/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
                     //Madrid: https://eu-es.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.