Configuring Applications for the ServiceNow Service Catalog SyncPack

This section describes how to configure this SyncPack to use SL1 to discover ServiceNow devices. This section also explains how to use the SyncPack to place SL1 devices into and out of maintenance mode.

Workflow for Configuring the SyncPack

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

In ServiceNow, you can follow the Guided Setup on the "ScienceLogic Integration with Catalog Request" page to configure ServiceNow and PowerFlow for this SyncPack.

Configuring the ServiceNow MID Server

If you are not using a MID Server, go to Configuring PowerFlow.

Install the MID Server
Configure the Connector Definitions
Configure the Connector Instance
Configure the MID Web Server
Run an external test of the MID Server configuration
Review the MID Server Script Include (ScienceLogic_JS)

Configuring PowerFlow

Create a configuration object in the PowerFlow user interface
Align the new configuration file with the relevant set of PowerFlow applications (depending on whether you use a ServiceNow MID Server)
Configure and Run the Catalog Requirements Sync
Configure the Discovery Sync
Configure the Change Management Sync
Schedule the applications as needed

Configuring the ServiceNow MID Server

If you are not using a MID Server, skip this topic and go to Configuring PowerFlow.

See the following link for instructions on installing and configuring the MID Server for your ServiceNow instance: MID Server installation.

After you set up the MID Server, you can use the following procedures to configure the ServiceNow MID Server to work with the "ServiceNow Service Catalog" SyncPack.

Configuring the Connector Definitions in ServiceNow

To configure the Connector Definitions used by the Update Sender transaction:

Navigate to Event Management > Event Connectors (Pull) > Connector Definitions. The Connector Definitions page appears.
Click New to create a new Connector Definition.

When you create a Connector Definition, ServiceNow creates a template MID Server Script Include with the same name and "_JS" appended at the end of the name. This item is automatically attached to the new record in the JavaScript to run field after you click Submit.
In the Name field, type a unique name and click Submit to save the new Connector Definition record. The Connector Definitions page appears.
Open the Connector Definition you just created and complete the following fields:
- Javascript to run. Attach the JavaScript file provided by the Certified application: ScienceLogic SL1: Event Integration.
- Default schedule (seconds). Specify the time in seconds between retrieval of events, such as "120". This field is not required for this integration specifically, but it is a required field. Events will not be pulled when this is triggered.
- Bi-Directional. Select this option to enable ServiceNow to send Alert changes back to the source instance. Enabling this allows SL1 as an external monitoring system to receive changes made in ServiceNow that are specific to Alerts.
- Alert field identifier. Set to "Message Key". The field causes the source monitoring system to be updated.

In the Connector Parameters section, double-click to add one or more rows using the following parameters to enable correct formatting and communication with the source event system:

Name	Example	Required
application_path	/api/v1/applications/update_sl1_event_from_snow_trigger	No
configuration_path	/api/v1/configurations/ + Configuration Name	Yes
log_level	30 (Default Log level)	No
run_path	/api/v1/applications/run	No
sl1_userid	1 (Default user_id in SL1)	No

The entries that are marked as not required are supplied by default.

Click Submit to save the updated Connector Definition.

Configuring the Connector Instance in ServiceNow

Before you can set up a Connector Instance in ServiceNow, you need to create a ServiceNow credential that will be used by the Connector Instance.

Creating a ServiceNow Credential

To configure the ServiceNow credential that will be used by the Connector Instance:

Navigate to Connections & Credentials > Credentials. The Credentials page appears.
Click New.
Select Basic Auth Credentials. A new Basic Auth Credentials record appears.
Complete the following fields on the new record:

Name. Type a unique name for the credential. Required.
User name. Type the ServiceNow user name.
Password: Type the ServiceNow password.

Click Submit to save the new record.
After the record is saved, open it again and check the Active field on the record.
Click Update.

Configuring the Connector Instance

To configure the Connector Instance:

Navigate to Event Management > Event Connectors (Pull) > Connector Instances.
Click New and complete the following fields on the new record:
- Name. Type a unique name. Required.
  
  The value of the Connector Instance Name must be the same case-sensitive value used in the Source Instance (event_class) field. If the values do not match exactly, the bi-directional connection will not work. In the example below, "ScienceLogic" is the Connector Instance Name. For more information, see External Testing of the MID Server Configuration.
- Connector definition. Confirm that the Connector Definition you created is associated with this Connector Instance record.
- Host IP: Specify the host IP address for PowerFlow.
- Credential. Select the credential for connection to PowerFlow. For more information, see Configuring the ServiceNow Credential.
- Bi-directional. Select this option.

In the Connector Instance Values section, ensure that the values have been configured:

Name	Example	Required
application_path	/api/v1/applications/update_sl1_event_from_snow_trigger	No
configuration_path	/api/v1/configurations/ + Configuration Name	Yes
log_level	30 (Default Log level)	No
run_path	/api/v1/applications/run	No
sl1_userid	1 (Default user_id in SL1)	No

In the MID Servers for Connectors section, select the MID Server.
Click Submit to save the new record.
After the record is saved, open it again and click Test Connector to confirm the correct configuration. This option is only available after you submit the record.
If you have a successful test connection, check the Active field on the record.
Click Update.

Configuring the MID Web Server

