Start a workflow with the Start when any workflow errors event

You can start a workflow when another workflow encounters an error by configuring a Start when any Workflow Errors start event. This event can start a new workflow instance when a workflow in your K2 environment goes into an error state. Typically, you would start a workflow to handle errors, or to notify someone about the errors so that they can address or repair the errors.

There are many reasons why a workflow might go into an error state. An easy way to simulate an erring workflow is to send an email to an invalid email address on the Send Email step, for example: bob2denallix.com instead of bob@denallix.com. The workflow runs, fails on the Send Email step, and goes into an error state. To see the erring workflow and error message, browse to K2 Management > Workflow Server > Workflows > [workflow name] > Process Details > Errors tab.

Instead of manually checking error logs, use the Start when any Workflow Errors event to start an error handling workflow to notify someone with an action task or an email. When you configure the Start when any Workflow Errors event, workflow properties from the erring workflow populate as variables in the error handling workflow. These include properties such as Workflow Name, Workflow ID, Folio, Error Message, and more. You can use these variables to populate the body of an email notification, or add details to the instruction section of a task with information from the erring workflow. You can also use the variables in SmartObject calls.

Keep in mind that if you use the Start when any Workflow Errors event, any workflow going into error state will start a new instance of the error handling workflow, and it becomes like a global "catch all" workflow. The global "catch all" workflow approach works in environments with few workflows in error state, and if you keep a simple configuration to the error handling workflow. When your error handling workflow contains multiple steps, such as user and server tasks, you can run into a scenario where potentially thousands of items flood your K2 worklist and email inbox. You could also run into a multiple error state loop. It is recommended to have a simple global "catch all" error handling workflow that sends an email when any workflow goes into an error state. For more specific error handling, use a Conditional Start Rule to start the error handling workflow only if the erring workflow matches certain criteria. For an example on configuring a Conditional Start Rule on the Start when any Workflow Errors event, see the Example of an error handling workflow configured with a Conditional Start Rule section in this topic.

Example of a configured Start when any Workflow Errors event

See the following resources for more information:

  • See the to How to: Use the Workflow Error Event for an example of using the Workflow Error Event.
  1. Create or Edit a new workflow (this will be the error handling workflow that starts when a workflow goes into error state).
  2. Select the Start step and click the expand / collapse toggle to expand the Configuration Panel. You can also double click the step to expand the panel.

    For an example on configuring a Conditional Start Rule on the Start when any Workflow Errors event, see the Example of an error handling workflow configured with a Conditional Start Rule section in this topic.
  3. Select the Start when any Workflow Errors option.

    4. You can only add one Start when any Workflow Errors event to the Start step.

  4. The When any Workflow Errors page shows. From here you add workflow property mappings to capture information from the erring workflow (in error state), into variables to use in the workflow.

    The following table explains the available options:

    5. Option Explanation How to Use
    Create Variables For Me

    Select this option to auto create and map all available erring workflow properties to corresponding variables.

    The available workflow properties are Workflow ID, Workflow Name, Workflow Path, Start Date, Originator, Priority, Folio, Error Message and Error Date.

    For more information on these properties, see the Workflow topic.

    Click the Create Variables For Me button.
    I'll do it myself

    Select this option to manually add variables and map them to the erring workflow properties.

    The available workflow properties are Workflow ID, Workflow Name, Workflow Path, Start Date, Originator, Priority, Folio, Error Message and Error Date.

    For more information on these properties, see the Workflow topic.

    Click the I'll do it myself link.

    Click the Add icon to add variables. Use the menu to select and map the workflow. For this option, you need to create variables first, before you configure the event. If the variables you create are not of the correct type, the error handling workflow may not start.
  5. Select one of the following options:

    6. To create and map all available erring workflow properties to corresponding variables, select Create Variables For Me. Notice the added and mapped workflow properties. On the left are the created variables, and o n the right are the workflow properties from the erring workflow.

    To remove a workflow property and its mapped variable, select it and click the Trash Bin. To add it back again, click the Add icon and map it to the corresponding variable.

    To clear all mappings, click the Clear Mappings link. This takes you back to the When any Workflow Errors page.

    This will just clear the mappings between properties and variables and will not remove the variables that were created.


    Click the Add button to conclude the configuration of the Start when any Workflow Errors event.

    When you select this option, you need to add variables to the workflow Context Browser first and then map them to the workflow properties of the erring workflow. To do this, click the expand / collapse toggle to expand the Context Browser and select Fields. Click the Add link in the Variables section.

    When adding variables, make sure to select the same data type for the variable as the workflow property. For example select the Date/Time data type for date related workflow properties. You can add variables for all the corresponding workflow properties, or just the ones you want.

    Field Type
    Workflow ID

    Number
    Error Date and Start Date Date/Time
    Rest of them Text

    For more information on how to create variables, see the Variables section in the Fields topic.

    To manually add workflow properties and map them to the manually added variables, click the I'll do it myself link.

    Click the Add icon and select variables from the menu. The variables show on the left.

    The workflow properties from the erring workflow show on the right. Use the menu to map the workflow properties to the corresponding variable.

    Click the Add button to confirm added workflow properties and mappings.

    To clear all mappings, click the Clear Mappings link. This takes you back to the When any Workflow Errors page.

    This will just clear the mappings between properties and variables and will not remove the variables that were created.


    The K2 Service Account needs Start rights on the error handling workflow. After you deploy the error handling workflow, you must manually assign the service account Start rights on the workflow rights screen in K2 Management. The K2 Service Account will show the KUID as the account name.
  6. The Start when any Workflow Errors event has been configured.
  7. To view the variables, click the expand / collapse toggle to expand the Context Browser. Select the Fields.
  8. When you delete one of the variables, a red indicator shows on the configured Start when any Workflow Errors event and the Start step.
  9. A red indicator shows the missing variable on the When any Workflows Errors page.
  10. To clear the red indicator, add the variable to the Context Browser > Fields > Variable section. Then edit the Start when any Workflow Errors event configuration and select the variable from the menu.
  11. To edit the configuration, click the Edit link.
  12. To delete the configuration, select it and click the Trash bin.
  13. Click Delete Event.

