Terraform ServiceNow Service Catalog Integration Developer Reference

The Terraform ServiceNow integration can be customized by ServiceNow developers using the information found in this document.

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 Flow 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:

ServiceNow Variable Name	HCP Terraform Variable
`tf_var_VARIABLE_NAME`	Terraform Variable: `VARIABLE_NAME`
`tf_env_ENV_NAME`	Environment Variable: `ENV_NAME`
`sensitive_tf_var_VARIABLE_NAME`	Sensitive Terraform Variable (Write Only): `VARIABLE_NAME`
`sensitive_tf_env_ENV_NAME`	Sensitive Environment Variable (Write Only): `ENV_NAME`

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

Customizing with ServiceNow "Script Includes" Libraries

The Terraform/ServiceNow Integration codebase includes ServiceNow Script Includes Classes that are used to interface with HCP Terraform. The codebase also includes example catalog items and flows that implement the interface to the HCP 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.

Class Name	Description
`tf_config`	Helper to pull values from the SN Terraform Configs Table
`tf_get_workspace`	Client-callable script to retrieve workspace data
`tf_http`	ServiceNow HTTP REST wrapper for requests to the Terraform API
`tf_no_code_workspace`	Resources for Terraform no-code module API requests
`tf_run`	Resources for Terraform run API requests
`tf_terraform_record`	Manage ServiceNow Terraform Table Records
`tf_test_config`	Client-callable script to test Terraform connectivity
`tf_util`	Miscellaneous helper functions
`tf_variable`	Resources for Terraform variable API Requests
`tf_vcs_record`	Manage ServiceNow Terraform VCS repositories table records
`tf_workspace`	Resources for Terraform workspace API requests

Example Service Catalog Flows and Actions

The ServiceNow Service Catalog for Terraform provides sample catalog items that use Flows and Workflows as their primary process engines. Flows are a newer solution developed by ServiceNow and are generally preferred over Workflows. To see which engine an item is using, open it in the edit mode and navigate to the Process Engine tab. For example, Create Workspace uses a Workflow, whereas Create Workspace Flow is built upon a Flow. You can access both in the Studio. You can also manage Flows in the Flow Designer. To manage Workflows, navigate to All > Workflow Editor.

You can find the ServiceNow Example Flows for Terraform in the ServiceNow Studio > Flows (or All > Flow Designer). Search for items that belong to the Terraform application. By default, Flows execute when someone submits an order request for a catalog item based on a Flow. Admins can customize the Flows and Actions to add approval flows, set approval rules based on certain conditions, and configure multiple users or roles as approvers for specific catalog items.

Flow Name	Description
Create Workspace	Creates a new HCP Terraform workspace from VCS repository.
Create Workspace with Vars	Creates a new HCP Terraform workspace from VCS repository and creates any variables provided.
Create Run	Creates and queues a new run in the HCP Terraform workspace.
Apply Run	Applies a run in the HCP Terraform workspace.
Provision Resources	Creates a new HCP Terraform workspace (with auto-apply), creates and queues a run, then applies the run when ready.
Provision Resources with Vars	Creates a new HCP Terraform workspace (with auto-apply), creates any variables, creates/queues a run, applies the run when ready.
Provision No-Code Workspace and Deploy Resources	Creates a new HCP Terraform workspace based on a no-code module configured in the private registry (with auto-apply), creates any variables, creates and queues a run, then applies the run when ready.
Delete Workspace	Creates a destroy run plan.
Worker Poll Run State	Polls the HCP Terraform API for the current run state of a workspace.
Worker Poll Apply Run	Polls the HCP Terraform API and applies any pending Terraform runs.
Worker Poll Destroy Workspace	Queries ServiceNow Terraform Records for resources marked `is_destroyable`, applies the destroy run to destroy resources, and deletes the corresponding Terraform workspace.
Update No-Code Workspace and Deploy Resources	Updates an existing no-code workspace to the most recent no-code module version, updates that workspace's attached variable values, and then starts a new Terraform run.
Update Workspace	Updates HCP Terraform workspace configurations, such as VCS repository, description, project, execution mode, and agent pool ID (if applicable).
Update Workspace with Vars	Allows you to change details about the HCP Terraform workspace configurations and attached variable values.
Update Resources	Updates HCP Terraform workspace details and starts a new Terraform run with these new values.
Update Resources with Vars	Updates your existing HCP Terraform workspace and its variables, then starts a Terraform run with these updated values.

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.

Access Control Roles	Description
`x_terraform.config_user`	Can manage the connection from the ServiceNow application to your HCP Terraform organization.
`x_terraform.terraform_user`	Can manage all of the Terraform resources created in ServiceNow.
`x_terraform.vcs_repositories_user`	Can manage the VCS repositories available for catalog items to be ordered by end-users.

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. Install the Terraform ServiceNow Service Catalog integration by following the installation guide.