Configuring Applications for the Cases SyncPack

This section describes how to configure PowerFlow applications for the "ServiceNow Cases" SyncPack.

With this SyncPack, any changes (except for acknowledgments) made to an SL1 event is sent to ServiceNow to update the corresponding case. Any status changes to the ServiceNow case are synced back to the corresponding SL1 event.

You can also use this SyncPack in conjunction with the "ServiceNow Configuration Management Database (CMDB)" SyncPack to create cases with a linked ServiceNow Configuration Item (CI).

Workflow for Configuring the SyncPack

The following workflows describe how to configure SL1 and PowerFlow to work with the "ServiceNow Cases" SyncPack.

Configuring SL1

Create a ServiceNow credential
Enable the following run book automation policies:

"ServiceNow: [Cases] Add/Update"
"ServiceNow: [Cases] Event Cleared"

Enable and customize the "ServiceNow: Add/Update/Clear Case" run book action policy
Optionally, send custom data to ServiceNow using the passthrough option
Optionally, enable and configure the "ServiceNow: [Cases] Click to Create" policy
Optionally, enable run book automation queue retries

Configuring PowerFlow

Create a configuration object in the PowerFlow user interface
Align the new configuration file with the following PowerFlow applications:

"Create or Update ServiceNow Case from SL1 Event"
"Resolve ServiceNow Case from SL1 Event"
"Sync Case or Incident State from ServiceNow to SL1 Event"

Schedule the PowerFlow applications as needed

Configuring SL1

The following topics cover how to set up your SL1 instance to work with the "ServiceNow Cases" SyncPack.

Creating a ServiceNow Credential in SL1

To configure SL1 to communicate with ServiceNow, you must first create a SOAP/XML credential. This credential allows the run book automations in the "ServiceNow Base Pack" PowerPack to connect with your ServiceNow instance. These run book automations are responsible for sending the SL1 event data to PowerFlow, which ultimately sends the data to ServiceNow.

The ServiceNow RBA - Example credential from the "ServiceNow Base Pack" PowerPack is an example SOAP/XML credential that you can configure for your own use.

To configure the ServiceNow RBA - Example credential:

In SL1, go to the Credential Management page (System > Manage > Credentials).
Locate the ServiceNow RBA - Example credential and click its wrench icon (). The Edit SOAP/XML Credential page appears.

Complete the following fields:

Profile Name. Type a new name for the ServiceNow credential.
Timeout. Leave as the default of "5000" ms.
Content Encoding. Make sure text/xml is selected.
Method. Make sure POST is selected.
HTTP Version. Select http/1.1.
URL. Type the URL for your PowerFlow instance.
HTTP Auth User. Type the username of your PowerFlow instance.
HTTP Auth Password. Type the password of your PowerFlow instance.

Click Save & Close. The credential is added to the Credentials page
On the Credentials page, make a note of the value in the ID column for the credential you just created. You will use this value with the sl1_credential_id parameter when you enable the snippet code of the "ServiceNow: Add/Update/Clear (Case/Event/Incident)" run book action policy.

Enabling the Run Book Automation Policies

Versions 104 and later of the "ServiceNow Base Pack" PowerPack separated these run book action policies by Cases, Events, and Incident, such as "ServiceNow: [Cases] - Add/Update".

Before you can run the "ServiceNow: Add/Update/Clear Case" run book action, you must enable the two case-specific run book automation policies in SL1:

ServiceNow: [Cases] - Add/Update
ServiceNow: [Cases] - Event Cleared

To enable the run book automation policies:

In SL1, go to the Automation Policy Manager page (Registry > Run Book > Automation).

Locate the "ServiceNow: [Cases] - Add/Update" automation policy and click its wrench icon (). The Automation Policy Editor page appears.

Update the following fields:

Policy State. Select Enabled.
Policy Priority. Select High to ensure that this PowerFlow automation policy is added to the top of the queue.
Available Actions. If it is not already selected, select "ServiceNow: Create, Update, Clear Incident or Event".

