Skip to main content

Manual workflow references

Run manual workflows within other workflows​

You can include an entire manual workflow as an action in another workflow!

This is known as a Manual Workflow Reference (MWR). If a MWR is added to another workflow, it will receive the output of the previous action as input. The output of the MWR then passes to the next action in that workflow. The MWR's output is determined by choosing an action within the manual workflow to provide a final output.

It involves creating a unique trigger parameter design for use by a single manual workflow. This one-to-one association causes the manual workflow to appear in the actions list when building another workflow in Alloy Web. Alternatively, API users can specify the parameter design when adding/editing an action in another workflow.

Note

While it's possible to create a chain of nested workflows (e.g. a workflow that references a manual workflow that references a manual workflow...), Alloy will stop you from creating any circular references! 😮‍💨 A manual workflow can't reference itself!

Create a parameter design​

First, create a trigger parameter design for the manual workflow:

  1. Create a new design (Swagger/ReDoc).

    POST /api/design
    {
      "name": "My Red ManualWF Parameters",
      "colour": "#df412c",
      "icon": "icon-math-brackets",
      "geometryRequired": false,
      "geometryAllows": [],
      "collections": ["Live"]
    }
    Note

    In the following steps, substitute {code} in the endpoint URL with your new design's code, e.g. designs_myRedManualWFParameters_6697e5eaad24446802f04e2e.

  2. Edit the design to make it implement the Manual Workflow Trigger interface (Swagger/ReDoc).

    POST /api/design/{code}/interface
    {
      "interfaceCode": "designInterfaces_workflowManualTrigger",
      "signature": "667b063d535060cadd3605eb"
    }

  3. To define any trigger parameters for the manual workflow, add them as attributes on your parameter design (Swagger/ReDoc). If an attribute is set as Required, a value must be supplied for that parameter when the manual workflow is run. If an attribute has the ActionParameter tag set, it will be visible in Alloy Web (when adding the MWR to another workflow).

    POST /api/design/{code}/attribute
    {
      "name": "StringParam",
      "required": true,
      "readonly": false,
      "unique": false,
      "tags": ["ActionParameter"],
      "options": {
        "max": 128,
        "indexed": true,
        "discriminator": "DodiAttributeOptionsStringWebModel"
      },
      "signature": "667b06c6535060cadd362355"
    }

Edit the manual workflow​

Configure the trigger​

Edit the trigger of the manual workflow (Swagger/ReDoc). You must set its parametersDesignCode to the parameter design's code. You must also set outputActionId to the ID of an action in the manual workflow that represents the final output. When the MWR is added to another workflow, this output will pass to the next action in that workflow.

PUT /api/workflow/{code}
{
  "name": "My Red ManualWF",
  "enabled": true,
  "description": "A manual workflow that makes defects red and edits their description",
  "trigger": {
    "dodiCode": "designInterfaces_items",
    "outputMode": "ManyItems",
    "parametersDesignCode": "designs_myRedManualWFParameters_6697e5eaad24446802f04e2e",
    "outputActionId": "6697eac4ad24446802f05018",
    "discriminator": "ManualTrigger"
  },
  "failureNotification": {
    "username": "teresagreen"
  }
}
Note

In the above step, substitute {code} in the endpoint URL with your manual workflow's code, e.g workflows_myRedManualWF_6697eaa7ad24446802f04ff3.

Use trigger parameters in actions​

When adding or editing the actions of the manual workflow, you can use a trigger parameter by defining it as an action parameter, or as a variable that all actions in the workflow can access. Currently, this is only possible via the Alloy API.

Add a MWR to another workflow​

Once you've set up your manual workflow, you can reference it in other workflows. To do this, add an action to the other workflow that uses your parameter design (Swagger/ReDoc).

To supply values for any trigger parameters, set the value of the corresponding attribute on the parameter design. Like any action parameter, you can supply a constant web model, or a computed web model that generates a dynamic value.

Alternatively, you can add a MWR to a workflow using Alloy Web.

POST /api/workflow/{code}/action
{
  "actionDesignCode": "designs_myRedManualWFParamDesign_6697e5eaad24446802f04e2e",
  "ancestorId": "669800f3ad24446802f061b1",
  "parameters": [
    {
      "attributeCode": "attributes_myRedManualWFParamDesignStringParam_66980133ad24446802f061d6",
      "value": {
        "template": "Defect $varDefectNum is considered DANGEROUS",
        "discriminator": "WorkflowSyntaxNodeTemplateWebModel"
      },
      "discriminator": "WorkflowComputedItemAttributeWebModel"
    }
  ],
  "variables": [
    {
      "name": "varDefectNum",
      "value": {
        "inputParent": 0,
        "itemValue": {
          "attributeCode": "attributes_defectsDefectNumber",
          "discriminator": "WorkflowSyntaxArgumentItemValueAttributeWebModel"
        },
        "discriminator": "WorkflowSyntaxNodeInputWebModel"
      }
    }
  ],
  "description": "This action is a MWR",
  "signature": "6698c25dd2083fc6d082d254"
}
Note

