Create a workflow that calls an external API - Data360_Govern - Preview

Step 1 - Build the workflow

This example assumes that you have already created an Action Type on which you want to base the workflow. For more information on Action Types, see Defining Action Types.

1. Navigate to Configuration > Workflows.
2. Click the Add button in the Workflow Types panel to create a new workflow.
3. Enter a Name for the workflow, for example "Jira ticket creation".
4. From the Change Type list, select Item Added.
5. From the Object Type list, select your data quality Action Type, for example Action Type :: Report data quality issue.
6. Click Next.
7. Build the workflow by dragging the required activities from the left of the screen into the workflow editing area. For example:

   

Step 2 - Configure the HTTP Request activity

Configure the HTTP Request activity to send a POST request to Jira to create a new ticket.

The exact settings that are required to configure the HTTP Request activity will vary depending on the external API that you are connecting to. The following example shows how to configure this workflow activity to connect to the Jira API.

1. Select the HTTP Request activity in the workflow that you built in the previous step.
2. Add the following request Headers:

   Key	Value
   Authorization	Basic <base64 encoded email address:API key>
   Content-Type	application/json

   You can also use a workflow token in the Value field of the header. They cannot, however, be used in the Key field. To include a token, either:

   • Enter it manually, or:
   • Copy it from elsewhere and paste it in the Value field.

   When the workflow runs, the tokens are replaced with their value.

   To create your Authorization header value:Combine the email address that you use to connect to Jira with your Jira API key, in the following format:<email_address>:<API_key>Then, base64 encode this value.Take the base64 encoded value and add this to the Authorization header value column, preceded by the word Basic and a space, for example:

   Basic FG5vYmxlQGluZm7mbXguY30uOmD5S3QoEjAnejKLUYpWZ2Y1enlvPLMxOQ==

   For information on obtaining your Jira API key, see the Jira documentation, for example: https://confluence.atlassian.com/cloud/api-tokens-938839638.html

   Note: If you use any of the following Content headers, you must also specify a value in the Body field: "Content-Type", "Content-MD5", "Content-Encoding" and "Content-Length". If you use one of these headers without a Body value, the HTTP Request workflow step will not complete.
3. Select the Method. Choose from: GET, POST, PUT or DELETE. In this case, select POST.
4. Enter the URL of the external API endpoint, for example: https://example.atlassian.net/rest/api/2/issue
   Tip: You can use Append field value tokens in the URL by copying and pasting the token value from the Body field. See Configuring email notifications for token examples.
5. Enter the request Body. For example, to create a new ticket in Jira, you can use JSON to reference the Jira project key and fields:

   {
     "fields": {
         "project":
         {
           "key": "TEST"
         },
         "summary": "Data quality issue",
         "description": "A data quality issue has been raised in Data360 Govern.",
         "issuetype": {
           "name": "Bug"
         }
     }
   }

   This creates a new Jira bug in the "TEST" project, with a summary and description that matches the information included in the request body:

   

6. Set the required Request Timeout period, up to a maximum of 600 seconds. The default value is 90 seconds.

For more information on implementing this example, see the Jira documentation, for example: https://developer.atlassian.com/server/jira/platform/jira-rest-api-examples/

Step 3 - Configure the conditional transitions

Use conditional transitions to determine which email (failure or success) is sent to the initiator of the workflow.

1. On the transition leading to the successful Email Notification activity, add the following condition:

   Field	Operator	Value
   HTTP Request :: Status Code	<	299

   This specifies that an email indicating that the HTTP request was successful will be sent if the HTTP response status code is less than 299.

2. On the transition leading to the failure Email Notification activity, add the following condition:

   Field	Operator	Value
   HTTP Request :: Status Code	>	299

   This specifies that an email indicating that the HTTP request failed will be sent if the HTTP response status code is greater than 299.

Step 4 - Configure the Email Notification activities

1. Select the successful Email Notification activity and type a Name, such as "POST request successful".
2. In the Recipient Type, select Initiator.
3. Type a Subject and Body for the email. For example, the Body could be:

   A new Jira ticket has been created to track a data quality issue. The HTTP response status code is: [HTTPREQUEST|365|statusCode]The response body is: [HTTPREQUEST|365|responseBody]

   This example uses the HTTP Request :: Status Code and HTTP Request :: Response Body tokens, which will be replaced with the API response values in the email that is sent to the initiator, for example:

   

   In the email, the response body provides the ticket number of the new bug that was created in Jira.

4. Select the failure Email Notification activity and type a Name, such as "POST request failed".
5. In the Recipient Type, select Initiator.
6. Type a Subject and Body for the email. For example, the Body could be:

   An error occurred preventing a new Jira ticket from being created. The HTTP response status code is: [HTTPREQUEST|365|statusCode] The response body is: [HTTPREQUEST|365|responseBody]

   This example uses the HTTP Request :: Status Code and HTTP Request :: Response Body tokens, which will be replaced with the API response values in the email that is sent to the initiator, for example:

   

   The email provides details of the error in the response body as well as the response status code, enabling you to troubleshoot the issue.

Step 5 - Add a HTTP Response task

A HTTP Response task can be added to an HTTP Request workflow, to enable subsequent steps to extract JSON-based properties from the relevant API.

1. Create a new HTTP Response workflow task.

2. Using the Edit tab of the HTTP Response task editor panel, select the appropriate upstream HTTP Request task, to connect to the input.

3. Under Outputs, click the Add button (+) to display the output configuration fields, and enter:

   1. A recognizable Name of your choice. For example, "Jira Key".
   2. The correct and valid JSON Path.
   Note: If the path is invalid, or the response doesn't contain the property that the path is targeting (for example, if the request fails) the value will be an empty string.

   For example, if the JSON Path is set to "key", the response from the API may be similar to the following:

   {

   "id":"1234",

   "key":"GOV-16569",

   "self":"http://localhost:8080/rest/api/2/issue/1234"

   }

Other steps in the workflow can now use the response output values. For example, in email tokens or in a field change step.