To configure the MID Web Server (a MID Server is required for this step):

In ServiceNow, install the Event Management plugin. You can request this plugin directly from ServiceNow.
Navigate to Mid Server > Extensions > MID Web Server. The Mid Web Server Contexts page appears.
Click New and complete the following fields on the new record:

Name. Type a unique name. Required.
HTTP/HTTPS Port: Specify a port number to listen on. The port number must be unique.
Authentication Type: Select Basic. Currently Basic is the only supported Authentication method. Complete the Basic Auth User and Basic Auth User Password fields with the relevant credentials.
Execute on: Select a specific MID Server or Cluster of MID Servers.
MID Server: Specify the MID Server or Mid Server Cluster you will use.

Click Submit to save the new record.

In the Related Links section, the Test parameters option is not a valid test to confirm your setup.

External Testing of the MID Server Configuration

ScienceLogic recommends that you test the MID Server connection by using an external testing source outside of ServiceNow, PowerFlow, and SL1.

Post a message to http://{MID_SERVER_IP}:{MID_Web_Server_port}/api/mid/em/jsonv2

Example body:

{
    "records":
    [ 
    	{
        "source" : "Simulated",
        "event_class": "ScienceLogic",
        "node" : "Postman",
        "type" : "High Virtual Memory",
        "resource" : "C:",
        "severity" : "2",
        "description" : "Test Event",
        "ci_type":"cmdb_ci_app_server_tomcat",
        "message_key": "Postman_109843242",
        "additional_info":{"name":"Create an event in snow"}
    	}
   ]
}

IMPORTANT: The value of the Source Instance (event_class) field must be the same case-sensitive value used in the Connector Instance Name. If the values do not match exactly, the bi-directional connection will not work. In the example above, "ScienceLogic" is the Source Instance (event_class) name. For more information, see Configuring the Connector Instances.

Verify that the Send resulted in an HTTPS Status 200.

The following topics cover how to set up your SL1 instance for the "ServiceNow Service Catalog" SyncPack.

You must install the "ServiceNow Base Pack" PowerPack before you can perform the following procedures. For more information, see Installing the ServiceNow Base Pack PowerPack.

Configuring PowerFlow

The following topics cover how to set up your PowerFlow instance for the "ServiceNow Service Catalog" 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.

Creating an OAuth2 Credential Record in ServiceNow

In order to use OAuth2 for authentication with ServiceNow, you must create an OAuth2 credential record in ServiceNow. To configure the ServiceNow credential that will be used by the Connector Instance:

Navigate to System OAuth > Application Registry. The Application Registries page appears.
Click New.
Select Create an OAuth API endpoint for external clients. A new record appears.
Complete the following fields on the new record:

Name. Type a unique name for the credential. Required.
Client ID. The Client ID is automatically generated by the ServiceNow OAuth server.
Client Secret. Leave this empty. ServiceNow will auto-generate this when the record is saved.
Refresh Token Lifespan. Enter the length of time in seconds the Refresh Token will be valid.
Access Token Lifespan. Type the length of time in seconds that the Access Token will be valid. ScienceLogic recommends setting this to 3,600 seconds to avoid known issues for longer ServiceNow REST interactions.

In a scenario where the Access Token Lifespan value is shorter than the duration of a PowerFlow step that makes multiple REST interactions with ServiceNow, the access token will expire and need to be refreshed. As a result, retries were added to several PowerFlow steps where this issue may occur. This issue will hopefully be addressed in future versions of the Base Steps SyncPack.

Under the Auth Scope section at the bottom of the page, double click Insert a new row.
In the search box that appears, click the magnifying glass icon, select the useraccount record, and click the checkmark icon to save.
Click Submit to save the new record.

Discovery Sync

The Discovery Sync integration lets you use SL1 for discovering ServiceNow devices. With Discovery Sync, you start an SL1 discovery session from ServiceNow and then sync the newly discovered SL1 devices or virtual devices and their data with ServiceNow. You can also use the Discovery Sync to remove devices.

To run a Discovery Sync session:

In PowerFlow, run the "Sync Catalog Requirements" application.
In ServiceNow, configure a service request for Discovery Sync. For more information, see Configuring a ServiceNow Service Request for Discovery Sync.
In PowerFlow , run the applications listed in the Discovery Sync Workflow.

Running the Catalog Requirements Sync

To prepare SL1 and ServiceNow for a Discovery Sync, run the "Sync Catalog Requirements" application in the PowerFlow user interface. This application exports information from SL1 to populate the information in the Discovery Dependent table and ServiceNow request form. You must run this application before you can create a discovery sync or change management session in ServiceNow.

This application uses one or more of the following options from the Configuration pane:

Configuration. Select the relevant configuration object to align with this application. You cannot edit fields that are populated by the configuration object. Required.

The region field is populated by the configuration object you aligned with this application. The region value must match the value in the SL1 Region field in ServiceNow. If you need to update this value, you will need to define the region variable in the configuration object that is aligned with this application, or align a different configuration object that has the correct region value.
snow_request_limit. Specify the number of CIs fetched from ServiceNow in each request. The default is 500 objects per chunk.
read_timeout. Specify the maximum amount of time in seconds the application should wait for a response before timing out. The default is 30 seconds.
sl1_chunk_size. Specify the number of objects to include in each chunk sent from SL1 to ServiceNow. The default is 500.
snow_chunk_size. Specify the number of objects to send in each chunk from ServiceNow. The default is 150 objects per chunk.

