Migration to Workflows

The business requirements for the dunning process are often complex and must adhere to strict legal standards. Therefore, processes need to be precisely defined to meet all these requirements.

Our objective is to simplify these process definitions while providing maximum flexibility and value. To achieve this we have developed the Workflow Builder, an intuitive user interface for process definitions inside of the collect.AI management portal. It comes together with a new approach called Workflows, which extends the feature set and replaces the existing Scenarios functionality.

Compared to scenarios, workflows offer a more efficient, flexible, and safer way to manage process structure and content with better process overview, enabling easier modifications and coordinated change deployments with version publishing.

This post outlines the main technical differences between workflows and scenarios as well as the necessary steps to adapt your integration with the workflow-related changes in the collect.AI system.

Your collect.AI Technical Project Manager will contact you to define the migration scope, align timeline, and assist with the migration.

Workflow and Scenario Differences

Workflows aim to streamline process definition and provide you with with greater control, enabling you to easily define processes directly within the collect.AI management portal via the Workflow Builder.

Aside from the significantly improved user experience, scenarios and workflows differ in several key areas:

• Versioning and version life cycle management
• Applying changes to active processes
• Content management approach
• Use of API endpoints

Let's have an overview of all these topics and then focus on the API changes.

Workflows and Workflow Versioning

Workflows introduce comprehensive versioning for both the workflow structure and individual actions, unlike scenarios which lacked versioning entirely.

Workflow definition in the Workflow Builder begins with an initial draft that can be modified as needed. Drafts cannot be used for claim assignment and must be published first. Publishing finalizes the changes and creates the first published version of the workflow.

A workflow version follows a defined lifecycle: it always starts as a draft and needs to be published before it can be used for claim assignment. Published versions are immutable. When changes of an already published workflow are needed, a new draft can be created from the latest version. Once published, this draft becomes the new current workflow version used for claim assignment. Of course, drafts can be discarded instead, too.

It is important to note that the assignment API, as well as assignment rules are only using workflow identifiers, and assign to the current (latest published) workflow versions only.

Individual workflows can be temporarily deactivated, causing assignment rules that reference them to be skipped.

Both workflows and scenarios have unique names. Workflows and their versions are identified by UUIDs, whereas scenarios use integer identifiers, and are not versioned. Additionally, workflows have user-friendly version names composed of major and minor sequential version numbers. E.g. v1.0, v1.1, v2.0, and so on.

With versioning, updates to specific actions within a workflow are applied to active claims running on earlier minor versions. However, changes to the workflow structure or settings only affect newly assigned claims and result in the creation of a new major version. Combined changes also result in a new major version.

For example, changes to customer message content or fees in v2.1 will be applied to claims running with workflow version v2.0 (the process definition will be "upgraded"), as well as changes from v2.2 to v2.1, and so on. However, changes in the major version v3.0 will not be applied to claims running with the latest v2.x version.

In other words, the major-minor version naming indicates how changes are applied: active claim processes are automatically upgraded to the latest minor version within the same major version when it is published. New major versions, however, only apply to newly created claims. We plan to relax this limitation as we enhance the workflow functionality.

Content Management Changes

The introduction of workflows brings major improvements to content management over scenarios.

Content composition is now more streamlined, simplifying changes:

• Reusable templates (e.g. "Standard Letter") serve as the basis for creating individual messages.
• Within these templates editable parts are defined, which can then be filled out with the actual content for a process step inside of the Workflow Builder (e.g. "First reminder").
• Additionally reusable content snippets can be defined (e.g. "merchant contact details" or "payment button"). These snippets can then be embedded into the different templates.

We will delve deeper into the new three-tiered communication content management approach in a separate post.

Effects of Migration

Content Migration

Legacy message content inherited from scenarios will remain unchanged and read-only. If content needs to be modified, it is required to replace the communication steps with legacy content from scenarios individually by creating new steps using the new content management approach.

Your Technical Project Manager will help with the content migration.

Newly created workflows will of course, use the new content management approach.

