The Terraform ServiceNow Service Catalog integration enables your end-users to provision self-serve infrastructure via ServiceNow. By connecting ServiceNow with Terraform Enterprise, this integration lets ServiceNow users create workspaces and perform Terraform runs, using prepared Terraform configurations hosted in VCS repositories.

Integrating ServiceNow with Terraform Enterprise involves several configuration steps. You will perform some of these steps in ServiceNow, and some of them in Terraform Enterprise.

Once these steps are completed, self-serve infrastructure will be available through the ServiceNow Catalog. Terraform Enterprise will provision and manage any requested infrastructure.

Prerequisites

To start using Terraform with ServiceNow Catalog Integration, you must already have:

• An account on a Terraform Enterprise instance.
• A ServiceNow instance or developer instance. You can request a ServiceNow developer instance at developer.servicenow.com.
• A supported version control system (VCS) with read access to repositories with Terraform configuration.
• A private Git repository to host the ServiceNow integration.

It does not require additional ServiceNow modules and has been tested on the following ServiceNow server versions:

• Madrid
• London

Obtaining the ServiceNow Integration

Before beginning setup, you must obtain a copy of the Terraform ServiceNow Catalog integration software. Contact your HashiCorp sales representative to get access to the software.

Once you have obtained the files from your sales representative, check them into a private Git repository before beginning these setup instructions.

Terraform Enterprise Setup

Before installing the ServiceNow integration, you need to perform some setup and gather some information in Terraform Enterprise.

1. Create an organization (or choose an existing organization) where ServiceNow will create new workspaces.
2. Create a team for that organization called "ServiceNow", and ensure that it has the organization-level "Manage all workspaces" permission. You do not need to add any users to this team.
3. On the "ServiceNow" team's settings page, generate a team API token. Save this API token for later.
4. If you haven't yet done so, connect a VCS provider for this Terraform organization.
5. On the organization's VCS provider settings page, find the "OAuth Token ID" for your VCS provider. This is an opaque ID that Terraform Enterprise uses to identify this VCS provider. Save the OAuth Token ID for later.

Installing the ServiceNow Integration

ServiceNow Server Studio

Import the integration using the ServiceNow Studio.

1. Launch the ServiceNow Studio by typing "studio" in the search on the left-hand side.
2. Click "Import from Source Control."
   • If this is not your first time opening the Studio, you can also access this from File > Import from Source Control.
3. Fill in the information required to import the integration:
   • URL: https://github.com/<YOUR_ORG>/terraform-servicenow-integration
   • Username: <your VCS username>
   • Password: <a VCS Personal Access Token or your password>
4. Select the Terraform application.
   • Application > Terraform
5. You can now close the ServiceNow Studio or continue customizing the application.

Enable Polling Workers (Recommended)

The integration includes 2 ServiceNow Workflow Schedules to poll the Terraform Enterprise API using ServiceNow Outbound HTTP REST requests. By default, all workflow schedules are set to On-Demand. These can be customized inside the ServiceNow Server Studio:

1. Select the Worker Poll Run State (Workflow > Workflow Schedule).
2. Change the value for the Run field from "On-Demand" to "Periodically".
3. Set Repeat Intervals to 1-5 minutes.
4. Click "Update".

Worker Poll Apply Run

This worker approves runs for any workspaces that have finished a Terraform plan and are ready to apply their changes. It also adds a comment on the request item for those workspaces notifying that a run has been triggered.

Worker Poll Run State

The worker synchronizes ServiceNow with the current run state of Terraform workspaces by polling the Terraform Enterprise API. On state changes, the worker adds a comment to the ServiceNow request item with the updated run state and other metadata.

Connecting to Terraform Enterprise

1. Exit Service Now Studio and return to the ServiceNow Service Management Screen.
2. Using the left-hand navigation, open the configuration table for the integration to manage the Terraform Enterprise connection.
   • Terraform > Configs