TIP: As a best practice, schedule the "Sync Catalog Requirements" application to run every hour or so, depending on your environment.

Configuring a ServiceNow Service Request for Discovery Sync

Before you can run a Discovery Sync, you need to configure the catalog and category values in the ServiceNow service request forms. You also need to activate the "Device Discovery" service request in ServiceNow.

NOTE: Because some of the fields in the service request form will only populate if you have completed the previous fields in the form, you need to complete the fields in the service request form in sequential order.

To configure the ServiceNow service requests for Discovery Sync:

In ServiceNow, go to the Catalog Items page (Service Catalog > Catalog Definitions > Maintain Items).
Type "ScienceLogic" in the Category column. The Device Discovery and Monitoring Removal service requests appear in the search results.
Open the Device Discovery service request and ensure that the Catalogs and Category fields are accurate. For example:

Do not set the Category to a Change Request.

If you need to update these fields, click the Edit in Catalog Builder button at the top of the detail page.
Update the fields and click the Update button to save your changes.
From the Catalog Items page, click the check box for the Device Discovery service request and click the Activate button at the bottom of the Catalog Items window.

This service request is instance-specific, which means that the service request will appear in the same location as the catalogs you specified for that request. In the example above, the Catalog was set to Service Catalog.

Navigate to the relevant catalog for the service request. For example, if you selected Service Catalog for one or both requests, then type "Service Catalog" in the filter navigator, or select Self-Service > Service Catalog to view the new service requests. Type "device discovery" in the Search catalog field to quickly locate the request.
Configure and run the applications listed in the Discovery Sync Workflow before creating the Device Discovery catalog request in ServiceNow.

Discovery Sync Workflow

Sync Service Requests from ServiceNow to SL1. This application sends the request forms to SL1. This application uses one or more of the following options from the Configuration pane:

Configuration. Select the relevant configuration object to align with this application.
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 seconds.
Open_State. The State ID from ServiceNow that specifies which Requested Items (RITMs) to pull and process. The default is 1.
Closed_Success_State. The State ID for a successfully created virtual device. The State ID for a successful run changes from 1 to 2 and then ends with 4. The default is 3.
Closed_Failed_State. The State ID for failed discoveries or failed virtual device creation, usually caused by invalid payloads. The State ID for a failed run changes from 1 to 2 and then ends with 4. The default is 4.
In_Progress_State. The State ID for RITMs for a running discovery. The default is 2.
target_vcug. Leave this field blank.
verify_snow_ssl. Toggle on (blue) this option to enable verification of the SSL certification when you run this application.
recursively_disable_children. Leave this field blank.

Sync Discovery Session Status from SL1 to ServiceNow. This application populates the discovery session logs back to ServiceNow. This application uses the following options from the Configuration pane:

Configuration. Select the relevant configuration object to align with this application. Required.
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 seconds.
retry_max. The maximum number of times that 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_backoff_max.The maximum time interval for the retry_backoff option, in seconds. For example, 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.
Closed_Success_State. The State ID for a successfully created discovery. The State ID for a successful run changes from 1 to 2 and then ends with 4. The default is 3.
Closed_Failed_State. The State ID for failed discoveries, usually caused by invalid payloads. The State ID for a failed run changes from 1 to 2 and then ends with 4. The default is 4.
sys_id_target. Takes the sys_id value from the CI in the ServiceNow Service Request and populates it in the relevant field in SL1, such as c-sys_id.
ci_class_target. Takes the ci_class value from the CI in the ServiceNow Service Request and populates it in the relevant field in SL1, such as c-ci_class_target.

If the sys_id_target field and the ci_class_target field are not populated, PowerFlow will skip the process of consuming cached data and populating custom attribute fields in SL1 with the sys_id and ci_class values of newly discovered devices.
retry_jitter. When selected, instead of using a defined interval between retries, the PowerFlow system will retry the step execution at random intervals. By default, this option is not selected.
retry_backoff. When selected, instead of using a defined interval between retries, PowerFlow will incrementally increase the interval between retries. By default, this option is not selected.
verify_snow_ssl. Toggle on (blue) this option to enable verification of the SSL certification when you run this application.

Sync Discovery Templates from SL1 to ServiceNow. This application creates Service Catalog templates in ServiceNow based on Discovery Sessions that were created in SL1. This option lets you use any existing SL1 Discovery Sessions as a template for discovering or monitoring a CI with SL1. This application uses the following options from the Configuration pane:

Configuration. Select the relevant configuration object to align with this application. Required.
sl1_chunk_size. Specify the number of object to include in each chunk sent from SL1 to ServiceNow. The default is 500.
snow_chunk_size. Specify the number of objects to send in each chunk from ServiceNow. The default is 150 objects per chunk.
template_prefix. Specify the prefix string that PowerFlow will search for in SL1. Any Discovery Sessions that contain that string will be used in ServiceNow to create a service catalog template. The default string is ServiceNow Template:, but you can configure this as needed. In SL1, go to the Discovery Sessions page (Devices > Discovery Sessions) and search for the discovery session or sessions that you want to use as a template. The start of the name in the Name field should match the value in the template_prefix field, above.
read_timeout. Specify the maximum amount of time in seconds the application should wait for a response before timing out. The default is 30 seconds.
verify_snow_ssl. Toggle on (blue) this option to enable verification of the SSL certification when you run this application.

