ServiceNow

This article describes how to set up an integration between your IONIX platform and ServiceNow. Integrating IONIX and ServiceNow will allow you to automatically open ServiceNow tickets that are based on Action Items created in the IONIX platform. 

Once you complete this guide, you’ll be able to provide us with the credentials we need to complete the integration.

General Information:

  • Both UserID/Password and Refresh Token based authentication are supported. 
  • You can set a threshold for the action items you would like to receive based on IONIX urgency scale (1-10 scale)

Known Issues and Limitations:

  • When an Action Item is closed in the IONIX platform, this will not automatically close the equivalent incident or change any of the incident fields in ServiceNow.  
  • When an incident is resolved in ServiceNow, it will not affect the equivalent Action Item in IONIX platform. Action Items are closed only when IONIX’s system no longer detects them. 
  • IONIX can only send to ServiceNow up to 1,000 action items per hour. Thus, initially, after an integration is set up, it might take a few hours to see all the open action items as tickets in ServiceNow. 

ServiceNow “Impact” Correlation

  • Vulnerability Action Items: Impact = High 
  • PKI, DNS, Cloud Action items: Impact = Medium 

ServiceNow “Urgency” Correlation

IONIX Urgency ServiceNow Urgency 
9.0 – 10.0 High 
7.0 – 8.9 Medium 
0.0 – 6.9 Low 

ServiceNow “Priority”

Priority is defined by ServiceNow using the following logic (unless configured otherwise in customer’s specific account)

Credentials

You’ll need to insert the following information to IONIX’s portal in order to complete the integration.  

  • Your ServiceNow Instance’s URL; 
  • OAuth Client ID; 
  • OAuth Client Secret; 

Use one of the following options: 

Option 1  

  • User Id; 
  • User Password; 

Option 2 

  • Refresh Token 

Creating OAuth Client:

1. Navigate to System OAuth> Application Registry

2. Click New to create an OAuth endpoint.

3. Create an OAuth API endpoint for external clients.

4. Name the new OAuth client ‘IONIX’. Leave all the other fields blank and press ‘Submit’.

5. Copy and record the Client ID on this screen (you’ll need to enter it later to the IONIX portal) and click ‘IONIX’ OAuth Client.

6. Now, press the lock button on Client Secret and copy the value (you’ll need to enter it later to the IONIX portal).

Creating New Inbound Web Service:

1. Navigate to System Web Services > Inbound > Create New

2. Create a new inbound web service labeled ‘ionix_action_item’ with Target Table – ‘Incident’. In it, create all the Web Service Fields with the labels depicted on the screenshot below. And then, at the top right, click ‘Create’. 

3. Press ‘Submit’ in the following screen.

A new screen will be displayed, please ignore it and move on. 

The fields ‘name’ and ‘body’ that we created in the new inbound web service should be of greater length than the default length of 40

characters. 

4. Navigate to System Definition > Tables (press ‘Tables’)

5. There, search the table created for our inbound web service labeled ‘ionix_action_item’ and click on it.

6. In the ‘ionix_action_item’ table definitions, search both for ‘name’ and for ‘body’ column labels. For each, double-click the max-length field and set the value to 4000. Afterwards, press ‘Update’.

If everything worked well so far, please move to the next section: Creating a Transform Map.
 Otherwise, in case of any issue with the web service, it is best to delete the web service and re-create it. 

7. To delete a web service, navigate to web service and click the desired one.

8. Click ‘Delete Web Service’ then return to step 2 above: “Create a new inbound web service”.

Creating a Transform Map:

1. Navigate to ‘ionix_action_item’.

2. In the edit screen, scroll down to the Web Service Transform Maps, where you will find a table named ’ionix_action_item’. Please click on it.

3. Add a new mapping by clicking ’New’ in Field maps section.

4. In the following screen, map the ‘name’ field in the source table to ‘Short description’ field in target table and click ‘Submit’.

5. In the same way that we created this mapping, we now need to create four more similar mappings, according to step #3.1, which are: 

Source field    => Target field 

body                 => Description 

category          => Category 

impact             => Impact 

urgency           => Urgency 

opening_date => Opened  

After we’re done entering the above-mentioned mappings, your transform map should look like this.