Migration of Existing Scenarios

During the migration, workflows are automatically created as copies of the existing scenarios.

The migrated workflows will retain the same names as the original scenarios. The identifiers will change, as mentioned in the "Workflow and Workflow Versioning" section and demonstrated in the "API Examples" section below.

Migration of Existing Assignment Rules

Assignment rules control automatic claim assignment to defined processes, and are applied when a claim is created or when the "start assignment" API endpoint is called.

Assignment rules will be updated to point to the new workflows instead of the original scenarios as part of the migration procedure.

On an unrelated note, this migration might be a good opportunity to switch from direct API assignment to automatic assignment rules.

API Changes

From an API perspective, the changes are limited to the assignment-related endpoints.

The API endpoints have been modified to be forward- and backward-compatible whenever possible. For example, the "start assignment" response format now makes the scenario identifier optional. And even after the migration, assignments to scenarios will still work and scenarios will be automatically substituted with the corresponding migrated workflows.

Here is the list of API endpoints relevant for the migration:

Endpoint	Subject for future deprecation	API behavior before migration	API behavior after migration
Start assignment		response: scenarioId made optional, added optional workflowId to make it forward-compatible.	response: scenarioId becomes undefined, workflowId becomes defined, unless claim remains unassigned
Assign claims to a scenario	Yes	response: scenarioId made optional, added optional workflowId to make it forward-compatible.	response: scenarioId becomes undefined if claim is assigned to a workflow, and workflowId is set instead.
Get Scenarios	Yes	No changes.	No changes.
Assign claims to a workflow		Error until merchant is migrated to workflows.	Specified behavior.
Get workflow list		Actually, migrated workflows are already available, but without any guarantees.	Specified behavior.

We recommend switching to the workflow-specific endpoints ("get scenarios" to "get workflow list" and "assign to scenario" to "assign to workflow") as soon as possible after the migration, or during the migration itself.

Please note, the scenario specific endpoints will eventually be deprecated, the exact timeline will be communicated in an upcoming newsletter.

Migration Path

Migration requires adjustments on both sides:

• Merchants must switch from scenarios to workflows in the collect.AI system.
• API consumption must be updated on the client side.

Of course, the latter only needs to be done in the case of direct API integration. And the rest of the section describes that case.

Your collect.AI Technical Project Manager will contact you to coordinate the switch time, migration details and assist with content migration.

On the client side, some changes might need to be made before the merchant switch. Depending on how strictly API responses are parsed, the previously mandatory scenarioId attribute in assignment call responses may need to be made optional in advance to avoid errors.

After the switch, old API endpoints will continue to function in a backward-compatible mode:

• The scenario list can still be requested if it is part of the client's business logic.
• Any attempts to assign to a scenario after the switch will be redirected to the corresponding migrated workflow.

Migration to the new API endpoints on the client side should happen after the merchant switch. It does not have to happen immediately, but we recommend doing it as soon as possible.

To fully switch from scenarios to workflows and prepare for the eventual deprecation of scenario-specific endpoints, you must use the workflow-specific endpoints listed in the corresponding API documentation section.

In summary, the migration stages are as follows:

1. collect.AI prepares the merchant switch to workflows.
2. collect.AI Technical Project Manager contacts you.
3. API client is adjusted (if needed) to treat scenarioId as optional in assignment call responses. This also could be done upfront.
4. collect.AI switches the merchant from scenarios to workflows.
5. API client switches to the new workflow-specific API endpoints.

As mentioned above, points 3 and 5 are only relevant for direct API integration. They do not need to be addressed for ETL integration.

API Examples

Now let's compare the behavior of existing and new endpoints before and after the migration.

List Workflows

Getting workflows: GET https://demo.collect.ai/merchants/3/workflows-meta:

{
  "error": null,
  "result": [
    {
      "id": "a9605d3d-ce73-3002-9def-2ca3ffba0cb5",
      "name": "assignment examples",
      "version": "a9605d3d-ce73-3002-9def-2ca3ffba0cb5",
      "assignmentEnabled": true,
      "createdAt": "2024-10-23T14:08:25.301Z",
    }
  ]
}

