workflows.create

Note: This method is only available to Fabric customers.

Create a Self Service Workflow. A workflow is the definition you configure in DX (identifier, parameters, HTTP request, scope, and filters).

When called with a personal access token, the issuing user must be a Self-Service Admin. Organization tokens with the workflows:create scope are also accepted.

See the workflows.list method to list existing workflows, and workflowRuns.trigger to run one.

Facts


Method	`POST https://api.getdx.com/workflows.create`
Required scope	`workflows:create`

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`identifier`	`Text`	Unique identifier of the workflow. May only contain letters, numbers, underscores, periods, and hyphens.
`name`	`Text`	Display name of the workflow.
`scope`	`Text`	`GLOBAL` or `ENTITY`.
`execution_type`	`Text`	`SIMPLE` or `EVENT_DRIVEN`.
`entity_filter_type`	`Text`	`ENTITY_TYPES` or `SQL`. Determines which entities an `ENTITY`-scoped workflow applies to.
`http_request`	`Object`	The HTTP request sent when the workflow runs. See `http_request`.

Optional arguments

Name	Type	Description
`description`	`Text`	Description of the workflow.
`icon`	`Text`	Icon for the workflow.
`color`	`Text`	Color for the workflow, as a hex value (for example `#38bdf8`).
`trigger_type`	`Text`	Who can trigger the workflow: `ANY`, `APPROVAL`, `RUNNERS`, or `ENTITY`. Defaults to `ANY`. `ENTITY` requires `scope` of `ENTITY`.
`entity_filter_type_identifiers`	`Array<Text>`	Identifiers of the entity types the workflow applies to. Required (at least one) when `scope` is `ENTITY` and `entity_filter_type` is `ENTITY_TYPES`.
`entity_filter_sql`	`Text`	SQL that selects the entities the workflow applies to. Required when `scope` is `ENTITY` and `entity_filter_type` is `SQL`.
`parameters`	`Array<Object>`	Parameters collected when the workflow is run. See Workflow parameters.
`approver_user_ids`	`Array<Text>`	IDs of active users who approve runs. Required (at least one) when `trigger_type` is `APPROVAL`.
`runners`	`Array<Object>`	Users or teams allowed to run the workflow. Required (at least one) when `trigger_type` is `RUNNERS`. Each item has one of `user_id`, `squad_id`, or `squad_linkage_id`, and must belong to your account.

`http_request`

Name	Type	Description
`method`	`Text`	`GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.
`url`	`Text`	The URL to send the request to.
`headers`	`Object`	Request headers as key/value pairs. Use `{}` for none.
`body`	`Text`	Request body, or `null`. Must be `null` when `form_data` is provided.
`form_data`	`Array<Object>`	Optional. Form fields, each with a `key` and a `value`.

The url, body, headers, and form_data values may reference variables. Variables that are not available for the workflow’s scope or that reference undefined parameters are rejected with invalid_variables_in_http_request.

Workflow parameters

Workflow parameters are the inputs a user provides each time the workflow is run. They are not arguments to this API call. Reference them in the http_request as {{data.<identifier>}}, and pass their values in the data object of workflowRuns.trigger.

Name	Type	Description
`identifier`	`Text`	Identifier of the parameter. Used as the key in the `data` object of `workflowRuns.trigger`.
`name`	`Text`	Display name of the parameter.
`type`	`Text`	`STRING`, `INTEGER`, `FLOAT`, `BOOLEAN`, `SELECT`, `USER`, `TEAM`, `EMAIL`, or `COMPUTED`.
`is_required`	`Boolean`	Whether a value must be provided when running the workflow.
`description`	`Text`	Optional. Description of the parameter.
`default_value`	`Text`	Optional. Default value. Must be valid for `type`. Not allowed for `COMPUTED` parameters.
`definition`	`Object`	Required for `SELECT` and `COMPUTED` parameters. For `COMPUTED`, an object with a `sql` key returning `value` and `label` columns.

Creating a COMPUTED parameter when authenticated with a personal access token requires the issuing user to have Data Studio access. Organization tokens are not subject to this check.

Example request

This is a typical request:

curl -X POST https://api.getdx.com/workflows.create \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  --data '{
    "identifier": "provision-single-tenant-instance",
    "name": "Provision Single-tenant Instance",
    "description": "Create a new single-tenant instance and associate with an account",
    "icon": "globe",
    "color": "#38bdf8",
    "scope": "ENTITY",
    "execution_type": "EVENT_DRIVEN",
    "entity_filter_type": "ENTITY_TYPES",
    "entity_filter_type_identifiers": ["service"],
    "trigger_type": "ANY",
    "parameters": [
      {
        "identifier": "app_name",
        "name": "App name",
        "description": "The all-lowercase name of the app to provision.",
        "type": "STRING",
        "is_required": true
      }
    ],
    "http_request": {
      "method": "POST",
      "url": "https://example.com/api/provision",
      "headers": { "Content-Type": "application/json" },
      "body": "{\"app_name\": \"{{data.app_name}}\"}"
    }
  }'

Example response

This is a typical success response.

{
  "ok": true,
  "workflow": {
    "identifier": "provision-single-tenant-instance",
    "name": "Provision Single-tenant Instance",
    "description": "Create a new single-tenant instance and associate with an account",
    "icon": "globe",
    "color": "#38bdf8",
    "scope": "ENTITY",
    "entity_filter_type": "ENTITY_TYPES",
    "entity_filter_sql": null,
    "entity_filter_type_identifiers": ["service"],
    "execution_type": "EVENT_DRIVEN",
    "trigger_type": "ANY",
    "parameters": [
      {
        "identifier": "app_name",
        "name": "App name",
        "description": "The all-lowercase name of the app to provision.",
        "default_value": null,
        "is_required": true,
        "type": "STRING",
        "definition": null
      }
    ]
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok param in the response.

Error	Description
`not_authed`	No authentication token provided.
`invalid_auth`	Some aspect of authentication cannot be validated.
`not_authorized`	The token lacks the `workflows:create` scope, or the personal access token’s user is not a Self-Service Admin.
`missing_content_type`	A request body was sent without a `Content-Type` header.
`invalid_json`	The request body is not valid JSON.
`Missing required parameter: <name>`	`identifier` or `name` was not provided.
`Invalid parameter: <message>`	The workflow failed validation, for example a duplicate or malformed `identifier`, an invalid `scope`, or a malformed `http_request`. The message describes each problem.
`workflow_parameter_validation_failed`	A parameter is invalid. `error_details.parameter_index` is the zero-based index of the offending parameter and `error_details.errors` describes the problems.
`workflow_approver_validation_failed`	`approver_user_ids` is empty or contains users that are not active users in your account when `trigger_type` is `APPROVAL`.
`workflow_runner_validation_failed`	`runners` is empty when `trigger_type` is `RUNNERS`, or a runner is invalid or does not belong to your account.
`invalid_variables_in_http_request`	The `http_request` references variables that are not available. `error_details.errors` lists the offending fields.