Run all three applications in PowerFlow, in the order listed above. When the applications finish running, PowerFlow sends the status of those applications to ServiceNow.

Creating a Discovery Request in ServiceNow

The Discovery Sync process starts an SL1 discovery session from ServiceNow and syncs the newly discovered SL1 devices and their data with ServiceNow. You can choose to discover standard devices or virtual devices. You can also choose to remove devices that have already been discovered.

To create a discovery request in ServiceNow:

In ServiceNow, go to the Catalog Request page (Self-Service > ScienceLogic SL1: Catalog Automation > Catalog Request). The Describe Needs page will appear.
Select the SL1 environments you would like to initiate device discovery for under Select SL1 PowerFlow platform. You can select multiple environments by holding the "Shift" or "Ctrl" key on your keyboard and then clicking the environments you want to use to discover devices.

Click the right arrow button to add the selected environments to the Selected table.
Click the Choose Options button. The Choose Options page appears.
In the Request Type field, select Discover Device(s) or Create Virtual Device, depending on the type of device you want to discover.
- If you selected Discover Device(s), go to step 5.
- If you selected Create Virtual Device, go to step 6.
If you previously created a catalog item template that contains your device discovery information, select it from the Select Template field.

You can save the current device discovery as a template by checking Save as Template. A template saves all of the discovery settings except for the IP addresses. You can access existing templates on the Catalog Template page in ServiceNow (ScienceLogic > Automations > Catalog Templates).

If you selected Discover Device(s) in the Request Type field, complete the following fields:

IP Address/Hostname Discovery List. Provide a list of IP addresses, hostnames, or fully-qualified domain names for SL1 to scan during discovery:

One or more single IPv4 addresses separated by commas and a new line. Each IP address must be in standard IP notation and cannot exceed 15 characters. For example, "10.20.30.1, 10.20.30.2, 10.20."
One or more ranges of IPv4 addresses with "-" (dash) characters between the beginning of the range and the end of the range. Separate each range with a comma. For example, "10.20.30.1 – 10.20.30.254".
One or more IP address ranges in IPv4 CIDR notation. Separate each item in the list with a comma. For example, "192.168.168.0/24".
One or more hostnames (fully-qualified domain names). Separate each item in the list with a comma.

Credentials. Select one or more SNMP credentials to allow SL1 to access a device's SNMP data and click the right arrow button to add them to the Selected table.
Discover Non-SNMP. Specifies whether or not SL1 should discover devices that don't respond to SNMP requests.
Model Devices. Determines whether or not the devices that are discovered with this discovery session can be managed through SL1.
DHCP. Specifies whether or not the specified range of IPs and hostnames use DHCP. If you select this option, SL1 performs a DNS lookup for the device during discovery and each time SL1 retrieves information from the device.
Device Model Cache TTL (h). Amount of time, in hours, that SL1 stores information about devices that are discovered but not modeled, either because the Model Devices option is not enabled or because SL1 cannot determine whether a duplicate device already exists. The cached data can be used to manually model the device from the Discovery Session window.
Collection Server. Select an existing collector to monitor the discovered devices. Required.
What company is this for?. Specify the company that will use this discovery data. Click the magnifying glass icon to locate a company. The Region field updates automatically based on the company you select.
Add Devices to Device Groups. Select one or more existing device groups to which you want to add the discovered devices.
Apply Device Template . Select an existing device template if needed. As SL1 discovers a device in the IP discovery list, that device is configured with the selected device template.
Initial Scan Level. For this discovery session only, specifies the data to be gathered during the initial discovery session.
Scan Throttle. Specifies the amount of time a discovery process should pause between each specified IP address (specified in the IP Address/Hostname Discovery List field). Pausing discovery processes between IP addresses spreads the amount of network traffic generated by discovery over a longer period of time.
Scan Default Ports. Select this option to scan the default ports: 21,22,23,25,80. If you de-select this option, you can specify a different list of ports in the Custom Port Scan field that appears.
Port Scan All IPs. For the initial discovery session only, specifies whether SL1 should scan all IP addresses on a device for open ports.
Port Scan Timeout. For the initial discovery session only, specifies the length of time, in milliseconds, after which SL1 should stop trying to scan an IP address for open ports and begin scanning the next IP address (if applicable).
Interface Inventory Timeout (ms). Specifies the maximum amount of time that the discovery processes will spend polling a device for the list of interfaces. After the specified time, SL1 will stop polling the device, will not model the device, and will continue with discovery. The default value is 600,000 ms (10 minutes).
Maximum Allowed Interfaces. Specifies the maximum number of interfaces per devices. If a device exceeds this number of interfaces, SL1 stops scanning the device, will not model the device, and will continue with discovery. The default value is 10,000.
Bypass Interface Inventory. Select this option if you do not want SL1 to attempt to discover interfaces for each device in the discovery session.

If you selected Create Virtual Device in the Request Type field, complete the following fields:

