Example: Creating a custom workflow step

This example demonstrates creating and using a custom step in a workflow. In this example you create a custom step to add comments to the current workflow instance as a step in the workflow.

In this example, we will be using the Workflow Comment System Service Object, and specifically the Add Comment method. This SmartObject is associated with the Workflow Service Service Type, one of the standard service types available in K2 environments.

While we are using a standard Service Type for this example, you can follow the same procedure to expose custom Service Object Methods as Custom Steps.

Follow the steps below to create a sample Custom Step

  1. Create or identify the Service Type, Service Instance, Service Object Method that you want to use for your Custom Step. If necessary, create a SmartObject for the Service Object. In this example we will use the existing Service Object for Workflow Comments, and generate a new SmartObject for it.
    Service Type: Workflow Service
    Service Object: Workflow Comment
    Service Object Method: Add Comment
    SmartObject: Workflow Comment (generated through the K2 Management site)
    1. Open the K2 Management Site
    2. Browse to Integration > Service Instances
    3. Use the Service Type column to find an instance of the service type you will create a SmartObject for. In this case, we will use the Workflow Service Service Instance of the Workflow Service Service Type:

    4. Use the Generate SmartObject button to generate a new SmartObject for the Workflow Comment Service Object. (You could also manually create a SmartObject using K2 Designer. If you use this approach, ensure that the name of the SmartObject you use is consistent for the environments where the custom step will be used by workflows)

  2. Use the Custom Step Administration form to register the new custom Step. The form is located at
    https://[servername]/Runtime/Runtime/Form/com__K2__System__Management__Workflows__CustomStep__Forms__Main
    Replace the [servername] placeholder with the name of your K2 environment)
    1. Using a web browser, open the Custom Steps administration form located at
      https://[servername]/Runtime/Runtime/Form/com__K2__System__Management__Workflows__CustomStep__Forms__Main
      Replace the [servername] placeholder with the name of your K2 environment). You must be a member of the Package and Deployment Role to use this form to register new custom steps.
    2. Once the form loads, open the Create tab

    3. Specify/select values for your new custom step. In this example:
      FieldDescription
      NameAdd Comment
      Toolbox PathDocumentation Examples
      Service TypeWorkflow Service (SourceCode.SmartObjects/Services.Workflow.WorkflowService)
      Service ObjectWorkflow Comment (WorkflowComment)
      Service Object MethodAdd Comment (AddComment)
      DescriptionAdd a comment to the workflow instance
      IconUpload a 32x32 .svg file. Sample:


    4. Click Create to register your new custom step
  3. Create a new workflow, drag the Add Comment custom step into the workflow design and configure the step with the current Workflow ID as the input for Process Instance ID, and a value of your choice for the comment.
    1. Launch K2 Designer and create a new workflow. Our example workflow is called Test Custom Steps but you can call your workflow anything you like.
    2. When the workflow designer loads, locate your new custom step in the toolbox. In this example, you can find the custom step in the Documentation Examples group.
    3. Drag and drop the custom step into the workflow.
    4. Expand the configuration panel for the step. Drag and drop the Workflow ID property from the context browser into the Process Instance ID field, and type some value for the Comment field. (In this case we also included the Now function from the Functions tab, but you can enter any value you like)

    5. Add additional steps to your workflow, if desired.
    6. Deploy your workflow
  4. Set up your environment for additional rights and permissions. In this example, give the K2 Service Account View rights to the workflow.
    1. Remember that workflow steps execute in the context of the K2 Service Account. To add comments to the workflow instance, the K2 Service Account requires View permission on the workflow. Launch K2 Management and navigate to the workflow you just deployed. In this example, the workflow is located at Workflow Server > Workflows > CustomSteps > Test Custom Steps
    2. Using the RIGHTS tab, give the K2 Service Account VIEW rights to the workflow.


  5. Test your custom step by starting a new instance of the workflow. Execute the GetList method of the Workflow Comments SmartObject to verify that a comment was added.
    1. In K2 Management site, use the Start New button in the INSTANCES Tab to start a new instance of the workflow. Use any value for the Folio and click Start. Make a note of the ID of the workflow.

    2. Navigate to the Workflow Comments SmartObject, located in Workflow Service > Workflow Service > Workflow Comment and Execute the Get List method. Enter the value of the Process Instance ID that you made a note of the previous step.
    3. You should see a comment entered by the K2 Service account for the workflow instance. This concludes the test.

Review

In this how-to, you created a custom workflow step to make it easier for workflow designers to call a SmartObject method when they are building a workflow. In this example, we created a custom step to add comments to a workflow instance as the workflow progresses.