Annotations / Custom fields

info

These functions are available in the Workflow Engine ≥ 4.0

Annotations are a set of records, a key (or name) - a value you can add to your Activities and Transitions in the designer. Annotations could be called "Activity and Transitions Custom Parameters" or "Activity and Transitions additional attributes", but we have chosen the term "Annotations", it is unambiguous and does not overlap with other Workflow Engine functions. The most essential information you need to know about annotations is the following:

• Annotations are edited in the designer in Activity and Transitions settings. Double click Activity or Transition to open their properties edit form. There is Annotation section in this form where you can create as many annotation as you want.
• Annotations are part of the scheme, they cannot be changed programmatically on the fly. After a process has been created for this scheme, you can only update the process to a new scheme with new annotations values. In other words, annotations are constant.
• Annotation record consists of Name and Value. Name is a string allowing you to find annotation value. Value is also a string. To save a complex object in the annotation you can add JSON string into Value.

Using annotations from code

It is very easy to read annotation value from code (it can be your Actions Code or any other server code). If you read annotations values from Actions, there is always a reference to the current ProcessInstance. Use the following code to get annotations values as string:

var processScheme = processInstance.ProcessScheme;
string valueFromActivity = processScheme.GetActivityAnnotation("ActivityName", "AnnotationName");
string valueFromTransition = processScheme.GetTransitionAnnotation("TransitionName", "AnnotationName");

If you are using JSON as annotation value, and you've got a type you can deserialize this JSON into, get this type values instantly:

var processScheme = processInstance.ProcessScheme;
YourCustomType valueFromActivity = processScheme.GetActivityAnnotation<YourCustomType>("ActivityName", "AnnotationName");
YourCustomType valueFromTransition = processScheme.GetTransitionAnnotation<YourCustomType>("TransitionName", "AnnotationName");

You can also read annotations values from the objects of the ActivityDefinition and TransitionDefinition type. For example, the following code will read annotations from the executing Activity and Transitions.

var executedActivity = processInstance.ExecutedActivity;
string valueFromActivity = executedActivity.GetAnnotation("AnnotationName");

var executedTransition = processInstance.ExecutedTransition;
string valueFromTransition = executedTransition.GetAnnotation("AnnotationName");

Same for typified annotations:

var executedActivity = processInstance.ExecutedActivity;
YourCustomType valueFromActivity = executedActivity.GetAnnotation<YourCustomType>("AnnotationName");

var executedTransition = processInstance.ExecutedTransition;
YourCustomType valueFromTransition = executedTransition.GetAnnotation<YourCustomType>("AnnotationName");

If you have decided to get annotations values outside actions, you will have to get the object of the ProcessDefinition type first:

var runtime = WorkflowInit.Runtime;
var processSchemeByProcessId = runtime.GetProcessInstanceAndFillProcessParameters(processId);
var processSchemeByCode = runtime.Builder.GetProcessScheme(schemeCode);

After that to get annotations values use methods described above.