Authorizing IONIX User to Use the Recently Generated API:

1. Navigate to ‘Roles’.

2. Create a new role.

3. Name it ‘ionix_integration’ and click ‘Submit’.

Creating a Group of Users for the Integration:

1. Navigate to User Administration > Groups.

2. Create a new group.

3. Call the group ‘ionix_group’ and add the description: ‘Users for IONIX integration server.’ and click ‘Submit’.

4. Navigate to that newly created group.

5. Click on ‘Edit’ to add necessary roles.

6. In the following screen search for these roles:  

  • ‘ionix_integration’ – our integration role;  
  • ‘import_transformer’ – an import role, which certifies user to use the import set we created in our web service;

7. For each role, click ‘>’ to move it to the box on the right or just double-click it.

8. When it’s done, click ‘Save’.

9. Click ‘Update’.

Adding a New User:

1. Navigate to System Security -> Users and Groups -> Users and click ‘New’.

2. Fill in their name, user ID and password. We recommend that you check the ‘web services only’ box (Record these credentials. You’ll need to enter them later to the IONIX portal.)

Adding a User to a Group:

1. Navigate to System Security > Users and Groups > Groups.

2. Search our group and click it.

3. Go to ’Group Members’.

4. Press ‘Edit’.

5. Search user’s name Under ‘Collection’, choose it, add it to the box on the right using the ‘>’ button and press ‘Save’.

6. Notice that our new role was given to the user and press ‘Update’.

Creating a New ACL:

1. First, you need to elevate your role.

2. Mark the security admin and click ‘OK’.

3. Navigate to ACL.

4. Click ‘New’. Create two policies. These are required for enabling the new web service named – ‘ionix_action_item’.

5. Create record policy. Under name, search for ‘ionix_action_item’, add a description and then double-click the role field and search for ‘ionix_integration’. 

6. Finally, click ‘Submit’ and then ‘Continue’.

7. Write record policy. Same as the above policy. Repeat step 8 for this policy. ‘Submit’ and ‘Continue’ to finish. 

That’s It! Your ServiceNow instance is ready for integration with IONIX. 

All you need to do is provide us with the credentials for the web service you now created. 

Collecting the Information Needed on the IONIX Portal:

1. To complete the integration, You’ll need to insert the following information to IONIX’s portal.  

  • Your ServiceNow instance URL; Your ServiceNow instance URL is https://<your instance>.service-now.com (see screenshot below)
  • OAuth Client ID; 
  • OAuth Client Secret; 

Select one of the following options: 

Option 1  

  • User Id; 
  • User Password; 

Option 2 

  • Refresh Token 

To get this token, you’ll have to make an HTTP request to your instance.

We’ll show you how to do it using Postman, but you can use any other tool to send the request. Here’s the request properties:

Use a POST request.

URL: take the Instance’s URL from the above bullet (see the above image) and add “/oauth_token.do”. For example: https://dev111452.servicenow.com/oauth_token.do.

Body (If you’re using Postman, check the ‘x-www-form-urlencoded’ option):

Body should contain these keys and values –

“grant_type” = “password”,

“client_id” = OAuth Client ID mentioned above

“client_secret” = OAuth Client Secret mentioned above

“username” = User Id for the user you chose or the new user you created.

“password” = User’s password for the user you chose or the new user you created.

Leave the headers blank.

2. Eventually, your request should look like this.

3. From the request’s response please copy the “refresh_token” and record it (you will need to enter it to the IONIX Portal). That’s the OAuth Refresh Token.

The response should be:

IONIX’s Portal:

1. Go to ‘Integration Settings’.

2. Under ‘Integrate ServiceNow’, press the ‘Settings’ button.

3. In the settings screen, you should insert the credentials mentioned above. As mentioned above, you need to choose whether you provide us with User ID + Password or with Refresh Token.

Here’s the User ID + Password option:

4. Here’s the Refresh Token option:

5. Set the Integration configuration in the section underneath the credentials. You can choose which categories of action items you wish to integrate and the urgency threshold.

6. Once you’re done with the configuration, click ‘Save’.

At this point, you should be able to see the activation button on screen – click it and you’re done.