# ServiceNow Integration

There are several ways Avantra is able to integrate with ServiceNow IT Service Management. Synchronizations include:

- You can forward Notifications to a ServiceNow instance in order to create incidents in there, as described in Define a ServiceNow Incident Output Channel.

- You can push/insert records directly to the event [em_event] table in ServiceNow, as described in Define a ServiceNow Event API Output Channel.

- You can synchronize servers from the ServiceNow IT Service Management into Avantra, as described in Synchronization of Servers.

- You can synchronize information discovered by Avantra into ServiceNow, as described in Outbound synchronization.

All scenarios require authorization of Avantra with ServiceNow which is described in Authorizing Avantra with ServiceNow.

But first, you need to install the Avantra Integration from the ServiceNow Store:

## Installing the Avantra Integration from the ServiceNow Store

| You only need the Avantra Integration if you want to create incidents in ServiceNow. It is not required in order to synchronize Servers from ServiceNow or use the outbound synchronization.

1. Open your preferred browser and proceed to the ServiceNow Store.

2. Search for Avantra and push the Get button.

3. Press Continue to confirm the notice.

4. You can choose to install the app on all instances or only on the selected instance. Set the flag next to I accept …​ and push Get.

5. In your ServiceNow instance, choose System Applications Applications and switch to the Downloads tab. Choose Avantra from the list and push the Install button. You probably must be a ServiceNow administrator to accomplish this task.

### Authorizing Avantra with ServiceNow

We recommend using a dedicated (API-) User in your ServiceNow instance for the integration with Avantra, i.e. to create a new user with the flag Web service access only set. You probably must be a ServiceNow administrator to accomplish this task.

Perform the following steps in your ServiceNow instance:

1. Choose User Administration Users and push the New button.

2. Fill in at least a User ID, e.g. `avantra-api-user`, a Password, and set the flag Web service access only, if desired. Push Submit.

3. Open the newly created user record and push the Edit …​ button on the Role tab at the bottom of the page.

4. Depending on what you plan to do, add the following roles:

   - To create incidents in ServiceNow, select the role `x_308038_syslink_x.imp_incident_user` i.e. type `x_` into the Collection search box, choose the mentioned role, and push . We also recommend adding the `itil` role to make the purpose of the user clear!

   - To send events to ServiceNow, use the role `evt_mgmt_integration`.

   - To synchronize servers from ServiceNow to Avantra, add the role `inventory_user`.

   - To use the outbound synchronization add the role `itil`.

5. Push the Save button.

Perform the following steps in Avantra WebUI:

Procedure: Creating a ServiceNow Authentication

1. Open Configuration Integrations and choose New ServiceNow.

2. Fill in a Name and select a Customer. Push the Create button.

3. Select the newly created entry and push Open.

4. Fill in your ServiceNow Instance Name, and for ServiceNow User and Passwords the values you created above.

5. Push the Save button.

## Synchronization of Servers

In order to synchronize server from ServiceNow to Avantra, proceed as follows:

1. Open Administration Synchronizations.

2. Choose New Inbound synchronization from the menu, choose `ServiceNow` for External Service, fill in a Name, and push Create.

3. Open the newly created record.

4. You may fill in a Description.

5. If you want to run the synchronization in the background periodically, you can set the flag Activate background synchronization and fill in an appropriate value for the time period.

   | Do not set this flag right from the beginning. Walk through this procedure, and after the initial synchronization was successful, set this flag.

6. Select the ServiceNow Authentication you created in Authorizing Avantra with ServiceNow.

7. In Table Name fill in the ServiceNow table that contains your server records. This will most likely be `cmdb_ci_server` or one of its sub-tables. It corresponds to the `tableName` shown in the ServiceNow REST API Explorer, see also the next step.

8. Fill in a Query to restrict the selection of servers from ServiceNow. You may use the ServiceNow REST API Explorer to build your query, just click on the link ServiceNow REST API Explorer. Push Apply and use the Test Query button to verify your selection.

9. For System Type select `Server`. This is the only available selection currently.

10. Choose a Default Customer and a Default System Role assigned to newly synchronized objects. These values will be used unless you create an attribute mapping overriding the values. See below.

11. In Additional Attribute Mapping, you may define how ServiceNow attributes are mapped to the Avantra fields `Customer`, `System Role`, `Description`, `Notes`, and `IP address`.

12. You can also select if monitoring shall start immediately after synchronization with field Start Monitoring. Most likely, you will choose `No` here.

13. Set the flag Create New Objects if you want to create a new object in Avantra if a new object is found in ServiceNow.

14. Set the flag Update Modified Objects if you want to modify an object in Avantra if the corresponding object was modified in ServiceNow.

15. Set the flag Delete Objects if you want to delete an object from Avantra that is no longer selected from ServiceNow. These can be objects that are deleted in ServiceNow, or that are no longer selected due to a modified Table Name or Query.

    | Use this option carefully!

16. Push Apply and use the Sync button to start the synchronization.

## Outbound synchronization

The outbound synchronization can enhance your ServiceNow CMDB with information discovered by Avantra. In addition to our existing CMDB integration, we now also offer integration with ServiceNow Service Graph Connector starting with Avantra 20.11.6 (see both procedures below). This synchronization will allow you to automatically sync detailed SAP configuration and change data with ServiceNow CMDB.

Procedure: Set up Service Graph Connector Synchronization (preferred option)

1. This outbound synchronization is based on CI of the cmdb_ci_sap_sid class, so make sure this class is installed in ServiceNow.

2. Install the Service Graph Connector from the ServiceNow Store by searching for Service Graph Connector for Avantra and clicking the Request App button (you will be prompted to log in with your ServiceNow ID).

3. Open the Service Graph Connector Guided Setup in ServiceNow and follow its instructions:

   - Create a user in ServiceNow with the `import_admin` role

   - Create Cloud Authentication in Avantra (also described in Authorizing Avantra with ServiceNow)

After the Service Graph Connector is ready, you can configure the synchronization in Avantra.

1. Open Administration Synchronizations.

2. Choose New Outbound synchronization from the menu, choose `ServiceNow Service Graph` for External Service, fill in Name, and push Create.

3. Open the newly created record.

4. You may fill in the Description field.

5. If you want to periodically run the synchronization in the background, you can set the flag Activate background synchronization and fill in an appropriate value for the time period.

6. Select the ServiceNow Authentication you created in Authorizing Avantra with ServiceNow.

7. Under Systems, select which SAP systems you want to synchronize. For example, you can choose systems of only one customer for the given synchronization, and then create another synchronization for another customer and sync it with a different ServiceNow instance. For this purpose, you can either select an existing system selection using Select a Pre-Defined System Selector or create a new one by choosing Define specific 'Ad-Hoc' Custom Selection and pushing the Create button. See Defining a System Selector for details.

8. Push the Sync button to start the synchronization.