Name. Type a name for the virtual device.
Virtual Device Class. Specify the device class of the virtual device. Click the magnifying glass icon to locate any classes aligned with your organization.
Collector Group. Specify the SL1 collector group to use for the Discovery Sync. Click the magnifying glass icon to locate any collector groups aligned with your organization.
What company is this for?. Specify the company that will use this discovery data. Click the magnifying glass icon to locate a company. The Region field updates automatically based on the company you select.

Click the Checkout button. On the Checkout page that appears, make a note of value in the Request Number field.

In the PowerFlow user interface, go to the Applications page and run the "Sync Service Requests from ServiceNow to SL1" application. For more information, see Discovery Sync Workflow.
When the application completes, go to Self-Service > My Requests in ServiceNow.
Click the RITM record link to go to the Requested Item page. The State field should update to Closed Complete and the request should be assigned to itself.
For a standard device discovery, go to ServiceNow and perform the following:

Scroll down to the Activities pane to verify that you have a comment stating the discovery completed.
In SL1, navigate to the Discovery Control Panel page (Registry > Manage > Discovery) and verify that SL1 created a new discovery session with that ID.

For a virtual device discovery, go to ServiceNow and perform the following:

Scroll down to the Activities pane to verify that you have a comment stating "Virtual Device <name> Created with SLID: <new id>":

In SL1, navigate to the Device Manager page (Registry > Device Manager) and verify that SL1 created a new device with that device ID.

TIP: As a best practice, schedule the "Sync Service Requests from ServiceNow to SL1" application to run every hour or so, depending on your environment.

Decommissioning Devices

If you want to quickly select one or more devices in ServiceNow to remove from monitoring (or "decommission") in SL1, you can use the Device Removal option from the Catalog Request form.

You then use the "Sync Service Requests from ServiceNow to SL1" application to decommission the devices that you no longer want to monitor. Running this application takes the list of synced devices in the service request and moves them to an SL1 Virtual Collector Group (VCUG).

If you move a parent device to a new Virtual Collector Group, then all of its children move as well. If you move a child directly, only the child moves.

This feature uses registered events in ServiceNow that are queued to ServiceNow Event Management to trigger actions in PowerFlow. Also, this method is just an example of one of many ways to trigger a registered event. For more information about registered events, including examples of other triggering events you can define in ServiceNow, see ServiceNow Registered Events.

Activating the ServiceNow Service Request for Monitoring Removal

To activate the ServiceNow service request for Device Removal:

In ServiceNow, go to the Catalog Request page (Self-Service > ScienceLogic SL1: Catalog Automation > Catalog Request). The Describe Needs page will appear.
Select the SL1 environments you would like to remove devices from under Select SL1 PowerFlow platform.

You can select multiple environments by holding the "Shift" or "Ctrl" key on your keyboard and then clicking the environments to remove devices for.

Click the right arrow button to add the selected environments to the Selected table.
Click the Choose Options button. The Choose Options page appears.
In the Request Type field, select Device Removal.
Specify the company that will use this discovery data in the What company is this for? . Click the magnifying glass icon to locate a company. The Region field updates automatically based on the company you select.
Under Devices you want to remove from monitoring, select the devices you want to remove. Click the right arrow to move them to the Selected table.
Click the Checkout button. On the Checkout page that appears, make a note of value in the Request Number field.

In the PowerFlow user interface, select the "Sync Service Requests from ServiceNow to SL1" application from the Applications page and click Configure on the application detail page. The Configuration pane appears:
Complete the following fields:

Configuration. Select the relevant configuration object to align with this application. You cannot edit fields that are populated by the configuration object. Required.
read_timeout. Specify the maximum amount of time in seconds the application should wait for a response before timing out. The default is 20 seconds.
recursively_disable_children. Check this option to move all child devices of the devices you are decommissioning to the VCUG. If this option is not checked and a parent device is in the disable request, the parent device will be skipped with a warning message.
target_vcug. Specify the ID of the SL1 Virtual Collection Group (VCUG) you created to hold the devices on the Collector Group Settings page (System > Settings > Collector Groups). If this value is null, the application will attempt to pull the value from the target_vcug field in the "Delete Devices from SL1" application.

Click Save. The Configuration pane automatically closes after this message appears.
Click Run to run the application.

TIP: As a best practice, schedule the "Sync Service Requests from ServiceNow to SL1" application to run every hour or so, depending on your environment.

Configuring Change Management Sync

The Change Management Sync integration lets you configure SL1 to generate an event when a maintenance-related change occurs. The SL1 event contains data about the change request from ServiceNow, including a hyperlink to the ServiceNow change record. The event is aligned with a device in SL1, and if the device is part of a business service in SL1 version 12.2.0 or later, the event displays on the Changes tab for that business service in SL1.

You will need to configure the following PowerFlow applications to run the Change Management Sync:

Create or Update Maintenance Schedule from ServiceNow Trigger
Sync Catalog Requirements
Sync Maintenance Schedules from ServiceNow to SL1Trigger Device Maintenance Updates via MID Server
Update SL1 Event With ServiceNow Change Request Info

Syncing Device Maintenance from ServiceNow to SL1

You can use the following methods to put one or more devices into maintenance mode from ServiceNow to SL1:

