Completion handlers and workflow wrappers

Completion handlers

Completion handlers are workflows that execute after another workflow has been completed. They provide a mechanism to extend or modify existing workflows without altering their core structure. These workflows have a context variable that can be used to reference previous contexts from the workflow that was completed. Configure completion handlers to either trigger another workflow after the existing one finishes, or execute the current workflow when another workflow is completed.

You might hear some of our support staff or customers who present on our Open Mics refer to completion handlers as workflow listeners. Listener is a more coding-focused term that they're already familiar with. A completion handler and workflow listener are the same thing.

Example workflow use cases for completion handlers

Let's look at a few use cases for using completion handlers:

• Taking additional steps after the onboarding workflow is complete

  • Add additional functionality to an existing synced workflow without having to unsync it from the template.

• Alerting for failed workflow executions, like kicking off the completion handler based on a failed status

Configure a completion handler in a workflow

1. Navigate to Automations > Workflows.

2. Locate the existing workflow that you want to address. Click Workflow Completion Handlers.

3. Note the two options in the Completion Handlers section. You'll need to choose which one you want to use:

   1. Run this workflow when...

      1. This will run the workflow when another workflow completes

   2. When this workflow completes...

      1. This will result in something being done when the workflow completes

4. Define your trigger conditions. This step will differ depending on which of the two options you chose in step 3.

   1. For When this workflow completes...

      1. Click to choose the workflow to trigger.

      2. Under Trigger On Statuses, specify the conditions for the trigger, such as succeeded, failed, timed out, or canceled. You can select multiple statuses from the drop-down list.

   2. For Run this workflow when...

      1. Click to choose the workflow to trigger.

      2. Under Trigger On Statuses, specify the conditions for the trigger, such as succeeded, failed, timed out, or canceled. You can select multiple statuses from the drop-down list.

      3. Select your relevant integration or integrations from the drop-down selector.

      4. Open each selected integration's accordion menu to choose your Configuration Selection Mode for that integration.

5. Make sure Enabled is toggled to on.

6. Click Submit to save your settings.

An example Add Completion Handler dialog for the When this workflow completes... option

An example Add Completion Handler dialog for the Run this workflow when... option

Access the context of the previous workflow

Contexts from the previously run workflow can be accessed with the COMPLETED_WORKFLOW variable. You can access most info via the context including ORG and CTX such as:

1. {{ COMPLETED_WORKFLOW.ORG.VARIABLES.cw_manage_company_id }}

2. {{ COMPLETED_WORKFLOW.CTX.user.username }}

Completion handlers will always run in the context of the parent organization. If you are taking actions on a suborganization in the workflow, then you must utilize the run-as-organization functionality and overrides set at the completion handler level.

The organization ID that was used in the previous workflow context can be referenced with the following Jinja:

{{ COMPLETED_WORKFLOW.ORG.ATTRIBUTES.id }}

Test completion handlers

Completion data is hard to fake for testing because it's represented as COMPLETED_WORKFLOW. instead of CTX.COMPLETED_WORKFLOW. Rather than running an entire workflow multiple times to test just this one element, create a noop action that sets the test data, and use it to trigger your completion handler.

In the noop, set all of the variables that will be used in your completion handler in the On Success transition as data aliases.

It’s important that the names of the data aliases you create in the On Success transition of the noop match both:

• the names of the variables that will be used in your completion handler

• the names of the variables that will be used in the live parent workflow that your completion handler is triggered by

Add static values that represent a good test case for ensuring that your completion handler functions the way you expect.

Example

In the example below, we’ve created a workflow with a single noop. In the On Success transition, we’ve added several data aliases that represent user data that could be used to test a completion handler, which could be used after a user is onboarded or offboarded.

The noop action, its On Success transition, and the corresponding data aliases

Once you’ve created the noop and added the correct data, attach this workflow to your workflow completion handler as another parent workflow that will trigger the completion handler. This will enable testing.

The location of the button

Click + to attach the workflow to the workflow completion handler

Click Test to run the workflow. This will feed the variables that you’ve set with your completion handler and trigger it to run, allowing you to confirm if the variables are used as expected. If you need to run your test workflow for organizations other than your parent MSP organization, add a trigger to the workflow which will allow you to select which organization the test workflow runs for.

Alternatively, re-run from the workflow result page of the workflow that kicks off the completion handler. This would still run the workflow in total, but would be a simpler way to achieve it with fewer clicks.

Workflow wrappers

Workflow wrapper is an informal term used colloquially by the ROC to describe a situation where a primary workflow is used in a separate workflow as a subworkflow. Whereas a completion handler only runs when a workflow completes, a workflow wrapper can run before or after completion.

Example workflow use cases for workflow wrappers

Let's look at a few use cases for using workflow wrappers:

• Handle pre and post-onboarding tasks

• Run a Crated workflow against a group of items, in a way it was not originally designed to do