This article contains instructions for implementing and using the NS1 + ServiceNow Orchestration Activity Pack integration. Alternatively, if you are using ServiceNow’s IntegrationHub, refer to these instructions instead.
ServiceNow Orchestration activity packs extend the workflow engine to manage processes and to automate things outside of a ServiceNow instance—allowing for greater efficiency around IT and business-related processes. Orchestration provides an ability to create reusable custom activities by using the Orchestration activity designer. Users can subscribe to the Orchestration plug-in as an add-on to the ServiceNow platform.
Orchestration provides the ability to create reusable activities via the Orchestration activity designer and includes wrapped NS1 REST messages available for use on any custom flows. To learn more about how to create custom activities, click here.
Requirements
- From NS1, you must have a Managed DNS account or have installed the Private DNS / Enterprise DDI software (version 2.2 or later).
- From ServiceNow, you must have purchased the Orchestration Activities plugin.
NOTE
If you are using ServiceNow’s IntegrationHub plugin, refer to these instructions instead.
Implementation Instructions (ServiceNow admin only)
Implementation must be done by someone with ServiceNow admin-level permissions.
-
Create an API key within the NS1 platform you want to control through ServiceNow (either Managed DNS or Private DNS/DDI).
NOTE Make sure to save/record the API key as it will not be viewable after initial key creation. -
Activate the Orchestration activity packs plugin. Once activated, verify the connection by navigating to Orchestration > Workflow Editor to ensure the activities are listed and accessible.
-
In the ServiceNow portal, click the gear icon at the top right corner of the banner frame.
- Under Application, select the application you want (i.e. NS1 Orchestration).
Initial configuration
The following steps are used to configure general settings, such as logging level, API key setup, etc.
-
From the left-hand sidebar, navigate to NS1 Orchestration > Configurations > General Configurations.
-
Under NS1 Configuration, enter the domain name of your Managed DNS or Private DDI network. This value is used to populate CMDB data for zones and records.
-
Enter the API key you created earlier. This is the API key created in and corresponding to the specific platform—Managed DNS or Private DNS/DDI—you want to use for configuring workflows in ServiceNow.
-
Select the logging level from the drop-down menu. This property defines how detailed logging is enabled for the application.
-
Define the auto refresh interval (time in seconds) used for API monitoring. The default is set to 300 seconds.
-
Define the configuration item (CI) expiration time which specifies when a non-discovered (inactive) CI should be automatically marked as “retired.”
API key configuration for Orchestration activities
Some of the pre-configured activities apply only to Private DNS/DDI users. This includes all activities pertaining to DHCP or IPAM as these are only available to NS1 customers who have purchased and installed NS1 Enterprise DDI. Refer to the NS1 API documentation for details.
-
In the ServiceNow portal, navigate to NS1 Orchestration > Configurations > Orchestration.
-
Update each value against each REST message. Note that all REST messages called by the same workflow/activity should use the same API key. For example, if a workflow is using DDI activities, apply the same API key to all DDI-related REST messages.
-
Navigate to Orchestration > Workflow Editor to get started using activity packs for NS1.
- It should prompt a new window to open with Workflow Editor and you can view the NS1 activities to the left.
Testing the configuration
Follow the steps below to verify that the configuration for zone and record integration is functioning properly.
-
In the ServiceNow portal, navigate to NS1 Orchestration > Monitoring > API Monitoring.
-
Click Load Data, and wait for the page to refresh or click Refresh.
-
Under Details, note whether or not the job is listed as “Complete” (i.e. Status: Complete).
-
Click Check details here to view the imported data.
Workflow editor
The Orchestration Workflow editor allows you to use one of the following activities while creating or modifying workflows.
This is a REST-based workflow in order to automate a multi-step process by combining different NS1 Orchestration Activities. Data inputs and requirements for the workflows match the NS1 API endpoints. Reference the example formats below.
Create a host record
This workflow creates a host record and optionally creates reverse zone and reverse record. It uses the following REST messages:
- Create a record
- Create a zone
Parameters (& example formats):
- Select "yes" or "no" from the drop-down list next to Create a reverse zone and record
- Enter a domain (ex. orchestra1.vdach.com)
- Optionally, enter a company domain (ex. demo.nsone.net)
- Enter a record type (ex. A)
- Enter the zone (ex. vdach.com)
- Enter one or more record answers (ex. [{"answer":["10.0.0.1"]}] Note: You must include all brackets and quotation marks.)
Delete a host record
This workflow deletes a host record and, optionally, deletes a reverse record. It uses the following REST messages:
- Delete a record
- View record configuration details
Parameters (& example formats):
- Optionally, enter a company domain (ex. demo.nsone.net)
- Enter a domain (ex. orchestra1.vdach.com)
- Enter a record type (ex. A)
- Enter the zone (ex. vdach.com)
- Select "yes" or "no" from the drop-down list next to Delete reverse record
Create and reserve an IP address (IPAM)
This workflow creates an IPAM IP address and also creates a reservation. It uses the following REST messages:
- Create an IP address (subnet)
- Create a reservation
Parameters (& example formats):
- Enter a name for the reservation.
- Enter a domain (ex. orchestra1.vdach.com)
- Enter one or more options (ex. [{"name": "dhcpv4/host-name","value": "ipzone.test"},{"name": "dhcpv4/domain-name","value": "newtest1.ipzone.test"},{"name": "dhcpv4/bootfile-name","value": "/boot1.img"}] )
- Enter an IPAM Domain (ex. company.net)
- Enter key value pairs (KVPS) (ex. {"a":"2"} )
- Enter a description.
- Enter a prefix (ex. 20.0.0.0/16)
- Enter tags (ex. ["custom-tag-1","custom-tag-2"])
- Enter the scope group ID (ex. 1)
- Enter the MAC address (ex. aa:bb:cc:dd:ee:ff)
- Enter a company domain (ex. company.net)
- Enter a network ID (ex. 110)
- Select a reservation type (ex. Assigned)
Delete an IP address reservation
This workflow uses the following activities:
- View reservation details
- List host records
- Delete a host record
- View a subnet (IP address)
Parameters (& example formats):
- Enter a company domain (ex. demo.nsone.net)
- Enter a domain (ex. orchestra1.vdach.com)
- Enter a reservation ID
- Select a record type from the drop-down list (ex. A)
- Select or deselect the check box next to Delete IPAM record for this host
List of predefined flows (REST API)
Below are the predefined workflows that come with the NS1 integration application and are available in both Orchestration Activity Packs and IntegrationHub. To get detailed information about the available REST messages, go to Development Tools > REST Messages in the left-hand sidebar (under NS1 Orchestration).
DNS:
- Create a host record
- Create a zone
- Delete a host record
- Get record configuration details
- List host records
DHCP:
- Create a reservation
- Delete a reservation
- Get reservation details
- List reservations
IPAM:
- Create an IP address
- Create a network
- Get an IP address
- List all IPAM reservations
- List networks
- Remove a network
- Reserve an IP address
Using the NS1 + ServiceNow integration, users can create workflows using any of the NS1 API endpoints, listed at www.ns1.com/api.