Use the "Sync Maintenance Schedules from ServiceNow to SL1" PowerFlow application if you are not using a MID Server, and you want to create a change request in ServiceNow to perform scheduled maintenance through a maintenance window in ServiceNow. For more information, see Scheduling Device Maintenance (No MID Server).
If you are looking to leverage a ServiceNow Management, Instrumentation, and Discovery (MID) Server, there are two separate ways of placing a Device in maintenance:

Use the "Create or Update Maintenance Schedule from ServiceNow Trigger" application to create and cancel maintenance schedules in SL1 from a ServiceNow MID Server trigger. When triggered, the application gathers data about the change request in ServiceNow and generates an SL1 Event with a severity of Notice.
Use the "Trigger Device Maintenance Updates via MID Server" application if you are using a ServiceNow MID Server and you want to immediately enable or disable maintenance on a device.

For more information, see Using a MID Server to Place a Device Directly in Maintenance or Schedule a Maintenance Window.

Viewing SL1 Events for Change Requests

When the "Create or Update Maintenance Schedule from ServiceNow Trigger" application is triggered, the application gathers data about the change request in ServiceNow and generates an SL1 Event with a severity of Notice.

For an SL1 Event that was generated by an update to a change request in ServiceNow, you can click the link for the ticket number in the Ticket External Reference column on the Events page (or click the life-ring icon () in the classic user interface) to go back to the change request in ServiceNow:

For more information about SL1 events, see the Events section.

Viewing Change Events for SL1 Business Services

If you are using SL1 version 11.1.0 or later with the Change Events feature enabled, and the device aligned with the event is in an SL1 Business Service, the event will display on the Change Events tab for that Business Service in SL1:

The Change Events tab displays a list of events that are created when PowerFlow pulls change data from ServiceNow, including both active and cleared change events.

For more information about SL1 Business Services, see the Business Services section.

Scheduling Device Maintenance (No MID Server)

You can create a change request in ServiceNow to perform scheduled maintenance through a maintenance window in ServiceNow. You use the "Sync Maintenance Schedules from ServiceNow to SL1" PowerFlow application to sync maintenance windows from ServiceNow change requests (CHG)s to SL1 devices to place the synced devices into maintenance mode for the scheduled change window.

This process does not require the use of a ServiceNow MID Server.

PowerFlow only syncs maintenance schedules that are aligned with devices that are already synced with ServiceNow. Before setting up maintenance schedule sync, you must first sync devices between SL1 and ServiceNow using the ServiceNow CMDB SyncPack.

When you create a change request (CHG) in ServiceNow and sync it to SL1, the scheduled maintenance that SL1 creates has collections disabled by default. This is not configurable.

The SL1 Scheduler supports maintenance windows of at least one minute or more.

If you update the scheduled times in a ServiceNow change request, you will need to cancel the change request, which also cancels the maintenance window in SL1. You will then need to create a new change request with the new time window and sync that change request to SL1.

To set up maintenance sync:

In ServiceNow, type "change" in the filter navigator and navigate to Change > Create New.
Click New to create a new change request of type "Normal". A new Change Request record appears:

Make a note of the change request number in the Number field. You will use this later to verify that the maintenance sync was created. In this example, the value is CHG0030004.
Update the following fields in the record:

Configuration Item. Select the CI you want to configure for maintenance sync.
Assignment group. Select the group for the CI.

The aligned CI must have the SL1 Monitored field selected before the PowerFlow can use the maintenance schedule for that CI.

Click the Submit button. The change request is saved, and you are returned to the Change Requests page.
Select the change request you just created, and in the change request record, right-click the State label and select Show Choice List. The Choices list displays a list of the configurable choices and values:

You need Administrator privileges to access this list.

Make a note of the values in the Value and Label fields. These values map to the New_Change_Request_State and Canceled_Change_Request_State fields in the "Sync Maintenance Schedules from ServiceNow to SL1" application.
Return to your new change request and scroll down in the change request to the Affected CIs tab, where you can click the Add button to add additional synced CIs to the maintenance sync:

In the PowerFlow user interface, go to the Applications page and select the "Sync Maintenance Schedules from ServiceNow to SL1" application.
Click Configure (). The Configuration pane appears:

As needed, update the following options from the Configuration pane:

Configuration. Select the relevant configuration object to align with this application. You cannot edit fields that are populated by the configuration object. Required.
New_Change_Request_State. The State ID from ServiceNow of the scheduled change request that this application accesses to pull to schedule maintenance windows in SL1.The default is -2.
read_timeout. Specify the maximum amount of time in seconds the application should wait for a response before timing out. The default is 20 seconds.
Canceled_Change_Request_State: The State ID for a canceled change request that this application accesses to pull to schedule maintenance windows in SL1. The default is 4.
New_Change_Task_State: The State ID of the scheduled change task that this application accesses to pull to cancel maintenance windows in SL1. The default is 1.
Canceled_Change_Task_State: The State ID for a canceled change task that this application accesses to pull to cancel maintenance windows in SL1. The default is 4.
Process_Change_Tasks: Select this option to enable change task processing, which allows the request to be broken down into Change Tasks, which results in two extra pulls of the data. The default is unselected.
collection_polling. When selected, leaves synced devices in a collection enabled state after a synced schedule completes. The devices will be put in maintenance but the devices will remain enabled for polling. By default, the devices are left in a collection disabled state.
patch_window. Specifies a patch window from 0 to 60 minutes.

