# Workflows

## List Workflows

This endpoint is used to list all active workflows in your parent Alloy Forge account. This endpoint is most commonly used to render an integrations page and display which workflows a user may enable.

You can also filter workflows based on particular integrations by specifying the optional query parameter `integration`

## List Workflows

<mark style="color:blue;">`GET`</mark> `https://api.runalloy.com/forge/2021-12/workflow`

#### Query Parameters

| Name        | Type   | Description                                             |
| ----------- | ------ | ------------------------------------------------------- |
| integration | String | The name of the integration you want to filter based on |

#### Headers

| Name                                                            | Type   | Description                          |
| --------------------------------------------------------------- | ------ | ------------------------------------ |
| Authorization Bearer {apiKey}<mark style="color:red;">\*</mark> | String | Your Forge API key for authorization |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "data": [
    {
      "workflowId": "61ab9079251cba0014437327",
      "name": "Alert Slack team when an order is paid in Shopify",
      "integrations": [
        {
          "name": "shopifyApi",
          "displayName": "Shopify",
          "icon": "https://cdn.runalloy.com/icons/shopify.png",
          "type": "oauth",
          "requiredParameters": [
            {
              "name": "shopSubdomain",
              "displayName": "Shopify Subdomain",
              "description": "The store subdomain. For example, if the store URL is https://abcstore.myshopify.com, the subdomain is abcstore."
            }
          ]
        },
        {
          "name": "slackApi",
          "displayName": "Slack",
          "icon": "https://cdn.runalloy.com/icons/slack.png",
          "type": "oauth"
        }
      ],
      "blocks": [
        {
                  "name": "Webhook",
                  "id": "1c3514f5-1772-4106-bf12-3f15195aa6d3",
                  "type": "alloy.webhook",
                  "parameters": {
                      "authentication": "authenticated",
                      "bodyParameters": {}
                  }
              },
              {
                  "name": "Clearbit",
                  "id": "55f3ffed-6fe8-4e81-a21d-3ae1549faa92",
                  "type": "alloy.clearbit",
                  "parameters": {
                      "resource": "company",
                      "operation": "enrich",
                      "domain": "google.com",
                      "companyName": "",
                      "facebook": "",
                      "linkedin": "",
                      "twitter": "",
                      "sampleDataLimit": 3
                  }
              },
              {
                  "name": "Variable",
                  "id": "87bb2c9f-469a-40b6-b168-e38477e89dfd",
                  "type": "alloy.variable",
                  "parameters": {
                     "variables": [
                       {
                         "uuid": "8c369ae7-59ec-4b15-b8ff-61f291e28fe5",
                         "name": "accountNumber",
                         "value": "123"
                       },
                       {
                         "uuid": "1cd295bd-3ca1-4a2b-d57d-ce0092cf41be",
                         "name": "accountName",
                         "value": "ACME Loyalty"
                       }
                     ]
                  }
              },
              {
                  "name": "Shopify",
                  "id": "92cef4be-c74a-411b-9e2a-843d29dc6462",
                  "type": "alloy.shopify",
                  "parameters": {
                      "resource": "customers",
                      "operation": "createCustomer",
                      "properties": [
                          {
                              "uuid": "45bc6f19-d302-4820-9d81-cdb7e69758c5",
                              "first_name": "",
                              "last_name": "",
                              "phone": "",
                              "note": "={{$block[\"87bb2c9f-469a-40b6-b168-e38477e89dfd\"].data[\"variables\"][\"accountNumber\"]}}",
                              "tags": [
                                  []
                              ],
                              "send_email_invite": "",
                              "password": "",
                              "password_confirmation": "",
                              "send_email_welcome": "",
                              "accepts_marketing": "",
                              "accepts_marketing_updated_at": "",
                              "marketing_opt_in_level": "",
                              "tax_exempt": "",
                              "tax_exemptions": ""
                          }
                      ],
                      "email": "example@example.com"
                  }
              },
      ]
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Activate a Workflow

This endpoint is used to activate a child workflow in Alloy. Note that you must first have created the child workflow with the Forge Modal. Child workflows are active when they are created, so this endpoint is primarily used in conjunction with the Deactivate Workflow endpoint to toggle child workflows off and on. For more on child workflows, please read our doc [here](https://gregg.gitbook.io/alloy-developer/forge-concepts#parent-and-child-workflows).

## Activate a Workflow

<mark style="color:orange;">`PUT`</mark> `https://api.runalloy.com/forge/2021-12/workflow/:workflowId/activate`

Activates a user configured workflow

#### Path Parameters

| Name                                         | Type   | Description                                 |
| -------------------------------------------- | ------ | ------------------------------------------- |
| workflowId<mark style="color:red;">\*</mark> | String | The Id of the workflow you want to activate |

#### Headers

| Name                                                            | Type   | Description                          |
| --------------------------------------------------------------- | ------ | ------------------------------------ |
| Authorization Bearer {apiKey}<mark style="color:red;">\*</mark> | String | Your Forge API key for authorization |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "activated": true
}
```

{% endtab %}
{% endtabs %}

## Deactivate a Workflow

This endpoint turns off a child workflow when given a workflow Id. When deactivated, the workflow becomes inactive and any incoming webhooks or regular runs will be disabled immedaitely.

## Deactivates the Workflow

<mark style="color:orange;">`PUT`</mark> `https://api.runalloy.com/forge/2021-12/workflow/:workflowId/deactivate`

Turns off all future runs of a user-specific workflow in Forge.

#### Path Parameters

| Name                                         | Type   | Description                                 |
| -------------------------------------------- | ------ | ------------------------------------------- |
| workflowId<mark style="color:red;">\*</mark> | String | The Id of the workflow you want to activate |

#### Headers

| Name                                                            | Type   | Description                          |
| --------------------------------------------------------------- | ------ | ------------------------------------ |
| Authorization Bearer {apiKey}<mark style="color:red;">\*</mark> | String | Your Forge API key for authorization |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "activated": false
}
```

{% endtab %}
{% endtabs %}

## Disable all Workflows for a User

This endpoint is used to disable all active workflows for a given user. The `userId` value represents the unique identifier for each user and can be obtained from the **List all Users** endpoint.

<mark style="color:purple;">`PATCH`</mark> `https://api.runalloy.com/forge/2021-12/user/:userId/disableWorkflows`&#x20;

#### Headers

| Name                                                            | Type   | Description                          |
| --------------------------------------------------------------- | ------ | ------------------------------------ |
| Authorization Bearer {apiKey}<mark style="color:red;">\*</mark> | String | Your Forge API key for authorization |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "message": "success"
}
```

{% endtab %}
{% endtabs %}

## Get workflow logs

This endpoint retrieves the logs of execution data for a workflow. The `workflowId` corresponds to a specific user's workflow. You can page through the results with the `page`, `limit`, and `order` query parameters.&#x20;

## Get Workflow logs

<mark style="color:blue;">`GET`</mark> `https://api.runalloy.com/forge/2021-12/workflow/:workflowId/logs`