Deleting the Start when any Workflow Errors event does not remove the added variables. If you do not need them after the delete, remove them manually.

Deleting the Start when any Workflow Errors event will only be removed wen you deploy the workflow. If you had a workflow that was deployed with a configured event and you delete the event without deploying the workflow again, an instance of this workflow will still be started when any workflow goes into error state. To fully remove the event subscription and make sure that no new instances are kicked off, delete the event and redeploy the workflow.

Suppose that your organization manages claim processing with a workflow. You recently discovered that not all claims processing workflows are completing as expected. After investigating the issues with the Errors page in the K2 Management Site, you notice some of the workflow instances are in an error state. Instead of relying on someone to periodically check the claims processing workflow for errors, you want to start a specific error handling workflow whenever an instance of the Claims workflow goes into Error state.

In this example, you create an error handling workflow called Claim Error Handling. You want this workflow to start only when an instance of the Claims workflow goes into an error state. To do this, you need to configure the Conditional Start Rule on the Start step. The workflow only starts if the condition set in the rule is met. In this case, the workflow starts if the Workflow Name variable equals the word Claims.

  1. Create a workflow called Claim Error Handling. For information on how to create a workflow, see How To: Create a Workflow.
  2. Select the Start step and click the expand / collapse toggle to expand the Configuration Panel. You can also double click the step to expand the panel. Select the Start when any Workflow Errors option.
  3. From the When any Workflow Errors page click Create Variables for me.
  4. Click Add to confirm the workflow properties, variables, and mappings.
  5. The setup and configuration are complete.
  6. To configure the condition for the start rule, select Conditionally Start and click Edit Start Rule.
  7. The Start Rule shows in the Rules Designer. In this example, you need to specify that if a workflow (equals to the word Claims in the Workflow Name field) goes into an error state, the workflow should start. To do this you use the Workflow Name variable. From the Context Browser locate the Workflow Name variable and drag it into the condition.
  8. Leave the operator as Equals. Type Claims as the value.
  9. For the THEN option select Start. For the ELSE option select Don't Start.
  10. Configure the rest of the workflow by adding a Send Email step. This sends an email to notify the recipients of the erring workflow. Use the variables to customize the subject and body of the email with information from the erring workflow as shown below.
  11. Complete the workflow configuration with an End step, and then Deploy the workflow.
  12. At runtime, when the Claims workflow goes into an error state, the Conditional Start Rule on the Claim Error Handling workflow evaluates the name of the workflow. If the name equals the word Claims the error handling workflow starts and sends an email. If the workflow name does not equal Claims, the workflow does not start.
    Claims workflow in error state

    Example of the email sent from the Claim Error Handling workflow

This section contains answers to common "What happens if I..." and other error handling workflow related questions.

Question Explanation

What happens if...

  1. I have a new workflow, not yet deployed
  2. I configure (delete) the Start when any Workflow Errors event
  3. I deploy it

Changes made to the error handling workflow automatically get saved. When you close the workflow designer, the changes (in this case deleting the Start when any Workflow Errors event) no longer show on the Start step. When you open the error handling workflow again, the configured Start when any Workflow Errors event will not show on the Start step. It will show as an option in the start event menu.

Because you did not deploy the error handling workflow when the event was configured, none of the initial Start when any Workflow Errors event configurations or deleting it published to the K2 server. This means the error handling workflow will not start when another workflow goes into an error state.

What happens if...

  1. I have a new workflow, not yet deployed
  2. I configure the Start when any Workflow Errors event
  3. I deploy it
  4. I delete the configured Start when any Workflow Errors event
  5. I redeploy it

When you deploy the error handing workflow, the Start when any Workflow Errors event configuration is published to the K2 server. This means the error handling workflow starts when any workflow goes into an error state.

When you edit the error handling workflow, delete the Start when any Workflow Errors event configuration, and redeploy the workflow, the changes are published to the K2 server. This means the Start when any Workflow Errors event is not configured on the latest deployed version of the error handling workflow. So, the error handling workflow will not start when another workflow goes into an error state.