Verify that the value from the New_Change_Request_State field matches the value in the Value field from ServiceNow, and the value from the Canceled_Change_Request_State field matches the value from the Label field from ServiceNow. These values must match for the maintenance sync to work.
Click Save. The Configuration pane automatically closes after this message appears.
Click Run () to run the application.
While the "Sync Maintenance Schedules from ServiceNow to SL1" application runs, you can monitor the status of the maintenance process by clicking the branch icon () on the "Schedule Maintenance" step. Click the triggered application's run ID in the pop-up window, and then click the branch icon on the "Create SL Maintenance" or "Modify Maintenance" steps for more information.
After the "Sync Maintenance from ServiceNow to SL1" application completes, navigate to the Schedule Manager (Registry > Schedules > Schedule Manager) in SL1 to view the change requests.

Verify that the Schedule Summary field contains the same value from the ServiceNow Number field. In this example, the value in SL1 matches the value from ServiceNow: CHG0030004.
You can also verify that the schedule was created for a device by navigating to the Device Manager (Registry > Devices), clicking the wrench icon for the device, and clicking the Schedule tab.
If you want to cancel the scheduled time for the maintenance sync, open the change request in ServiceNow, click the Additional actions menu button (), and select Cancel Change. The next time the "Sync Maintenance from ServiceNow to SL1" application runs, the application cancels that maintenance sync.

TIP: As a best practice, schedule the "Sync Maintenance from ServiceNow to SL1" application to run every hour or so, depending on your environment.

Using a MID Server to Place a Device Directly in Maintenance or Schedule a Maintenance Window

You can use this SyncPack with a ServiceNow MID Server for the following scenarios:

Placing a device directly in maintenance.
Scheduling a maintenance window

To set up either scenario, perform the following:

Configure and run the "Sync Catalog Requirements" application in PowerFlow.
Create a ServiceNow Credential and Credential Affinity in ServiceNow, or

Configure ServiceNow to use an API Key for PowerFlow Authentication

Configuring and Running the "Sync Catalog Requirements" Application in PowerFlow

Prerequisites for the MID Server workflow:

In PowerFlow, open the "Sync Catalog Requirements" application and click the Configure button (). The Configuration pane appears.
This application uses one or more of the following options from the Configuration pane:
- Configuration. Select the relevant configuration object to align with this application. You cannot edit fields that are populated by the configuration object. Required.
  
  The region field is populated by the configuration object you aligned with this application. The region value must match the value in the SL1 Region field in ServiceNow. If you need to update this value, you will need to define the region variable in the configuration object that is aligned with this application, or align a different configuration object that has the correct region value.
- snow_request_limit. Specify the number of CIs fetched from ServiceNow in each request. The default is 500 objects per chunk.
- read_timeout. Specify the maximum amount of time in seconds the application should wait for a response before timing out. The default is 30 seconds.
- sl1_chunk_size. Specify the number of object to include in each chunk sent from SL1 to ServiceNow. The default is 500.
- snow_chunk_size. Specify the number of objects to send in each chunk from ServiceNow. The default is 150 objects per chunk.
Click Save.
Click the Run button. The application syncs the configuration objects from PowerFlow to ServiceNow so that ServiceNow can tell PowerFlow to which SL1 system it needs to send the change request.
In ServiceNow, create a credential for the sync. For more information, see Creating a ServiceNow Credential and Credential Affinity or Configure ServiceNow to use an API Key for PowerFlow Authentication.

You do not need to run or schedule the "Create or Update Maintenance Schedule from ServiceNow Trigger" application or the "Trigger Device Maintenance Updates via MID Server" application in PowerFlow. Those applications are triggered by the MID Server, which is triggered first by a registered event in ServiceNow Event Management. For more information about registered events, including examples of other triggering events you can define in ServiceNow, see ServiceNow Registered Events.

Creating a ServiceNow Credential and Credential Affinity

Before you can set up maintenance sync with the MID Server in ServiceNow, you need to create a credential for the MID Server. You should have access to the "Integration Services" section of the Discovery Dependents page (x_sclo_scilogic_discovery_dependent) in ServiceNow, which is provided by the "Integration Services" import set.

To create a credential to connect to PowerFlow:

In ServiceNow, go to Connections & Credentials > Connection & Credential Aliases.
From the Connection & Credential Aliases list, select ScienceLogic. The Connection & Credential Aliases page appears:

Click New to create a new credential. The Credentials page appears.
From the list of credentials, select Basic Auth Credentials. This is currently the only type of credential that is supported. The Basic Auth Credentials page appears.
Complete the fields related to the PowerFlow on the Basic Auth Credentials page. Make sure that the Credential alias field is set to x_sclo_scilogic.Sciencelogic.

Click Submit. The credential is added to the Connection & Credential Aliases page.
Select the new credential. The Basic Auth Credentials page for that credential appears.
Click New to create a Discovery IP Affinity record. A new Credential Affinity page appears.
Complete the following fields:

MID server. The name of the MID Server you want to use.
IP address. Use the PowerFlow IP address that was listed in the IP field on the relevant record on the Discovery Dependents page in ServiceNow. To quickly find the relevant record on the Discovery Dependents page, right-click the Type column and select Group By Type, and then expand Type: Integration Services. Use the IP value from the record that matches the Region for the devices you want to use.
Credential ID. This field should be completed for you.