#### Query Parameters

| Name  | Type   | Description                                               |
| ----- | ------ | --------------------------------------------------------- |
| page  | Number | page of results                                           |
| limit | Number | Number of results per page (max 30, default 10)           |
| order | String | `asc` or `desc` for ascending/descending (default `desc`) |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{

    "data": [
        {
            "executionId": "62145ffc4cd971057a204fcc",
            "startedAt": "2022-02-22T04:01:00.512Z",
            "stoppedAt": "2022-02-22T04:01:02.298Z",
            "finished": true,
            "results": [
                {
                    "blockId": "d504be51-ae37-42f7-9a63-bf4197d06f29",
                    "startedAt": "2022-02-22T04:01:00.512Z",
                    "stoppedAt": "2022-02-22T04:01:00.512Z",
                    "data": [
                        [
                            {
                                "json": {
                                    "body": {
                                        "customerId":"gid://shopify/Customer/6116254253275"
                                    },
                                },
                                "id": "da9e8413-b7f4-402c-a36f-2965032ef2ee"
                            }
                        ]
                    ]
                },
                {
                    "blockId": "a2140760-5844-4b63-b2f9-8855ff1965e4",
                    "startedAt": "2022-02-22T04:01:00.548Z",
                    "stoppedAt": "2022-02-22T04:01:01.631Z",
                    "data": [
                        [
                            {
                                "json": {
                                    "customer": {
                                            "id": 6116254253275,
                                            "email": null,
                                            "accepts_marketing": false,
                                            "created_at": "2022-02-21T14:21:26-08:00",
                                            "updated_at": "2022-02-21T14:21:26-08:00",
                                            "first_name": "test",
                                            "last_name": null,
                                            "orders_count": 0,
                                            "state": "disabled",
                                            "total_spent": "0.00",
                                            "last_order_id": null,
                                            "note": null,
                                            "verified_email": true,
                                            "multipass_identifier": null,
                                            "tax_exempt": false,
                                            "phone": null,
                                            "tags": "",
                                            "last_order_name": null,
                                            "currency": "USD",
                                            "addresses": [],
                                            "accepts_marketing_updated_at": "2022-02-21T14:21:26-08:00",
                                            "marketing_opt_in_level": null,
                                            "tax_exemptions": [],
                                            "admin_graphql_api_id": "gid://shopify/Customer/6116254253275"
                                        }
                                    
                                },
                                "id": "f31b2169-aa17-42d7-8f32-a0f3f76e2129"
                            }
                        ]
                    ]
                },
                {
                    "blockId": "5a4bc255-0893-4233-b370-42e49e0f3ffe",
                    "startedAt": "2022-02-22T04:01:02.259Z",
                    "stoppedAt": "2022-02-22T04:01:02.268Z",
                    "data": [
                        [
                            {
                                "json": {
                                    "value": "test"
                                },
                                "id": "86371891-ec76-4fad-a24d-d75ccaaa17d4"
                            }
                        ]
                    ]
                }
            ]
        }
    ]

}
```

{% endtab %}
{% endtabs %}

## Set workflow variables

You may find that your workflows require user-specific values which need to be provided programmatically, not through the Forge Modal. In order to achieve this, you can add a Variable Block to the workflow, specify as many fields as you need, and then use those fields later in the workflow where the user-specific values are required. After a user creates a child workflow, use this endpoint to set the user-specific values in the Variable Block. For example, a Variable Block with the following setup:&#x20;

![](/files/dBPq5pNaeZZnU0zaRJbe)

should have the following request body:

```
{
  "accountNumber": 234234234,
  "accountName": "A Real Account Name"
}

```

## Set Variable Block values

<mark style="color:purple;">`PATCH`</mark> `https://api.runalloy.com/forge/2021-12/workflow/:workflowId/variables/:blockId`

Set the values for fields defined in a variable block for a specified child workflow.

#### Path Parameters

| Name                                         | Type   | Description                                                                                                                                                                                    |
| -------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| workflowId<mark style="color:red;">\*</mark> | String | `_id` of the child workflow                                                                                                                                                                    |
| blockId<mark style="color:red;">\*</mark>    | String | `id` of the variable block (a uuid4 value). The blockId is consistent between parent/child workflows, so it is safe the record the value from the parent workflow to be used in every request. |

#### Request Body

| Name          | Type   | Description                                                                               |
| ------------- | ------ | ----------------------------------------------------------------------------------------- |
| variableName1 | String | Variable names must match what you entered in Variable Name fields on the Variable block. |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gregg.gitbook.io/alloy-developer/reference/api-reference/workflows.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.