Deleting the Start when any Workflow Errors event does not remove the added variables. If you do not need them after the delete, remove them manually.
What happens if I change something about the Start when any Workflow Errors event (such as changing the mappings)? Do I have to deploy the error handling workflow for those changes to take effect?

Changes made to the error handling workflow are automatically saved. When you close the workflow designer, the changes (in this case changing mappings) show in the Start when any Workflow Errors event configuration on the Start step.

However, to commit these changes to the K2 server you must redeploy the error handling workflow. If you do not redeploy, the older version of the deployed error handling workflow is used when new instances of erring workflows occur.

What happens if I have more than one error handling workflow that starts when any workflow goes into an error state?

Example: There are two error handling workflows called Global Error Handling and Admin Error Handling. Both error handling workflows are configured with the Start when any Workflow Errors event and deployed. You did not configure a Conditional Start Rule on either of them. Does this mean both Global and Admin Error Handling workflows starts whenever any workflow goes into an error state?

Yes. In this example both the Global and Admin Error Handling workflows start whenever any workflow goes into an error state.

This scenario shows the importance of configuring a Conditional Start Rule on your error handling workflow to only start when a specific condition from the erring workflow is met.

For an example on configuring a Conditional Start Rule on the Start when any Workflow Errors event, see the Example of an error handling workflow configured with a Conditional Start Rule section in this topic.
What happens if I create a copy (save as) of the deployed error handling workflow and then deploy the copied version of the error handling workflow? Will there be two error handling workflows that both start when any workflow goes into an error state? Creating copies of workflows is not recommended. Do not try to copy or rename error handling workflows. While this is possible, you should avoid doing this especially if you have already deployed the workflow that handles the Start when any Workflow Errors event. It is recommended that you create and configure a new error handling workflow from scratch.

 

To see what happens when you create a copy of a workflow see, KB002953: Saving, copying and renaming workflows.
How do I completely delete an error handling workflow so that it no longer starts when any workflow goes into an error state? In other words, how do I get rid of the error handling workflow?

There are two ways to delete an error handling workflow:

  • Edit and delete the Start when any Workflow Errors event configuration form the error handling workflow. Redeploy it. With this option, the error handling workflow remains on your K2 server but will not start when any workflow goes into an error state.
  • Delete the deployed error handling workflow. For information on how to delete a deployed workflow , see the How to delete a deployed workflow section in the Delete a workflow topic.

When working with the Start when any Workflow Errors event on the Start step, keep in mind the following considerations:

  • You can only add one Start when any Workflow Errors event to the Start step.
  • The workflow you configure to start when an error event occurs may need additional information about the erring workflow. You need to configure a Conditional Start Rule or some other custom logic based on the specific erring workflow.
  • Remember to keep your error handling workflows to a minimum. If you want to have a specific workflow start for a specific workflow that errors, modify your error handling workflow with a Conditional Start Rule so it only starts when that particular workflow goes into an error state. For an example on configuring a Conditional Start Rule on the Start when any Workflow Errors event, see the Example of an error handling workflow configured with a Conditional Start Rule section in this topic. For related information see, KB002953: Saving, copying and renaming workflows.
  • If you need error handlers for specific workflows, you'll need to setup one global "catch all" error handling workflow that does something simple like send an email, then setup the other specific workflows to conditionally start based on the workflow path and name.
  • Do not try to copy or rename error handling workflows. While this is possible, you should avoid doing this especially if you have already deployed the workflow that handles the Start when any Workflow Errors event. It is recommended that you create and configure a new error handling workflow from scratch.
  • Events occur in an asynchronous manner, which means that when the event occurs, actions will not immediately be taken. In most cases, the action occurs within 5 minutes, but this depends on the load and your environment.
  • Use the Create Variables for me button instead of the I'll do it myself (doing your own mappings) option. If you do your own mappings, make sure that the data type from the event matches the data type of your variable, or else the error handling workflow will not behave as expected.
  • The K2 Service Account needs Start rights on the error handling workflow. After you deploy the error handling workflow, you must manually assign the service account Start rights on the workflow rights screen in K2 Management.
  • To automatically attempt the retry of an error, use the ErrorLogs system SmartObject located at System > Management > Workflows > SmartObjects. Get a list of errors and filter it by Folio, creating a reference of the resulting error object. Then use the RetryError method of the same SmartObject, passing in the necessary information from the reference. For more information, see the Errors topic. You may need to add some processing to address the source of the error before retrying the workflow. Note that IPC errors (Type ID 20) should typically not be retried.
  • It is possible that some error events are not raised. This can happen:
      • On server start up before the service is able to process events.
      • If you have mismatched data types between your variables in your error handling workflow and the event object data.
      • If there was a problem when creating the transformation of the error event to the action.
  • K2 Package & Deployment does not create the error event subscription when you deploy the error handling workflow. You can deploy error handling workflows using K2 Package and Deployment, but you must open the error handling workflow with K2 Designer and deploy it from K2 Designer to create the error event subscription.

  • The number of instances of a workflow that can occur in a minute is set to 10 by default to prevent the infinite looping scenario. This value can be configured in Management>Workflows>Settings>Instance Threshold Policies>Workflow Instances.