Click Submit.

Configuring ServiceNow to use an API Key for PowerFlow Authentication

If you want to use an API key for authentication instead of using the default "isadmin" user, you will need to add an HTTP header to the Integration Services Application Run record in ServiceNow.

In PowerFlow, create an API key on the API Keys page and save the key for step 9, below.
In ServiceNow, go to System Web Services > Outbound > REST Message and search for Integration Services Application Run.
Select the Integration Services Application Run record that is connected to the ScienceLogic SL1: Service Catalog Request Integration in the Application column. The Integration Services Application Run record appears:
In the HTTP Methods section, click IS Application Run.
Click the HTTP Request tab.
If needed, click Insert from the Additional actions menu at the top left of the record.
In the Use MID Server field, select the MID server you want to use.
In the HTTP Headers section, type PF-APIKEY in the Name field.
In the HTTP Headers section, paste the API key from step 1 in the Value field.
Click the Update button in the lower left of the window.

ServiceNow Registered Events

This section describes the commands that you can use to generate registered events in ServiceNow. These events can trigger actions in PowerFlow, such as specifying one or more CIs for monitoring, or putting a CI into maintenance.

This section is recommended for advanced ServiceNow administrators.

These events use the gs.eventQueue command, using the following format:

eventQueue(String name, Object instance, String parm1, String parm2)

For more information about registered events, see the ServiceNow documentation: https://developer.servicenow.com/dev.do#!/learn/learning-plans/quebec/new_to_servicenow/app_store_learnv2_automatingapps_quebec_what_are_events.

Change Request Events

The following events can be triggered to queue to the event manager. The actual trigger for the following events is not included in the application, but you can configure a custom trigger. An example is provided in the Change Request Events Example, below.

Direct to Device: x_sclo_scilogic.device_maintenance

The "Trigger Device Maintenance Updates via MID Server" application receives a group of one or more synced devices from the ServiceNow MID Server and checks for the enable_maintenance and disable_maintenance actions on those devices. If the application encounters devices with one of those actions, it will enable or disable the user maintenance status of those devices as needed.

Command

gs.eventQueue('x_sclo_scilogic.device_maintenance',current, action, affected_ci);

Event Fields

Field	Description
x_sclo_scilogic.device_maintenance	Unique name of the event.
current	The table to which the event applies.
action	Parm1: An array that includes the action to be performed (enable_maintenance or disable_maintenance) and the sys_id of the task. The task is not required; the action is required.
affected_ci	Parm2: An array of device sys_ids that need to be enable or disabled for maintenance mode.

Scheduled Device Maintenance: x_sclo_scilogic.device_maintenance_skd

The "Create or Update Maintenance Schedule from ServiceNow Trigger" application handles scheduling and canceling maintenance schedules in SL1 from a trigger from a ServiceNow Management, Instrumentation, and Discovery (MID) Server.

The "Create or Update Maintenance Schedule from ServiceNow Trigger" receives a group of one or more synced devices from the ServiceNow Management, Instrumentation, and Discovery (MID) Server and checks for the schedule and cancel actions on those devices. If the application encounters devices with one of those actions, it will enable or disable the user maintenance status of those devices as needed.

As a result, in ServiceNow you can bring change requests out of a scheduled state and update them, and all of the updates to those change requests are synced back to SL1 in real time, even if those change requests were already scheduled.

Command

gs.eventQueue('x_sclo_scilogic.device_maintenance_skd',current, 'schedule', current.getUniqueValue());

Event Fields

Field	Description
x_sclo_scilogic.device_maintenance_skd	Unique name of the event.
current	The table to which the event applies.
schedule	Parm1: Accepts the following variables: schedule: Creates a schedule in SL1. cancel: Deletes any currently scheduled maintenance. event: Creates an event in SL1.
current.getUniqueValue())	Parm2: The sys_id of the change request.

Change Request Events Example

There are many different ways to utilize the registered events that are supplied in the certified application. Below is on possible way of triggering by using business rule on the change request table.

Navigate to the change request table and create a business rule:
Configure the Business Rule to trigger when the state of the change request changes to Scheduled or Canceled:

Click the Advanced tab, where you can configure the trigger for the event queue:

This script block is set up to trigger three different times, depending on the state change:

(function executeRule(current, previous /*null when async*/) {
	var scheduled = -2,  //value of the state choice for the scheduled choice (default is -2)
		cancelled = 4, //value of the stae choice for the cancelled choice (default is 4)
		implement = -1;  //value of the state choice for the implement choice (default is -1)
	gs.info("State change for change " + current.state);
	if(current.state.changesTo(scheduled)){
		gs.eventQueue('x_sclo_scilogic.device_maintenance_skd',current, 'schedule', current.getUniqueValue());
	}else if(current.state.changesTo(implement)){
		gs.eventQueue('x_sclo_scilogic.device_maintenance_skd',current, 'event', current.getUniqueValue());
	}else if(current.state.changesTo(cancelled)){
		gs.eventQueue('x_sclo_scilogic.device_maintenance_skd',current, 'cancel', current.getUniqueValue());
	}else{
		return;
	}
	
})(current, previous);