Configuring Applications for the SyncPack

This section describes how to configure PowerFlow application for the "ServiceNow Change Management" SyncPack. You can use this SyncPack to place SL1 devices into and out of maintenance mode.

Creating and Aligning a Configuration Object

A configuration object supplies the login credentials and other required information needed to execute the steps for an application in PowerFlow. 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 create one or more configuration objects in the PowerFlow user interface and align that configuration object to the applications that let you sync data between SL1 and ServiceNow.

Depending on your SL1 and ServiceNow environments, you might be able to use the same configuration object with other ServiceNow SyncPacks.

When either multiple SL1 stacks or multiple ServiceNow systems are involved with PowerFlow, you should create an individual configuration object for each SL1 stack or ServiceNow system. Next, create an individual schedule for each configuration object. Each schedule should use a configuration object that is specific to that single SL1 stack or ServiceNow system. Creating copies of a PowerFlow application from a SyncPack for the purpose of distinguishing between domains is not supported, and will result in issues on upgrades.

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.

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

Aligning a Configuration Object

Before you can run the applications in this SyncPack, you must first "align" a configuration object with the application you want to use.

To align a configuration object with an application:

From the Applications page of the PowerFlow user interface, open the relevant application and click Configure. The Configurations pane for that application appears.
From the Configurations drop-down, select the configuration object you want to use.
Click Save to align that configuration with the application.
Repeat this process for every other application you want to use.

The values for the parameters that display in the Configuration pane with a padlock icon () are populated by the values in the configuration object.

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

Starting with version 3.2.0 of this SyncPack, 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 Change Management 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 Change Management Requirements" Application in PowerFlow

Prerequisites for the MID Server workflow:

In PowerFlow, open the "Sync Change Management Requirements" application and click the Configure button (). The Configuration pane appears.
Update the following fields:
- Configuration. Select the configuration object with the saved credentials for ServiceNow and SL1.
- is_host. Specify the IP of the cluster VIP
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);