Custom workflow steps

You can extend the list of standard steps in the workflow designer tool by creating custom workflow steps. Custom workflow steps make it easy for workflow designers to drag, drop and configure a step into a workflow to call a SmartObject method.

To create a custom workflow step you must register the custom step by pointing it to a Service Method of a Service Object, and configuring the display values and icon for the custom step. Once the custom step is registered, it will appear in the K2 Workflow Designer and designers can use the custom step against a SmartObject that contains the Service Object method associated with the custom step.

For examples that demonstrate how to create custom workflow steps, see Example: Creating a custom workflow step and Example: Using JSSP and Custom Workflow steps together.

How custom workflow steps work

To understand how custom steps work, you first need to understand how SmartObjects work. For an overview of SmartObjects, see the topic SmartObject terminology and architecture and for an overview of Service Types see the topic Service Types in the User Guide. You should understand how Service Types, Service Objects and Service Object methods are related, and then how Service Instances and SmartObjects are related.

Essentially, when you register the custom step, you will tell K2 which Service Type, Service Object and Service Object method to use for the custom step. When a workflow designer uses your custom step in a workflow, they need to select the Service Instance of the targeted Service Type ("connection") to use when the workflow executes. Under the covers, K2 will find and execute the relevant SmartObject method in the specified Service Instance that matches the Service object method defined for the custom step.

Registering the custom workflow step

Using the custom workflow step in workflow designer

Service Object consistency

Because of the way that custom steps infer the SmartObject to call at runtime (based on the Service Type and Service Object method), custom steps are best suited when Service Instances of the Service Type exposes Service Objects with the same structure. In other words a Service Type with consistent Service Objects, where the Service Objects have the same properties and methods regardless of the service instance they are in, would work well. Something like the standard SQL Server Service Type may not work well, since the Service Objects in this service are different based on the SQL database targeted by different Service Instances of the Service Type. Consider limiting your custom steps to service types where the Service Objects are guaranteed to be consistent across Service Instances.

For Service Types that do not expose consistent Service Objects (for example the REST Endpoint Service or the SQL Server Service) you may want to register a new Service Type that uses the same underlying Service Broker, create a Service Instance of the Service Type, and ensure that the Service Instances of this new Service Type are consistent. This means that each Service Instance of the Service Type will contain the same SmartObjects and methods, which makes using custom steps more predictable.

At runtime, the custom step definition compares the Service Instance information (the connection that the workflow designer selected when configuring the custom step) to the Service Type, Service Object, and Service Object Method that you chose when creating the custom step. It then executes the SmartObject that matches the definition of the custom step, using the following logic:

  1. If there is only one Service Object in the selected connection/Service Instance, use that Service Object even if the name does not match.
  2. If there is more than one Service Object in the selected connection/Service Instance, use the Service Object where the name matches.
  3. If there is more than one item in the collection, but no name matches, you will see a validation error: "A single, matching SmartObject was not found."
  4. If there are no SmartObjects in the selected connection/Service Instance, you will see an error like "a SmartObject was not found".

See Creating custom workflow step for more information about validation that happens when you drag a custom step onto the canvas.

See these topics to learn how to set up custom workflow steps:

Considerations

  • If you create a custom step in K2 Cloud Update 11, then upgrade your K2 environment to K2 Cloud, you must also update your custom step and reselect the Service Type, Service Object and Service Object Method in the dropdowns on the Register Custom Step form shown above.
  • Carefully plan the structure (name and toolbox path) of your custom steps. You cannot change the name or the location of a custom step once you create it. For more information, see Managing custom workflow steps.
  • You must register the custom step in each environment where a workflow will use it. The K2 Package and Deployment tool does not package or deploy custom steps, and workflows containing custom steps will not function without the same custom steps in both environments. If you are deploying a workflow with a custom step to another environment, ensure that the custom step is already registered in the target environment before you deploy the workflow. In other words, if you have a Development K2 environment and a Production K2 environment, you must register the custom step in each environment, with the same configuration values.
  • You must be a member of the Security Administrators role, or both the Package and Deployment and Server Admin roles to create or maintain custom workflow steps.
  • If Service Object names differ between Service Instances, your steps may fail at runtime. Validation messages appear in the configuration panel if the K2 Workflow Designer detects that there may be a problem at runtime. If you do not use the Generate SmartObjects option when creating the Service Instance, there is a chance that the Service Object Method Names you use in the step configuration will not match, and the steps will fail at runtime.
  • If you delete all the custom steps in a toolbox node, the system removes the node as well.
  • Deactivate custom steps if you no longer want designers to use them, but they are still used in deployed workflows. For more information, see Managing custom workflow steps.
  • If K2 cannot locate a SmartObject that references the specified Service Object, you will not be able to specify any mappings in the workflow design tool while configuring the custom step.
  • The system disables the configuration panel if there is no SmartObject/Service Object Method match found.
  • Service Types (along with their Service Objects and SmartObjects) that do not have the same structure may not behave the way you expect. Validation messages appear in the configuration panel if the K2 Workflow Designer detects that there may be a problem at runtime. The following two images are examples of validation errors:

  • If you need to update the Service Type, Service Object, or Method at a later point, you must update the custom step definition. You can also update the description and the icon, but you cannot update the custom step name or location in the toolbox. See the topic Managing custom workflow steps for more information.