How to create an integration and start a task

‍

This example shows you how to create an integration and start a task. The integration we are going to create is using ServiceNow and we will create a new incident.

‍

1. Create the integration 

‍

Let’s start by making an authenticated call to create a new integration. We will use a POST request, the URL and request body will look like the following:

/core/integrations

The request body will look like the following:

‍

{
  "data": {
    "type": "integration",
    "attributes": {
      "name": "ServiceNow Integrations",
      "image_url": "https://client_name.cutover.com(or.net)/img/integrations/ServiceNow.png",
      "kind": "custom"
    }
  }
}

‍

Once the API call has been executed, you will need to store the integration ID. The integration ID is required to create a new integration action.

‍

2. Create a new integration action

‍

Now that the integration is in place, you will need to create an integration action that will generate a ServiceNow incident. To begin, make an authenticated call to create a new integration action. This will be done using a POST request, and the URL will be structured as follows:

/core/integration_actions

The request body will look like the following:

‍

{
"data": {
		"type": "integration_action",
		"attributes": {
			"global": true,
			"hooks": [
				"task/started"
			],
			"image_url": "https://api.client_name.cutover/img/integrations/SNow.png",
			"kind": "custom/payload",
			"name": "Create Incident,
			"option_overrides": {
				"auto_start": false,
				"cancellable": true,
				"notify_on_cancel": false,
				"enable_start_fixed": false,
				"execute_in_rehearsal": true,
				"finish_task_on_success": true,
				"include_context_in_request": false
			},
			"settings": {
				"auth_type": "token",
				"request_type": "POST",
				"response_mode": "none",
				"webhook_url": "https://<your-domain>/api/now/table/incident",
				"outbound_headers": "{\n  \"Content-Type\": \"application/json\"\n}",
				"outbound_payload": "{\"short_description\":\"Short description\"}",
				"encrypted": true,
				"token_auth_type": "Basic",
				"token_auth_value": "*********************"
			}
		},
		"relationships": {
			"integration": {
				"data": {
					"id": "integration ID",
					"type": "integration"
	}
          }
        }
    }
}

‍

3. Test the integration action

Now that the integration action has been created, you will need to create a runbook and a task to test the integration.  

Firstly, you will need to make an authenticated call to create a new runbook. We will use a POST request, the URL will be structured as follows:

‍

/core/runbooks

The request body will look like the following:

‍

{
  "data": {
    "type": "runbook",
    "attributes": {
      "name": "Enter the name of the RB"
    },
    "relationships": {
      "workspace": {
        "data": {
          "id": "ID of workspace",
          "type": "workspace"
        }
      }
    }
  }
}

‍

The ID of the workspace can be retrieved using the List workspaces endpoint. Once the API call has been executed, you will need to store the runbook ID.

‍

A second API call must be made to create the integration task. Before proceeding, the task ID for the "Create incident" integration action must be obtained. This can be retrieved using the List integration action API. Once the task ID has been identified, you can proceed to use the Create a task API. This involves a POST request, and the URL will be formatted as follows:

core/runbooks/{runbook_id}/tasks

The request body will look like the following:

‍

{
  "data": {
    "type": "task",
    "attributes": {
      "name": "Create Incident"
    },
    "relationships": {
      "stream": {
        "data": {
          "id": "stream ID",
          "type": "stream"
        }
      },
      "task_type": {
        "data": {
          "id": "task ID",
          "type": "task_type"
        }
      }
    }
  }
}

‍

Before running the integration, the runbook must be initiated. Use the Start a Runbook API, which requires a PATCH request. The URL for this request will be formatted as follows:

/core/runbooks/{id}/start

The request body will look like the following:

‍

{
  "meta": {
    "comms": "on",
    "run_type": "live",
    "rebaseline": true,
    "shift_fixed_times": true
  }
}

‍

To execute the task integration, use the start a task call, which requires a PATCH request. The URL for this request will be formatted as follows:

/core/runbooks/{runbook_id}/tasks/{id}/start

The request body will look like the following:

‍

{
  "meta": {
    "override": true
  }
}

‍

The integration has successfully fired in the runbook.

‍

‍