By default, the "ServiceNow: [Cases] Add/Update" automation policy will create ServiceNow Cases for all devices. You can limit the devices affected by making changes to the Organization, Severity, Match Logic, Aligned Devices, and/or Aligned Events fields.

ScienceLogic highly recommends that you do not make changes to the Policy Type, Repeat Time, or Align With fields or the And event is NOT acknowledged setting.

Click Save.
Repeat steps 2-4 for the "ServiceNow: [Cases] - Event Cleared" run book automation policy.

Enabling and Customizing the Run Book Action Policy

The "ServiceNow: Add/Update/Clear Case" run book action policy contains snippet code that you can customize to use with the "ServiceNow Cases" SyncPack. You edit these values in the Input Parameters pane of the Actions page for this policy.

For example, you can choose to let PowerFlow create both an incident and a case in ServiceNow when an SL1 event is created, or you can choose to have PowerFlow create just an Incident when an SL1 event is created. You can edit this setting with the proactive parameter, which is described in the "Customizing the Snippet Code in the Input Parameters Pane" section, below.

Make sure you are using the most recent version of the run book action policy. If there are two policies with the same name, always use the policy with the higher number in the ID column of the Actions page.

Be sure to schedule the "Cache SL1 Users" PowerFlow application to run at least once a week to ensure that the user cache has the most recent data.

To enable and customize the Case run book action policy:

In SL1, go to the Actions page (Registry > Run Book > Actions).
Locate the ServiceNow: Add/Update/Clear Case policy and click its wrench icon (). The Action Policy Editor page appears:

For the Action State filed select Enabled.
For the sl1_credential_id field in the Input Parameters pane, specify the credential ID from the ID column on the Credential Management page (System > Manage > Credentials). For example: "sl1_credential_id": "101"
Edit the snippet code as necessary, using the information in the Customizing the Snippet Code in the Input Parameters Pane section, below.
When you are finished, click Save.

Customizing the Snippet Code in the Input Parameters Pane

SL1 run book action snippets are written in Python. In the event of a syntax error, the policies will no longer run. As a result, you must ensure that all edits adhere to Python standards. True and False options are case-sensitive and must not contain quotes.

You can customize the following values in the "ServiceNow: Add/Update/Clear Case" run book action snippet code:

sl1_credential_id. Specifies the ID of the credential object. You can find this value in the ID column of the Credentials page (Manage > Credentials of SL1. For example: "sl1_credential_id": "41"
debug. A true/false value that determines if the action is logged in SL1 and if the application is run in Debug Mode on PowerFlow. Troubleshooting logs are written to /data/tmp/servicenow_rba.log.
configuration. Specifies the ID of the configuration object used on PowerFlow. The configuration ID is all lower-case, with spaces in the configuration object "friendly" name replaced by underscores. For example: "configuration": "docs_config"

NOTE: To find the configuration ID with the API, make a GET request on this endpoint: https://<powerflow_hostname>/api/v1/configurations.

queue. Specifies the worker queue on which the application runs. Leave this as default.
integration. Specifies the SyncPack you are using for this run book action. For example: "integration": "cases".
discard_if_no_ci. Specifies whether PowerFlow should create cases in ServiceNow for devices that do not have a matching CI record. Your options include:

true. If a device is not mapped to a CI, PowerFlow will not create a case in ServiceNow, and SL1 is not updated. The following log message appears: "No CI found".
false. If a device is not mapped to a CI, PowerFlowwill create a case in ServiceNow and update SL1. The default is false.

proactive. Creates both a Case and an Incident in ServiceNow when an SL1 Event is created, or creates just a Case when an SL1 Event is created. If a Case or Incident is assigned in ServiceNow, the SL1 Event will be acknowledged. Users will be matched first on username, then email, then first and last name. The default is "true".

true. Specify "true" if you want to create both a Case and an Incident in ServiceNow. This option creates an "External Ticket" link for the SL1 Event that opens the corresponding Case in ServiceNow. If an Event has a Case in ServiceNow, the case status will be populated; if not, the Incident status will be populated. If a Case or Incident is assigned in ServiceNow, the SL1 Event will be acknowledged.
false. Specify "false" if you only want to create an Incident in ServiceNow. This option creates an "External Ticket" link for the SL1 Event that opens the corresponding Incident in ServiceNow.
If you change the proactive value from true to false after initial configuration and you have active Cases, the External Ticket link for the SL1 Event will continue to link to the Case record in ServiceNow. To avoid this situation, ensure that all synced Cases are Closed or Inactive before changing the proactive value. The External Ticket link will only be updated to the Incident record for new SL1 Events.

Customizing Logging in the Run Book Action

You can customize the following logging-related items in the "ServiceNow: Add/Update/Clear Case" run book action snippet code:

logfile = /data/tmp/ServiceNow_add_update_clear_incident.log

Location for logging output.
Will be created if it does not exist.
Will be appended with each Run Book job.
Is case-sensitive.

do_debug_logging = True

True is on, False is off.
Is case-sensitive.
For troubleshooting, these can be enabled or changed.
Writes logs to /data/tmp/servicenow_rba.log.

Sending Custom Data to ServiceNow Using the Passthrough Option

You can use the "ServiceNow: [(Cases/Events/Incidents)] Add/Update" run book automation and the "ServiceNow: Add/Update/Clear (Case/Event/Incident)" run book action to "pass through" custom data about SL1 cases, events, or incidents to ServiceNow (depending on the SyncPack you are using with PowerFlow).

For example, you might want to use the passthrough functionality to overwrite the impact and urgency of a ServiceNow incident, which is the only way to change the priority of the incident.

To pass custom data to ServiceNow:

Create a new run book action that pulls the relevant data and adds it to a dictionary called EM7_RESULT.
Add the new run book action to the "ServiceNow: [(Cases, Events, or Incident)] Add/Update " run book automation Policy, ahead of the "ServiceNow: Add/Update/Clear (Case/Event/Incident)" run book action so that the new action runs first, and then is consumed by the ServiceNow action.

Passing Custom Data to ServiceNow

The following procedure describes how to configure the passthrough functionality, using the "ServiceNow: [Incident] Add/Update" run book automation and the "ServiceNow: Add/Update/Clear Incident" run book action as examples.

To pass custom data to ServiceNow:

In SL1, go to the Actions page (Registry > Run Book > Actions) and click Create to create a new run book action policy.
Complete the following fields:

Action Name. Type a unique name for the action.
Action State. Select Enabled.
Action Type. Select Run a Snippet.
Execution Environment. Select ServiceNow Base Pack.
Complete the other fields as needed, or leave them at their default settings.

In the Snippet Code pane, add the snippet code you want to include for the EM7_RESULT dictionary. For example, the following snippet code lets you override the ServiceNow Incident work notes with a hardcoded note:

EM7_RESULT = {"work_notes": "This is a new note"}

Additional notes about the structure of the EM7_RESULT dictionary:

EM7_RESULT = is required for the dictionary, and the formatting of the keys should match the example above.
All keys defined in the EM7_RESULT dictionary need to map to field IDs on the ScienceLogic Events table in ServiceNow.
You can hard-code the values in the EM7_RESULT dictionary, or you can use variables and functions, like the "Snippet Code Example", below.
As a best practice, avoid sending null passthrough values to ServiceNow. If you must send 'null' or 'NULL' values to ServiceNow, pass through that value as an empty string, such as "location":"". Also, only pass through values that you need. For example, instead of sending {"location": "", "work_notes": "stuff"}, simply send {"work_notes": "stuff"}.
A long snippet might delay the ticket being created

Click Save.
Go to the Automation Policy Manager page (Registry > Run Book > Automation) and open the "ServiceNow: Add/Update Incident" run book automation Policy.

In the Available Actions section, add the new run book action before the "ServiceNow: Create, Update, Clear Incident" run book action:

The output of this new run book action will be consumed by the "ServiceNow: Create, Update, Clear Incident" run book action, ensuring that the EM7_RESULT dictionary is passed through to ServiceNow. The "ServiceNow: Create, Update, Clear Incident" run book action automatically populates the passthrough values with any values from EM7_LAST_RESULT. The passthrough overwrites any other previously defined fields, such as assignment group.

You can add additional run book actions to the run book automation Policy for any additional workflows that you might want to run. The Automation Policy execute these Actions in a sequential, top-down order. However, the "ServiceNow: Create, Update, Clear Incident" run book action only consumes the EM7_RESULT dictionary from the run book action directly above it.

Passthrough Example

For the Dictionary Entry of the ServiceNow field on the import table, you can reference the XML of the record. You will need to copy the <sys_name> value so you can use that as the key for the passthrough.

In this example, you want to bring in an additional field called sl1 category.

Create the new sl1 category field on the import table in ServiceNow. You can right-click on the header of the form to view the XML:
Look for the <sys_name> value.
Copy that value directly out and use that in your EM7_RESULT for the passthrough value (in the Snippet Code pane):

EM7_RESULT = {'sl1 Category': 'test'}

Snippet Code Example

The following snippet code example shows how to pull additional information and make it available for passthrough. All of the additional information that is going to be sent is contained in a dictionary variable called EM7_RESULT. You can pass through multiple items through in a single run book action by adding additional keys to the EM7_RESULT dictionary.

This example lets you assign assignment groups to an Incident based on certain criteria, such as event policy IDs:

from future.utils import iteritems

def invert_mappings(mappings):
    """
    Invert received one-to-many mappings and converts it into a one-to-one
    mapping.

    Args:
        mappings (dict): Dictionary of mapped values

    Returns:
        dict: inverted dictionary.

    """
    inverted_mappings = dict()
    for key, values in iteritems(mappings):
        for sub_value in values:
            invert_mappings[sub_value] = key
    return inverted_mappings


# Example of assignment group to list of event policy ids mapping.
assignment_groups_to_event_policies = {
    "sys_id_1": [1, 2, 3, 4, 5],
    "sys_id_2": [6, 7, 8, 9, 10],
}
# which sys_id to use if the current event_policy_id isn't mapped
default_sys_id = "sys_id_3"

# invert the mappings
event_policy_to_assignment_group = invert_mappings(assignment_groups_to_event_policies)

# Send assignment group sys_id to IS RBA
EM7_RESULT = {
    "assignment_group": event_policy_to_assignment_group.get(
        EM7_VALUES["%3"], default_sys_id
    )
}

Configuring the "ServiceNow: [Cases] Click to Create" Automation Policy

The "ServiceNow: [(Cases/Events/Incident)] - Click to Create" automation policy lets you manually create a case, event, or incident in ServiceNow by clicking the Actions button () in SL1 for an event and selecting "Create External Ticket" (or by clicking the life-preserver icon () for an event in the classic user interface).

This run book action policy is available in the "ServiceNow Base Pack" PowerPack.

To configure the "ServiceNow: Click to Create" run book action policy:

In SL1, go to the Behavior Settings page (System > Settings > Behavior) and set the Event Console Ticket Life Ring Button Behavior option to Create/View External Ticket.
Click Save to save your changes. You might need to log out of SL1 and log back into SL1 for the changes to update.
Go to the Automation page (Registry > Run Book > Automation).
Locate the "ServiceNow: (Cases/Events/Incident) - Click to Create" policy and click its wrench icon (). The Automation Policy Editor page appears:
Update the following fields:

Policy State. Select Enabled.
In the Criteria Logic section, select and external ticket IS requested in the fifth drop-down. Leave the other values in this section at their default settings.
Repeat Time. Specify the frequency at which SL1 should execute the automation policy while the conditions are still met. The choices range from "every 30 seconds until satisfied" to "every 2 hours until satisfied", or "only once". By default, the policy only runs once.
Available Actions. If it is not already selected, select ServiceNow: Send to PowerFlow: ServiceNow: Add/Update/Clear Incident and add it to the Aligned Actions field.

Click Save. The "Click to Create" feature is now available on the Events and Event Investigator pages.

Enabling Run Book Automation Queue Retries

You can enable run book action (RBA) queue retries to keep from losing any data if PowerFlow is unavailable. Those pending PowerFlow applications are added to an RBA queue that you can access to retry the applications that failed.

For more information, see Enabling Run Book Automation Queue Retries.

Configuring PowerFlow

The following topics cover how to set up your PowerFlow instance to work with the "ServiceNow Cases" SyncPack.

Creating and Aligning a Configuration Object in PowerFlow

A configuration object supplies the login credentials and other required information needed to execute the steps for a PowerFlow application. The Configurations page () of the PowerFlow user interface lists all available configuration objects for that system.

You can create as many configuration objects as you need. A PowerFlow application can only use one configuration object at a time, but you can use (or "align") the same configuration object with multiple applications.

To use this SyncPack, you will need to use an existing configuration object in the PowerFlow user interface or create a new configuration object. Next, you need to align that configuration object to the relevant applications that are triggered by the Run Book Actions in SL1.

Depending on your SL1 environment and the third-party environment with which you are syncing data, you might be able to use the same configuration object with more than one SyncPack.

Creating a Configuration Object

For this SyncPack, you can make a copy of the "ServiceNow SyncPack" configuration object, which is the sample configuration file that was installed with the "ServiceNow Base" SyncPack.

The "ServiceNow SyncPack" configuration object contains all of the required variables. Make a copy of the configuration object and update the variables from that object to match your SL1 and ServiceNow settings.

To create a configuration object based on the "ServiceNow SyncPack" configuration object:

In the PowerFlow user interface, go to the Configurations page ().
Click the Actions button () for the "ServiceNow SyncPack" configuration object and select Edit. The Configuration pane appears:

Click Toggle JSON Editor to show the JSON code. Click the button again to see the fields.

Click Copy as. The Create Configuration pane appears.

This step is required. Do not use the original configuration object to run PowerFlow applications.
Complete the following fields:

Friendly Name. Name of the configuration object that will display on the Configurations page.
Description. A brief description of the configuration object.
Author. User or organization that created the configuration object.
Version. Version of the configuration object.

In the Configuration Data field, include the required block of code to ensure that the applications aligned to this configuration object do not fail:
```
{
   "encrypted": false,
   "name": "<sl1_db_host>",
   "value": "${<config.sl1_host>}"
}
```
For example:
```
{
   "encrypted": false,
   "name": "sl1_db_host",
   "value": "10.2.11.42"
}
```
If you are using IPv6 for IP addresses, wrap the IP string in brackets, such as https://[2001:db8:3333:4444:5555:6666:7777:8888]

Click Toggle JSON Editor to show the JSON code. Click the button again to see the fields. You can also click Add Value and add a new name-value pair in the Configuration Data Values section.

If you are using SL1 with an External Database (SL1 Extended architecture or a cloud-based architecture), update the "value" of that block of code to be the host of your database. This field accepts IP addresses. For example: "value": "db.sciencelogic.com". If you are not using the SL1 Extended architecture or a cloud-based architecture, you do not need to make any changes to the block of code other than pasting the code into the configuration object.

In the Configuration Data Values field, update the default variable definitions to match your PowerFlow configuration.

The region value is a user-defined variable that identifies your SL1 instance within ServiceNow.

To create a configuration variable in the JSON Editor, define the following keys:

encrypted. Specifies whether the value will appear in plain text or encrypted in this JSON file. If you set this to "true", when the value is uploaded, PowerFlow encrypts the value of the variable. The plain text value cannot be retrieved again by an end user. The encryption key is unique to each PowerFlow system. The value is followed by a comma.
name. Specifies the name of the configuration file, without the JSON suffix. This value appears in the user interface. The value is surrounded by double-quotes and followed by a comma.
value. Specifies the value to assign to the variable. The value is surrounded by double-quotes and followed by a comma.

If you want to use OAuth2 for authentication with ServiceNow, complete the following Configuration Data Values fields:

snow_oauth_client_id. Enter the OAuth2 Client ID from ServiceNow.
snow_oauth_client_secret. Enter the OAuth2 Client secret from ServiceNow.
snow_oauth_token_url. Enter the full authentication URL, including host and protocol from ServiceNow. For example, "https://<test-instance-name>.service-now.com/oauth_token.do"
snow_auth_method: Enter oauth or http_basic. If no value is provided, http_basic will be used for connection.

The configuration options listed above are included by default with the sample configuration object provided in the "ServiceNow Base" SyncPack. The configuration options are only required in the configuration object if you plan to use OAuth2 to authenticate. If the values are not present in the configuration object, normal "http_basic" authentication will be used.

Click Save. You can now align this configuration object with one or more applications.

Aligning a Configuration Object and Configuring PowerFlow Applications

To run Case Sync, you must "align" the configuration object to run with the following PowerFlow applications:

Cache SL1 Users
Create or Update ServiceNow Case from SL1 Event
Resolve ServiceNow Case from SL1 Event
Sync Case or Incident State from ServiceNow to SL1 Event

If you want to link cases with ServiceNow Configuration Items (CIs), you will need to run the "Sync Devices from SL1 to ServiceNow" application from the ServiceNow CMDB SyncPack. If this is the first time you are running Case Sync, you will need to run the "Sync Devices from SL1 to ServiceNow" application twice to build the internal cache. For more information, see Running a Device Sync in the ServiceNow CMDB SyncPack section.

To align the configuration object with the relevant PowerFlow applications:

On the Applications page of the PowerFlow user interface, open one of the PowerFlow applications listed above and click Configure. The Configurations pane for that application appears:

From the Configurations drop-down, select the configuration object you want to use.

The values for eventDetails and the other parameters that appear in the Configuration pane with a padlock icon () are populated either by the configuration object you aligned with the application or by the Run Book Action. Do not modify these values. If you encounter an error, make sure your Run Book Action is configured properly.
If needed, edit the retry values:

retry_max. The maximum number of times PowerFlow will retry to execute the step before it stops retrying and logs a step failure. For example, if retry_max is 3, PowerFlow will retry after 1 second, then 2 seconds, then 4 seconds, and stop if the last retry fails. The default is 0.
retry_jitter. Instead of using a defined interval between retries, the PowerFlow system will retry the step execution at random intervals. The default is unselected.
retry_backoff. Instead of using a defined interval between retries, PowerFlow will incrementally increase the interval between retries. The default is unselected.
retry_backoff_max.The maximum time interval for the retry_backoff option, in seconds. For example, This means, if you have retry_max set to 15, the delays will be 1, 2, 4, 8, 16, 32, 64, 120, 240, 480, 600, 600, 600, 600, and 600. The default is 600.
read_timeout. Specify the maximum amount of time in seconds that the application should wait for a response before timing out. The default is 20.

Do not update any of the other parameters on the Configuration pane for any of these PowerFlow applications related to Case Sync. These values are updated by the "ServiceNow: Add/Update/Clear Case" Run Book Action.

Click Save to align that configuration with the application.
Repeat this process for the other PowerFlow applications. The "Cache SL1 Users" application is in the "System Utils" SyncPack.

Scheduling PowerFlow Applications

ScienceLogic recommends that you schedule the following PowerFlow applications:

"Cache SL1 Users": at least once a week
"Sync Case or Incident State from ServiceNow to SL1 Event": every 60 seconds

Do not schedule the "Create or Update ServiceNow Case from SL1 Event" application or the "Resolve ServiceNow Case from SL1 Event" application. These applications should only be triggered by Run Book Automations.

For more information about scheduling applications, see Scheduling a PowerFlow Application.