After the migration, this is the expected behavior.

This actually, works even before the migration, but with a significant caveat: we provide no guarantees in that mode. Additionally, when scenarios get changed, workflows are not guaranteed to be immediately in sync.

List Scenarios

Getting list of scenarios: GET https://demo.collect.ai/merchants/3/scenarios

{
  "result": [
    {
      "id": 826,
      "name": "assignment examples",
      "description": "assignment API examples",
      "merchantId": 3,
      "isDefault": true,
      "isActive": true,
      "languages": [
      ],
      "calendars": [
      ],
      "actionSteps": [
      ]
    }
  ],
  "error": null
}

The scenario list endpoint will continue to function after the migration. However, it will eventually be retired.

Note: the response shown is not the complete response body; it has been simplified for clarity.

Assign Claims

Before Migration

Assign claims to a scenario: POST https://demo.collect.ai/merchants/3/scenarios/826/assignments

{
  "result": [
    {
      "claimId": 209279,
      "scenarioId": 826
    }
  ],
  "error": null
}

The endpoint behavior did not change before the migration.

Assign claims to a workflow: POST https://demo.collect.ai/merchants/3/assignments/workflows/a9605d3d-ce73-3002-9def-2ca3ffba0cb5

{
  "result": null,
  "error": {
    "type": "WorkflowAssignmentError",
    "message": "Some claims aren't assigned correctly",
    "details": {
      "errors": [
        {
          "claimId": 214110,
          "message": "Unexpected assignment error"
        }
      ]
    }
  }
}

Indeed, this is not expected to work before the migration to workflows.

After Migration

Assign claims to a scenario: POST https://demo.collect.ai/merchants/3/scenarios/826/assignments

{
  "result": [
    {
      "claimId": 247349,
      "workflowId": "a9605d3d-ce73-3002-9def-2ca3ffba0cb5"
    }
  ],
  "error": null
}

As you can see, after the migration, the claim has been assigned to the migrated workflow instead of the specified scenario.

Assign claims to a workflow via new workflow-specific endpoint: POST https://demo.collect.ai/merchants/3/assignments/workflows/a9605d3d-ce73-3002-9def-2ca3ffba0cb5

{
  "result": [
    {
      "claimId": 258850,
      "workflowId": "a9605d3d-ce73-3002-9def-2ca3ffba0cb5"
    }
  ],
  "error": null
}

There are no surprises - after the migration, this endpoint works as expected.

Start Assignment

The "Start assignment" endpoint assigns claims based on the assignment rules configured in the management portal. You can access them under the "Process Management" > "Assignments" menu. The simplest assignment rules consist of a default rule that assigns all claims to a selected scenario or workflow, depending on the merchant's migration status.

Before Migration

Start assignment: POST https://demo.collect.ai/merchants/3/assignments/claim/214110

{
  "error": null,
  "result": {
    "claimId": 214110,
    "scenarioId": 826
  }
}

The claim is successfully assigned to a scenario before the migration, there is no change in behavior.

After Migration

Start assignment (via the same endpoint as before): POST https://demo.collect.ai/merchants/3/assignments/claim/267191

{
  "error": null,
  "result": {
    "claimId": 267191,
    "workflowId": "a9605d3d-ce73-3002-9def-2ca3ffba0cb5"
  }
}

The claim is assigned to a workflow, which is the expected behavior after the migration.

Conclusion

The migration to workflows will affect assignment rules, content management, and API endpoints. While existing endpoints will continue to function for a period, some will eventually be retired. Therefore, it is crucial to transition to the new workflow-specific endpoints to fully leverage the enhanced capabilities.

By understanding these changes and their implications, you can ensure a smooth transition and take full advantage of the improved process management that workflows offer.

As always, we would greatly appreciate your feedback! Just reach out to your Technical Project Manager for any questions or suggestions.