Organizing Workflows

Naming

Trees

When creating trees for the platform, the preconfigured webhooks that come with some of our solutions are looking for workflow with particular names:

• Created
• Saved
• Submitted

For example, in a particlar group:
{kapp slug} > {form slug}

And that means that that HAS to be the naming convention for the trees for those solutions. This will probably be similar for any solution you are using or you build. The webhooks will determine the workflow tree naming convention because the webhooks are the connection into the workflow engine and need whatever they are expecting to be there.

Routines

Routines are called by trees and other routines much like handlers so their naming is a little more loose. However, it is a good idea to create and stick with a convention that will be clear and re-usable, for example:

• individual_approvals_v1
• group_approvals_v1
• send_notifications_v1

Handlers

There is a standard naming convention followed by Kinetic when creating handlers. Handlers will work with other names, but using this convention allows us to quickly and easily sort and manage our handlers. It goes like this {system} then {record type} then {action} then {version}. Examples include:

• kinetic_request_ce_attachment_upload_v1: This reaches out to Kinetic Request CE (the platform front end) and uploads an attachment.
• kinetic_task_tree_run_v2: This reaches out to Kinetic Task (the workflow engine for the platform) and runs a tree.
• kinetic_bridgehub_bridge_create_v1: This reaches out to Kinetic Bridgehub and creates a bridge.

Not everything fits neatly into this, but we try to keep it as close as possible.

Versioning

Trees and Routines

It is possible to version trees and routines without changing the initial tree being called unless there are new inputs or outputs needed. There is a full detailed article on this related to this article. Generally the notes for this are to be cautious when updating a tree or routine to a new version because of in flight requests and any potential existing name requirements from web hooks.

Note that any updates that require new inputs or outputs for a routine will cause you to need to replace all the instances of that routine everywhere it exists. This is a good reason to do your best to try and think of all potential inputs when first creating a routine. It is better to have inputs you don't need/use right away than to have to go back and touch everywhere you use your routine later for things you could forsee.

Updating Handlers

There are two ways to update a handler: You can update the code of a handler without touching the version or the node.xml in any way. Or you can update the node.xml to update the version, add input, and/or add outputs. If the node.xml changes, you need to go replace all instances of that handler if you want to be able to leverage that new version. If you leave the old version in the system and just want to use the new version moving forward, you don't have to change anything; but let's be realistic, you likely updated it because of some kind of issue and things need to be changed.

If you just change the code without changing the node.xml, the handler will reload the code when the workflow engine is restarted and all will be fine. This is the reason developers occassionally choose to make changes without updating handler versions. However, if you do this it is critical that you make notes of what was changed, by who, and why in the changelog of the handler. Your handler will no longer match our version and support will be up the creek without notes on what was done.

Organizing Categories

Routines and handlers are placed in categories. They are available under these categories in the builder. Security can be applied to these categories separately, but mostly having good categories helps workflow developers be more efficient.