3. Click on "New" to create a new Terraform Enterprise connection:
   • Set API Team Token to the Terraform Enterprise Team Token you created earlier.
   • Set Hostname to the hostname of your Terraform Enterprise instance. (If you're using the SaaS version of Terraform Cloud, this is app.terraform.io.)
   • Set Org Name to the name of the Terraform Enterprise organization you wish to use for new workspaces created by ServiceNow.

Adding the Terraform Service Catalog

1. In ServiceNow, open the Service Catalog > Catalogs view by searching for "catalogs" in the left-hand navigation.
2. Click the plus sign in the top right.
3. Select Terraform and choose a place to add it.

At this point, your users can request Terraform infrastructure via ServiceNow, but there are not yet any infrastructure items available to request.

Configuring VCS Repositories

To make infrastructure available to your users, you must add one or more workspace templates to the Terraform service catalog. A workspace template is a VCS repository that contains a Terraform configuration; any repository that could be connected to a manually-created Terraform Enterprise workspace can also be used as a workspace template in the ServiceNow integration.

1. In ServiceNow, open the Terraform > VCS Repositories table by searching for "terraform" in the left-hand navigation.
2. Click "New" to add a VCS repository for fulfillment through the Terraform Service Catalog.
   • Name: The name for this workspace template that you want users to see.
   • OAuth Token ID: The OAuth Token ID that you copied from your Terraform Enterprise organization's VCS providers settings. This ID specifies which VCS provider hosts the desired repository.
   • Identifier: The VCS repository that contains the Terraform configuration for this workspace template. Repository identifiers are determined by your VCS provider; they typically use a format like <ORGANIZATION>/<REPO NAME> or <PROJECT KEY>/<REPO NAME>. Azure DevOps repositories use the format <ORGANIZATION>/<PROJECT>/_git/<REPO NAME>.
   • The remaining fields are optional.

Terraform Variables and ServiceNow Variable Sets

ServiceNow has the concept of a Variable Set which is a collection of ServiceNow Variables that can be referenced in a workflow from a Service Catalog item. The Terraform Integration codebase can create Terraform Variables and Terraform Environment Variables via the API using the tf_variable.createVariablesFromSet() function.

This function looks for variables following these conventions:

This function takes the ServiceNow Variable Set and Terraform Workspace ID. It will loop through the given variable set collection and create any Terraform variables or Terraform environment variables.

Customizing with ServiceNow "Script Includes" Libraries

The Terraform/ServiceNow Integration codebase includes ServiceNow Script Includes Classes that are used to interface with Terraform Enterprise. The codebase also includes example catalog items and workflows that implement the interface to Terraform API.

These classes and examples can be used to help create ServiceNow Catalog Items customized to your specific ServiceNow instance and requirements.

Script Include Classes

The ServiceNow Script Include Classes can be found in the ServiceNow Studio > Server Development > Script Include.

Example Service Catalog Workflows

The ServiceNow Example Workflows can be found in the ServiceNow Studio > Workflow > Workflow. By default, the workflows execute upon submitting an order request for the various catalog items. Admins can modify the workflows to wait on an approval action, include approval rules, and specify approver groups.

ServiceNow ACLs

Access control lists (ACLs) restrict user access to objects and operations based on permissions granted. This integration includes the following roles that can be used to manage various components.

For users who only need to order from the Terraform Catalog, we recommend creating another role with read-only permissions for x_terraform_vcs_repositories to view the available repositories for ordering infrastructure.

Example Customizations

Creating a Catalog Item with Pinned Variables

This example use case creates a Terraform catalog item for resources that limits user input to certain variables.

Create Service Catalog Item

1. Enter the ServiceNow Studio.
2. Click "Create Application File" to raise a dialog box of options.
3. In the dialog, navigate to the "Service Catalog" section, select "Catalog Item", and click the "Create" button.
4. Name the new catalog item. (The rest of this example assumes an item named Example With Pinned Variables.)
5. Select Catalogs: "Terraform Catalog" > Select Categories: "Terraform Resources".
6. Add any other descriptions you may want.
7. Click "Submit".

Create Variable Set

1. Click "Create Application File" to raise a dialog box of options.
2. In the dialog, navigate to the "Service Catalog" section, select "Variable Set", and click the "Create" button.
3. Name your variable set. (The rest of this example assumes a set named Example Pinned Variables, with a default "Internal Name" of example_pinned_variables.)
4. Click "Submit".
5. Under the "Variables" tab click "New".
   1. Create your variable:
   2. In this example we will create a field called tf_var_pet_name_length that will be for a Terraform variable that determines the number of words to use for the pet server name.
      • Question: Pet Name Length
      • Name: tf_var_pet_name_length
      • tf_var_ tells the Terraform ServiceNow SDK that this is a Terraform variable.
   3. Repeat variable creation as necessary for your use case.
   4. Click "Submit".

Add Variable Set to Catalog Item

1. Go back to your Catalog Item.
2. Under the "Variable Sets" tab, click "New".
3. Search for and select the variable set you created (Example Pinned Variables).
4. Click "Submit".

Create Custom Workflow

This example uses the "Example With Pinned Variables" workflow, which is one of the example workflows included with the integration.

In the ServiceNow Studio:

1. Navigate to "Workflow" > "Workflow" > "Example With Pinned Variables".

2. Double click on the "Run Script" item.

3. Copy the script code from the editor.

4. Close the "Run Script" and "Workflow" windows.

5. Create a new custom workflow, by clicking "Create Application File" and choosing "Workflow".

   • Name: Example Pinned Variables (replace with your custom workflow name)
   • Table: Requested Item [sc_req_item] and Click "Submit"

6. Add a "Run Script" item to the workflow, by navigating to the "Core" tab and selecting "Utilities" > "Run Script".

   • Name: Example Workflow Pinned Variables

   • Script:

     • Paste in the code copied from the "Provision Resources with Variables" workflow, and change the following lines:

         // ** Custom Variables **
         var VAR_SET_NAME = "example_pinned_variables";
         var VCS_REPO     = "ORG_NAME/REPO_NAME";
       

7. Click "Submit"

8. Ensure that the ServiceNow Run Script is part of the workflow. (The summary of the workflow should look like "Begin" > "Run Script" > "End".)

9. Click the menu at the top left and select "Publish"

Set The Workflow for Catalog Item

In the ServiceNow Studio:

1. Select the "Example with Pinned Variables" catalog item. ("Service Catalog" > "Catalog Item" > "Example With Pinned Variables")
2. Select the "Process Engine" tab.
3. Set the workflow field by searching for the "Example Pinned Variables" workflow and clicking "Update".

Test the Catalog Item

The new item should be available in the Terraform Service Catalog. Once the new catalog item is confirmed to work, you can customize as needed.