API Workflow - Run Plan

Contents:

This section describes how to run a plan using the APIs available in  Trifacta® Wrangler Pro.

• A plan is a scheduled sequence of tasks based on a trigger that you define. 
  • When a plan is executed via API, the request is the trigger, and the plan is executed immediately. 
• Plans can be designed in the Trifacta application. For more information, see Plans Page.
• For more information on plans in general, see Overview of Operationalization.

A note about API URLs:

In the listed examples, URLs are referenced in the following manner:

<protocol>://<platform_base_url>/

In your product, these map references map to the following:

<http or https>://<hostname>:<port_number>/

For more information, see API Reference.

Pre-requisites

Before you begin, you should verify the following:

1. Get authentication credentials. As part of each request, you must pass in authentication credentials to the platform. 

   Tip: The recommended method is to use an access token, which can be generated from the Trifacta application. For more information, see Access Tokens Page.

   For more information, see  https://api.trifacta.com/saas-pro/index.html#section/Authentication

2. Verify plan and its flows and outputs:
   1. You must create a plan first. See Plan View Page.

   2. As part of creating that plan, you must verify that all referenced flows and output objects are properly defined and can be executed independently. 

      NOTE: In a flow, all recipes that you wish to have executed by the corresponding task must have a defined output object. For each output object, you must create at least one write settings or publication object. During plan runs, these objects are not validated, and tasks fail without them.

   3. Any applicable parameters are applied to the tasks at the time of execution. Parameter overrides are not supported in plans.
   4. See Flow View Page. 
3. Verify plan execution. Run the desired plan through the Trifacta application and verify that the output objects are properly generated. See Plan View Page.

4. Acquire plan identifier. In Plan View, acquire the numeric value for the plan from the URL. In the following, the plan Id is 1234:

   http://<platform_base_url>/plans/1234

Step - Run Plan

Through the APIs, you can run a plan. Construct a request like the following, where:

• <id> is the plan identifier that you already extracted from the Plan View URL.

{
    "validationStatus": "Valid",
    "planSnapshotRunId": 2
}

If the 201 response code is returned, then the plan has been queued for execution. 

For more information, see  https://api.trifacta.com/saas-pro/index.html#operation/runPlan

Step - Run Plan with Overrides

When you run your plan, you can apply overrides to any of the parameters that are sourced in flow tasks within the plan. Overrides are applied in the body request when submitting to the plan run API endpoint.

{
  "planNodeOverrides": [
    {
      "handle": "ax",
      "overrideKey": "region",
      "value": {
        "variable": {
          "value": "02"
        }
      }
    },
    {
      "handle": "cq",
      "overrideKey": "state",
      "value": "CA"
    }
  ]
}

{
    "validationStatus": "Valid",
    "planSnapshotRunId": 2
}

<task_type>-<handleId>

If the 201 response code is returned, then the plan has been queued for execution. 

For more information, see  https://api.trifacta.com/saas-pro/index.html#operation/runPlan

Step - Monitoring Your Plan Run

You can monitor the status of your plan run through the following endpoint, where:

• <id> is the plan snapshot identifier for your run that you retained from the previous step.

{
    "id": 2,
    "status": "InProgress",
    "scheduleHistoryId": null,
    "startedAt": "2020-04-23T17:53:33.466Z",
    "finishedAt": null,
    "submittedAt": "2020-04-23T17:53:32.993Z",
    "executionId": null,
    "createdAt": "2020-04-23T17:53:33.312Z",
    "updatedAt": "2020-04-23T17:53:33.499Z",
    "plan": {
        "id": 1
    }
}

When the plan run has successfully completed, the returned status message includes the following:

"status": "Complete",

For more information, see  https://api.trifacta.com/saas-pro/index.html#tag/PlanSnapshotRunYou can also review your plan runs through the Trifacta application at the following URL:

<protocol>://<platform_base_url>/plans/<planId>/runs/<planSnapshotRunId>