In the above step, substitute {code} in the endpoint URL with your other workflow's code, e.g workflows_myOtherWorkflow_669800f3ad24446802f061b2.

Example workflow models​

For reference, here are example models for both workflows described in this article. Note that parts have been removed for brevity, so they can't be used as is.

My Red ManualWF
{
  "workflow": {
    "workflow": {
      "name": "My Red ManualWF",
      "description": "A manual workflow that makes defects red and edits their description",
      "context": "Customer",
      "tags": [],
      "enabled": true,
      "trigger": {
        "dodiCode": "designInterfaces_defects",
        "outputMode": "ManyItems",
        "parametersDesignCode": "designs_myRedManualWFParameters_6697e5eaad24446802f04e2e",
        "outputActionId": "6697eac4ad24446802f05018",
        "discriminator": "ManualTrigger"
      },
      "triggerNodeInfo": {
        "id": "6697eaa7ad24446802f04ff2",
        // this `output` contains the model of the `dodiCode` value
        // its contents are omitted for brevity!
        "output": { },
  "actions": [
    {
      // this `actionDesign` contains the standard model of the Edit action design
      // its contents are omitted for brevity!
      "actionDesign": { },
      "actionId": "6697eac4ad24446802f05018",
      "actions": [
        {
           // this `actionDesign` contains the standard model of the Message action design
           // its contents are omitted for brevity!
          "actionDesign": { },
          "actionId": "6698d3ded2083fc6d082d849",
          "actions": [],
          "parameters": [
            {
              "attribute": {
                "attributeCode": "attributes_workflowMessageActionMessageType",
                "value": ["5c66bcd44b4d4259071069de"]
              },
              "discriminator": "WorkflowConstantItemAttributeWebModel"
            },
            {
              "attribute": {
                "attributeCode": "attributes_workflowMessageActionMessageText",
                "value": "This defect is now red"
              },
              "discriminator": "WorkflowConstantItemAttributeWebModel"
            },
            {
              "attribute": {
                "attributeCode": "attributes_workflowMessageActionRecipientName",
                "value": "Teresa"
              },
              "discriminator": "WorkflowConstantItemAttributeWebModel"
            },
            {
              "attributeCode": "attributes_workflowMessageActionLinkedItems",
              "virtualDefinition": "$input(0)$itemId$",
              "discriminator": "WorkflowVirtualItemAttributeWebModel"
            },
            {
              "attribute": {
                "attributeCode": "attributes_workflowMessageActionSingleInstance",
                "value": false
              },
              "discriminator": "WorkflowConstantItemAttributeWebModel"
            },
            {
              "attribute": {
                "attributeCode": "attributes_workflowMessageActionEmailAddress",
                "value": "teresa.green@example.com"
              },
              "discriminator": "WorkflowConstantItemAttributeWebModel"
            },
            {
              "attribute": {
                "attributeCode": "attributes_workflowMessageActionEmailSubject",
                "value": "Defect Alert"
              },
              "discriminator": "WorkflowConstantItemAttributeWebModel"
            }
          ],
          "variables": []
        }
      ],
      "parameters": [
        {
          "attributeCode": "attributes_defectsDescription",
          "value": {
            "parameterCode": "attributes_myRedManualWFParametersStringParam_66980133ad24446802f061d6",
            "inputMode": "Each",
            "discriminator": "WorkflowSyntaxNodeTriggerParameterWebModel"
          },
          "discriminator": "WorkflowComputedItemAttributeWebModel"
        },
        {
          "attribute": {
            "attributeCode": "attributes_workflowEditItemActionsColour",
            "value": "#df412c"
          },
          "discriminator": "WorkflowConstantItemAttributeWebModel"
        }
      ],
      "variables": []
    }
  ]
}
My Other Workflow
{
  "workflow": {
    "workflow": {
      "name": "My Other Workflow",
      "context": "Customer",
      "tags": [],
      "enabled": true,
      "trigger": {
        "dodiCode": "designInterfaces_defects",
        "outputMode": "ManyItems",
        "discriminator": "ManualTrigger"
      },
      "triggerNodeInfo": {
        "id": "669800f3ad24446802f061b1",
        // this `output` contains the model of the `dodiCode` value
        // its contents are omitted for brevity!
        "output": { }
  },
  "actions": [
    {
      "actionDesign": {
        "name": "My Red ManualWF Parameters",
        "code": "designs_myRedManualWFParameters_6697e5eaad24446802f04e2e",
        "context": "Customer",
        "implements": [
          {
            "code": "designInterfaces_items",
            "parent": "designs_myRedManualWFParameters_6697e5eaad24446802f04e2e",
            "context": "Customer"
          },
          {
            "code": "designInterfaces_workflowManualTrigger",
            "parent": "designs_myRedManualWFParameters_6697e5eaad24446802f04e2e",
            "context": "Customer"
          }
        ],
        "attributes": [
          {
            "name": "StringParam",
            "code": "attributes_myRedManualWFParametersStringParam_66980133ad24446802f061d6",
            "parent": "designs_myRedManualWFParameters_6697e5eaad24446802f04e2e",
            "context": "Customer",
            "type": "String",
            "required": false,
            "readonly": false,
            "unique": false,
            "tags": ["ActionParameter"],
            "options": {
              "max": 128,
              "indexed": true,
              "discriminator": "DodiAttributeOptionsStringWebModel"
            }
          },
          {
            "name": "Geometry",
            "code": "attributes_itemsGeometry",
            "parent": "designInterfaces_items",
            "context": "Core",
            "type": "GeoJson",
            "required": false,
            "readonly": false,
            "unique": false,
            "tags": [],
            "options": {
              "allows": [
                "Point",
                "MultiPoint",
                "LineString",
                "MultiLineString",
                "Polygon",
                "MultiPolygon",
                "GeometryCollection"
              ],
              "discriminator": "DodiAttributeOptionsGeoJsonWebModel"
            }
          },
          {
            "name": "Title",
            "code": "attributes_itemsTitle",
            "parent": "designInterfaces_items",
            "context": "Core",
            "type": "String",
            "required": false,
            "readonly": false,
            "unique": false,
            "tags": ["Computed"],
            "options": {
              "indexed": true,
              "discriminator": "DodiAttributeOptionsStringWebModel"
            }
          },
          {
            "name": "Subtitle",
            "code": "attributes_itemsSubtitle",
            "parent": "designInterfaces_items",
            "context": "Core",
            "type": "String",
            "required": false,
            "readonly": false,
            "unique": false,
            "tags": ["Computed"],
            "options": {
              "indexed": true,
              "discriminator": "DodiAttributeOptionsStringWebModel"
            }
          }
        ],
        "metadata": {
          "createdDate": "2024-07-17T15:40:26.432Z",
          "createdUserUsername": "benarnour",
          "lastEditDate": "2024-07-18T09:04:22.220Z",
          "lastEditUserUsername": "benarnour",
          "signature": "6698da96d2083fc6d082dc37"
        },
        "dodiColour": {
          "value": "#df412c",
          "parent": "designs_myRedManualWFParameters_6697e5eaad24446802f04e2e"
        },
        "dodiIcon": {
          "value": "icon-file-code",
          "parent": "designs_myRedManualWFParameters_6697e5eaad24446802f04e2e"
        },
        "geometryRequired": {
          "value": false,
          "parent": "engine_defaultedProperties"
        },
        "geometryAllows": {
          "values": [
            "Point",
            "MultiPoint",
            "LineString",
            "MultiLineString",
            "Polygon",
            "MultiPolygon",
            "GeometryCollection"
          ],
          "parent": "engine_defaultedProperties"
        },
        "dodiCollections": {
          "values": ["Live", "Archive"],
          "parent": "engine_defaultedProperties"
        },
        "tags": [
          {
            "value": "AlloyConfigEntity",
            "parent": "designInterfaces_workflowManualTrigger"
          }
        ],
        "discriminator": "DesignWebModel"
      },
      "actionId": "6698e0bdd2083fc6d082dffc",
      "actions": [
        {
        // this `actionDesign` contains the standard model of the Message action design
        // its contents are omitted for brevity!
          "actionDesign": { },
          "actionId": "66990365d2083fc6d0831c3c",
          "actions": [],
          "parameters": [
            {
              "attribute": {
                "attributeCode": "attributes_workflowMessageActionMessageType",
                "value": ["5c66bcd44b4d4259071069df"]
              },
              "discriminator": "WorkflowConstantItemAttributeWebModel"
            },
            {
              "attribute": {
                "attributeCode": "attributes_workflowMessageActionMessageText",
                "value": "All these defects are now red"
              },
              "discriminator": "WorkflowConstantItemAttributeWebModel"
            },
            {
              "attribute": {
                "attributeCode": "attributes_workflowMessageActionRecipientName",
                "value": "Toby"
              },
              "discriminator": "WorkflowConstantItemAttributeWebModel"
            },
            {
              "attributeCode": "attributes_workflowMessageActionLinkedItems",
              "virtualDefinition": "$input(0)$itemId$",
              "discriminator": "WorkflowVirtualItemAttributeWebModel"
            },
            {
              "attribute": {
                "attributeCode": "attributes_workflowMessageActionMobileNumber",
                "value": "+447700900077"
              },
              "discriminator": "WorkflowConstantItemAttributeWebModel"
            }
          ],
          "variables": []
        }
      ],
      "parameters": [
        {
          "attribute": {
            "attributeCode": "attributes_myRedManualWFParametersStringParam_66980133ad24446802f061d6",
            "value": "DANGER!"
          },
          "discriminator": "WorkflowConstantItemAttributeWebModel"
        }
      ],
      "variables": []
    }
  ]
}

Here's a summary of their expected behaviour:

  1. My Other Workflow is triggered on items of the Defect interface. They pass to the MWR action.

  2. My Red ManualWF is triggered. The Edit Item action changes each item's colour and overwrites their Description attribute with a parameter value (specified in the MWR action). The edited items pass to the Message action. For each item, an email is sent containing a link to the edited item.

    The final output of the MWR is the Edit Item action.

  3. My Other Workflow continues. The output of the MWR (the edited items) passes to the Message action. A single SMS is sent containing links to all the edited items.