For integration into ServiceNow, CLIP offers two different methods that use different APIs:

• The preferred option is to use the "Scoped App" for CLIP from the ServiceNow App Store. It contains the Web Service endpoint, transform map, business rules, scripts, menus etc. used by CLIP to create incidents and trigger incident updates to be reported back to CLIP and the data source (backsync).
• the "direct" integration into ServiceNow without the use of the "Scoped App" directly creates incidents, events, etc. in ServiceNow by accessing the respective tables. This type of integration can be achieved without installing an app into ServiceNow, Backsync can be achieved by polling ServiceNow.

Both approaches have advantages and disadvantages. The following recommendations should help in deciding whether to use CLIP with or without "Update Set" / "Scoped App":

Integrate into ServiceNow with Clip by means of the "Scoped App" if

• it is necessary to do further customizations or implement logic within ServiceNow before an incident is created (i.e. run business rules and transform map scripts)
• asynchronous backsync is required (all ticket changes will be transferred to Clip immediately)
• high numbers of open tickets created by CLIP are expected

Use CLIP's option to directly integration into ServiceNow without using the "Scoped App" if

• your company policies refuse to apply additional configurations to your ServiceNow instance for an integration
• it is not expected to have high numbers of open tickets created by CLIP that need to be synchronized
• no customizations have to be done within ServiceNow and a basic mapping in the ClipConfig.xml is sufficient
• a simpler approach is favored because no maintenance is necessary on ServiceNow release changes

Please continue the configuration of CLIP with either following the section "Configuring ServiceNow Targets" with either "Scoped App" or direct.

Supported Versions

Please assure that the system you intend to integrate meets the version requirements outlined in the table below.

Using the “Scoped App”

To configure a Clip target of type "ServiceNow" using the "Scoped App", the following steps need to be performed:

1. Configure a target of type "ServiceNow" in ClipConfig.xml and specify at least the basic settings: the URL and authentication info for Clip to log into ServiceNow.
2. Install AppLink's CLIP App from the ServiceNow app Store into your ServiceNow instance
3. Create an integration user in ServiceNow that owns the "Clip" role
4. For backwards synchronization, you need to configure the Clip properties in ServiceNow

Each of these four steps is described in its own subsections:

System Preparation

Install the Clip “App” into ServiceNow

In this step, the Clip "App" is installed intoServiceNow. This is achieved by

1. contacting us via ServiceNow's app Store
2. AppLink approval for your request
3. Installation of the Clip App in ServiceNow

To contact us, please visit the ServiceNow app Store at https://store.servicenow.com and find AppLink's certified CLIP app by e.g. searching for "AppLink", then click on "Contact Seller":

Once AppLink has approved your request, please click on „Get" and then accept the Terms & Conditions to get the app from the app store.
As an alternative to install the "App" via the ServiceNow App Store, the App can be installed by uploading an "Update Set" which is contained in an XML file contained in Clip. Please note that it is recommended to install the app via the ServiceNow app store as documented in the previous section – the import of the CLIP "Update Set" as described here is just for the purpose if using the app is not possible for some reason or a quick solution is needed.
To upload the CLIP "Update Set", please logon to ServiceNow with a user that has "admin" privileges:

• in the ServiceNow menu, select "System Update Sets -> Retrieved Update Sets" and then click the link "Import Update Set from XML" (Please note that you can find ServiceNow menues easily by typing some letters e.g. "upd" into the "filter navigator field).
• In the "Choose file to upload" entry field, choose and upload the file for your ServiceNow version (e.g. when installing into ServiceNow "Madrid", the <version> String should contain "M"):

[Clip]\apache-tomcat\ webapps\Clip\conf\Clip_for_ServiceNow_ScopedApp_<version>_US.xml

• The update set has the state "Loaded". Click on the name of the update set to see the details
• Click the button "Preview Update Set" so the Window "Update Set Preview" shows up
• Click the button "Commit Update Set"

To verify that the Clip application for ServiceNow has been uploaded successfully, please display the Clip application "AppLink CLIP Integration":
The menu provides access to the following items:

• Properties - configure properties for ServiceNow Backsync
• Webservice Endpoint / Outbound – Web Services for inbound and outbound communication
• Transform Map - Mapping between the web service import set to the target incident.
• Incidents - All incidents that originated from Clip.
• Business Rules - business rule used to send ServiceNow to Clip update commands
• Script Includes - script objects for Backwards communication from ServiceNow to Clip
• Contact Support: Link to AppLink Web site
• Output Log: displays filtered logging information

If you choose an item from the menu (i.e. the properties page) the following message will occur on top of the page:

Please choose "Switch to Clip" in order to activate the scoped application Clip.

Create an “Integration User” in ServiceNow

It is recommended to configure a dedicated integration user for Clip which has the "Clip" role assigned to perform insert and update operations. Updates of ServiceNow incidents performed by other users can then easily be identified and pushed back to Clip. Updates performed by Clip itself will not be subject to be pushed back to Clip.
In the ServiceNow menu, select "User Administration > Users">"New" and fill in the fields:

• "User ID": e.g. "clip"
• "First name": "Clip"
• "Last name": "Integration Platform"
• "Password"

The integration user "clip" to be used by Clip as the "sending" system furthermore must have the proper rights to create and update data via the Web Service endpoints that are part of the Clip import set and that act as an import table to ServiceNow.
After creation uf the integration user, edit its users roles and assign the role "x_algh_clip.clip_integration" – to select the role, enter "x" in the "Collection filter field":

Please note that in order to view the incidents created by the integration user the "itil" role has to be provided.

Granting access rights to integration user without Clip App

If you prefer to not use the Clip App so the user role "x_algh_clip.clip_integration" is not present in your ServiceNow instance, the integration user must be granted some access right manually so Clip can do insert and update operations.
However, during implementation phase of Clip you might want to assign full admin rights to the integration user's account, so you are also able to login with this account and customize transform maps, scripts etc.:

• Click "admin" in the "Collection" listbox and then "Add" and "Save" to add the "admin" role to user "hpbsm".
• No Access Control Rules need to be configured.

In production, you can restrict the integration user account to only the roles that are required to insert and update data in CLIP's import table:

• Give the user the "soap" role, which will inherit all soap-related roles
• Give the user the "import_transformer" role

Additionally, the following Access Control Rules must be configured ( "System Security" -> Access Control (ACL) -> Access Control -> "New

• • Type "Record"
  • Operation "Create"

  • Name: "HPBSM [u_hpbsm]"

  • No field selection, i.e. "—NONE --"
  • "Submit"
  • Repeat the steps above for Operation "Read", "Write" and "Delete".

Configuring the Clip properties in ServiceNow

In this step, the Clip properties for the backwards synchronization are configured.
In the ServiceNow App "AppLink CLIP Integration", please select "Properties":

Please configure the following settings:

• URL for the CLIP WebService for backwards communication:

Correct the suggested URL https://clipserver.company.com:9090/Clip/modws by changing the protocol, clip server name and port.

• MID-Server to use for backwards synchronization

If backwards synchronization should be handled by a ServiceNow MID-Server please select the mid server here.
If the App was just installed, the list of mid servers might need an update, this is performed by this procedure:
Right click on "Configure the MID-Server to use for backwards synchronization." property and select Edit Property, then clear the choices and value in the property and update it

• Outbound user and password:

Keep the default "admin" / "admin", or enter your user and password.

• Name of the Clip Server Target:

In the standard configuration, leave the setting "ServiceNow" unchanged

• Integration User configured in ClipConfig.xml for Clip to login into ServiceNow:

In the standard configuration, leave the setting "hpbsm" unchanged ( it was configured in a previous step ). This user is used to filter ServiceNow incident changes for backsync: modifications initiated by Clip via this user will be blocked for backsync.

• Debugging

In the standard configuration, uncheck the debugging option

Clip Target Configuration

On the Clip Server, edit the configuration file conf/ClipConfig.xml:

The following attributes have to be set in the ServiceNow target definition:

• "name" Attribute of the target tag. The name of the ServiceNow Target is used to report back ServiceNow incident changes to the Clip server via a ServiceNow business rule. For a standard integration, leave the default value "ServiceNow" unchanged.
• If upgrading Clip from former versions that used SOAP as a communication style, the attribute useSOAP has to be set to true: useSOAP="true". SOAP communication style will be unsupported in next versions of Clip, so we recommend to switch to REST communication which is the default ( useSOAP="false).
• The "retryIntervalSecs" attribute defines the time interval for the Clip server to retry a connection to this target if the connection is lost.
• "url" Attribute in the ServiceNow Tag. Type in the URL for your ServiceNow server
• "user" Attribute of the "snTarget" Tag. Type in the user name to log on to the ServiceNow Server. For a standard integration, leave the default value "hpbsm" unchanged.
• "passwd" Attribute of the "snTarget" Tag. Type in the password to log on to the ServiceNow Server. The password can be entered in clear text or as an encrypted value. To encrypt the password, use the password encryption in the "Configuration" tab of the Clip Web interface:

• Proxy settings: if outbound communication from Clip to ServiceNow needs to be established via a proxy server, the following settings need to be configured. Please note that when changing proxy related settings, the CLIP service needs to be restarted, a "Reload Config" in the GUI does not make the new settings effective:
  • useProxy: to use a proxy, set "useProxy" to "true"
  • proxyHost: please specify the hostname of the proxy server
  • proxyHostsExcluded: this optional attribute can be used to specify hosts which CLIP should not connect to via the proxy. Please note that if a proxy is used ( i.e. useProxy="true" ), this proxy is used for all connections that CLIP initiates, also for connections to OMi or NNMi. If connections to OMi or NNMi must not be initiated via the proxy, you have to use this attribute to exclude these hosts. The value for this attribute allows wildcards. As an example, if connections to all hosts in the domain "applink.de" should not use the proxy, set this attribute to : proxyHostsExcluded="*.applink.de"
  • proxyPort: port to connect to the proxy server
  • proxyUser: username to login into the proxy server
  • proxyPassword: password for "proxyUser" to login into the proxy server. The password can be entered in clear text or as an encrypted value. To encrypt the password, use the password encryptor in the "Configuration" Tab of the Clip Server Web interface
• drilldownURL: the drilldown URL specifies how an event or incident of this target can be opened in a web browser. It is used in the Clip web GUI in the incident list to provide a quick link to the incident.
• The tag "incidentDescription" defines a pattern that is used to generate a descriptive text for an incident in the Clip Web GUI
• The "trustAllCerts" attribute should be used for testing and debugging purposes only. If set to "true", Clip will accept all SSL certificates even invalid ones.

Create and update settings

This section describes how an OMi event and its attributes are mapped to a ServiceNow incident. For a standard integration, these settings do not need to be modified – for an out-of-the-box integration, please continue with section "Uploading CLIP "Update Set" in ServiceNow".

Mapping the OMi event attributes to a ServiceNow incident is a two-step process which is further described in the next two subsections:

1. In the first step, Clip transfers the OMi event attributes to the ServiceNow Web Service "import set table" u_hpbsm according to rules configured on the server running the Clip application and the settings in ClipConfig.xml.
2. In the following second step, ServiceNow applies mappings and scripts to transfer an OMi event that Clip passed to an import set via a Web Service call to create a ServiceNow incident. This is done by the ServiceNow Transform Map "HPBSM_Trans_Map". The rules and mappings are uploaded as described in the next section.

ServiceNow responds to CLIP's Web Service with the Incident Number and its ServiceNow "sys_id". Right after CLIP has received the incident number, CLIP queries the incident just created to obtain incident attributes assigned by ServiceNow like "assigned user", "assigned group" and "priority" so this data can be used for display in OMi's forwarding tab, annotations, custom attributes etc..

Mapping OMi event attributes to ServiceNow import set table u_hpbsm

In the first step, OMi event attributes are transferred to the import set "u_hpbsm" in one of two ways:

• Implicit OMi event attributes are available in the import set "u_hpbsm" without further configuration in ClipConfig.xml. For example, the OMi event "severity" is available in the u_hpbsm WebService field "severity" with the value of "critical", "major", minor", "warning" or "normal".

• User defined attributes (user1 – user10 ) are configured in ClipConfig.xml and can be used to generate customized values which can contain any of the available OMi event attributes (see also appendix B) or Clip special variables ( [RL_ALLVALUES], [RL_ALLCHANGES] ). For example, this field mapping in ClipConfig.xml would configure CLIP to place the "CiName" of an event in the field "user8" if it exists, and "CiDisplayLabel" otherwise:

After uploading the "Update Set" for Clip into ServiceNow, you can review all implicit and user defined attributes by displaying "Integration – Micro Focus OpsBridge"->"Web Service endpoint" in ServiceNow:

Web Service Fields of Import Set table "u_hpbsm"

Mapping “u_hpbsm” fields to ServiceNow incident fields

In the second step, attributes of the u_hpbsm import set table are mapped to a ServiceNow incident by means of a ServiceNow transform map:

Please refer to the ServiceNow documentation for further information about import sets, transform maps etc..

Migration from SOAP to REST on Fuji or later release

REST service is the preferred way of communication between Clip and ServiceNow on the Fuji release. Coming from older releases (i.e. Eureka) it is recommended to switch from SOAP to REST. This can be achieved by following these two steps:

1. Open the configuration file conf/ClipConfig.xml and set the attribute useSOAP to “false” and the importSetTable attribute to Clip’s import set table name:

 <snTarget name="ServiceNow" useSOAP="false" importSetTable="/api/now/import/u_hpbsm"…

1. The Clip integration user has to have to following additional roles which must be provided:

• rest_service
• import_transformer

For details on how to set roles for the integration user please refer to chapter 5.5.1.3 Create an “Integration User” in ServiceNow.

Without “Update Set” / “Scoped App”

Please first create an integration user in ServiceNow to allow CLIP to create and query incidents. At least the following roles must be assigned to this ServiceNow integration user:

• rest_service
• task_editor

Also the ACL "Task.Work_Notes" has to be modified. Otherwise the integration user is not able to access the work notes during ticket creation and update operations. In order to modify this ACL please:

• type "ACL" into the application menu and choose "Access Control"
• filter the ACL with name "Task.Work_Notes"
• edit the ACL with name "Task.Work_Notes" (read operation)
• add the Clip integration role x_algh_clip.clip_integration
• save the ACL

On the Clip Server edit the configuration file conf/ClipConfig.xml – for the ServiceNow integration without "Update Set" / "Scoped App" it contains the example integration "MFOMi_ServiceNowDirect" which needs to be activated:

This integration references the ServiceNow example target "ServiceNowDirect":

The configuration of these attributes is required:

• "processAllFields" should be set to false in order to only process fields that are explicitly defined in the ClipConfig.xml
• "statusField" is the name of the ServiceNow column that holds the current incident's status
• "closedStatusValueString" is the status value that will cause Clip to close the synchronization once it is received
• "importSetTable" attribute should be pointed directly to the incident table (usually "api/now/table/incident")
• "useSOAP" has to be set to "false" because polling is only supported in combination with REST communication
• "updateCalcDelta" should be set to "true" so that polling will only process the changed attributes
• "heartbeatIntervalSecs" (optional, default "270") can be set in order to increase or decrease the heartbeat and polling interval

In this section, only attributes relevant for the mode without "Update Set" / "Scoped App" are described here. For configuration of additional required attributes ( e.g. user, password, URL, proxy settings), please refer to chapter 5.5.1.1 .
Since CLIP version V5.05, CLIP allows two different polling models, the following two subsections describe the model and the related configuration attributes.

Configuring Polling based on ServiceNow query

This newer ( and default ) polling model queries the ServiceNow instance based on a qualifier for those incidents, that have been updated since the last polling cycle. The advantage in comparison with the "polling based on CLIP DB" is that not all "active" incidents known to CLIP need to be read, but only those that have changed and a single ServiceNow query can provide all updates.
The configuration of these attributes is required:

• "incidentPolling" has to be set to true
• "incidentPollingByQualifier" has to be set to true ( default = true )

• "incidentPollingQualifier" identifies the incidents to be queried. The default string "sys_created_by=[RL_IntegrationUser]" queries all incidents that have been created by the integration user as specified in the ServiceNow target ( "user" Attribute of the "snTarget" Tag ). As an additional qualifier, CLIP internally adds a qualifier to limit the query to only the changed incidents since the last polling cycle, i.e. CLIP adds "^sys_updated_on>2017-05-03+10:37:42" ( all timestamps are UTC )

• "incidentPollingAttributes" defines a semicolon separated list of attributes that should be polled by Clip

Configuring Polling based on CLIP DB

The polling model "based on the CLIP DB" queries the ServiceNow instance for all incidents that have been created by CLIP and are "active" according to the state in the CLIP DB. Polling is performed in batches, due to the length limitation of the URL to query ServiceNow which contains the list of sys_id's to be queried.
The configuration of these attributes is required:

• "incidentPolling" has to be set to true
• "incidentPollingByQualifier" has to be set to false ( default = true )
• "incidentPollingAttributes" defines a semicolon separated list of attributes that should be polled by Clip
• "incidentPollingBatchSize" (optional, default "100") defines how many incidents are retrieved in one batch during polling. Since retrieving incidents is an expensive operation batch processing improves performance significantly