ServiceNow Service Graph Connector for Terraform – Setup

The ServiceNow Service Graph Connector for Terraform is a certified scoped application available in the ServiceNow Store. Search for ”Service Graph Connector for Terraform” published by ”HashiCorp Inc” and click Install.

Prerequisites

To start using the Service Graph Connector for Terraform, you must have:

• An administrator account on a Terraform Enterprise instance or within an HCP Terraform organization.
• An administrator account on your ServiceNow vendor instance.

The Service Graph Connector for Terraform supports the following ServiceNow server versions:

• Utah
• Vancouver
• Washington DC
• Xanadu

The following ServiceNow plugins are required dependencies:

• ITOM Discovery License
• Integration Commons for CMDB
• Discovery and Service Mapping Patterns
• ServiceNow IntegrationHub Standard Pack

Additionally, you can install the IntegrationHub ETL application if you want to modify the default CMDB mappings.

Connect ServiceNow to HCP Terraform

Once the integration is installed, you can proceed to the guided setup form where you will enter your Terraform credentials. This step will establish a secure connection between HCP Terraform and your ServiceNow instance.

Create and scope Terraform API token

In order for ServiceNow to connect to HCP Terraform, you must give it an HCP Terraform API token. The permissions of this token determine what resources the Service Graph Connector will import into the CMDB. While you could use a user API token, it could import resources from multiple organizations. By providing a team API token, you can scope permissions to only import resources from specified workspaces within a single organization.

Visit your organization’s Settings > Teams page. Scroll down to the Team API Token section and click Create a team token. Save this token in a safe place since HCP Terraform only displays it once. You will use it to configure ServiceNow in the next section.

Configure Service Graph Connector for Terraform API token

In the top navigation of your ServiceNow instance's control panel, click on All, search for Service Graph Connector for Terraform, and click SG-Setup. Next, click Get Started.

Next, in the Configure the Terraform connection section, click Get Started.

In the Configure Terraform authentication credentials section, click Configure.

If you want to route traffic between your HCP Terraform and the ServiceNow instance through a MID server acting as a proxy, change the Applies to dropdown to "Specific MID servers" and select your previously configured MID server name. If you don't use MID servers, leave the default value.

Set the API Key to the HCP Terraform team API token that you created in the previous section and click Update.

In the Configure Terraform authentication credentials section, click Mark as Complete.

Configure Terraform Webhook Notification token

To improve security, HCP Terraform includes an HMAC signature on all "generic" webhook notifications using a user-provided token. This token is an arbitrary secret string that HCP Terraform uses to sign each webhook notification. ServiceNow uses the same token to verify the request authenticity. Refer to Notification Authenticity for more information.

Create a token and save it in a safe place. This secret token can be any value but should be treated as sensitive.

In the Configure Terraform Webhook token section, click Configure. In the Token field, enter the secret token that will be shared between the HCP Terraform and your ServiceNow instance and click Update.

In the Configure Terraform Webhook token section, click Mark as Complete.

Configure Terraform connection

In the Configure Terraform connection section, click Configure.

If you are using Terraform Enterprise, set the Connection URL to the URL of your Terraform Enterprise instance. If you are using HCP Terraform, leave the Connection URL as the default value of https://app.terraform.io.

If you want to use a MID server, check Use MID server box, change MID Selection dropdown to "Specific MID sever" and select your previously configured and validated MID server.

Click Update to save these settings. In the Configure Terraform connection section, click Mark as Complete.

Import Resources

Refer to the documentation explaining the difference between the two modes of import offered by the Service Graph Connector for Terraform. Both options may be enabled, or you may choose to enable only the webhook or scheduled import.

Configure scheduled import

In the Set up scheduled import job section of the setup form, proceed to Configure the scheduled jobs and click Configure.

You can use the Execute Now option to run a single import job, which is useful for testing. The import set will be displayed in the table below the scheduled import form, after refreshing the page. Once the import is successfully triggered, click on the Import Set field of the record to view the logs associated with the import run, as well as its status.

Activate the job by checking the Activate box. Set the Repeat Interval and click Update. Note that the import processing time depends of the number of organizations and workspaces in your HCP Terraform. Setting the import job to run frequently is not recommended for big environments.

You can also access the scheduler interface by searching for Service Graph Connector for Terraform in the top navigation menu and selecting SG-Import Schedule.

Configure Terraform Webhook

In the top navigation, click on All, search for Scheduled Imports, and click on Scheduled Imports.

Select the SG-Terraform Scheduled Process State record, then click To edit the record click here.

Click the Active checkbox to enable it. Leave the default value for the Repeat Interval of 5 seconds. Click Update.

Next, create the webhook in HCP Terraform. Select a workspace and click Settings > Notifications. Click Create a Notification.

Keep the Destination as the default option of Webhook. Choose a descriptive name Name.

Set the Webhook URL enter https://<SERVICENOW_HOSTNAME>/api/x_hashi_service_gr/sg_terraform_webhook and replace <SERVICENOW_HOSTNAME> with the hostname of your ServiceNow instance.

In the Token field, enter the same string you provided in Terraform Webhook token section the of the Service Graph guided setup form.

Under Health Events choose No events.

Under Run Events choose Only certain events and enable notifications only on Completed runs. Click Create Notification.

Trigger a run in your workspace. Once the run is successfully completed, a webhook notification request will be sent to your ServiceNow instance.

Monitor the import job

By following these steps, you can track the status of import jobs in ServiceNow and verify the completion of the import process before accessing the imported resources in the CMDB.

For scheduled imports, navigate back to the SG-Import Schedule interface. For webhook imports, go to the SG-Terraform Scheduled Process State interface.

Under the form, you will find a table containing all registered import sets. Locate and select the relevant import set record.

Click on the Import Set field to open it and view its details. The Outbound Http Requests tab lists all requests made by your ServiceNow instance to HCP Terraform in order to retrieve the latest Terraform state.

Monitor the state of the import job. Wait for it to change to Complete, indicated by a green mark. Once the import job is complete, you can access the imported resources in the CMDB.

You can also access all import sets, regardless of the import type, by navigating to All and selecting Import Sets under the Advanced category.

View resources in ServiceNow CMDB

In the top navigation of ServiceNow, click on All and search for CMDB Workspace, and click on CMDB Workspace.

Perform a search by entering a Configuration Item (CI) name in the Search field (for example, Virtual Machine Instance). CI names supported by the application are listed on the resource mapping page.