Java Command Annotations – @workflowDocu
Java command annotations are used for the developing Java commands in PAK.
This chapter describes the functionality of the @workflowDocu annotation.
It also gives an example of how you can use this annotation in your implementation.
1. Basics
@workflowDocu refers to documentation tags and thus, it differs from the other command annotations. Please keep in mind that @workflowDocu is only usable inside the JavaDoc blocks of command classes, i.e.
before @JavaCommand and command variables, i.e. before @Persistent.
It allows the user to understand the syntax of
these commands/parameters in order to use them correctly. The text written after @workflowDocu is stored in the command map as docu and is displayed to users of the command as additional information.
You should add a short but precise description to the command class and the individual command variables.
This will help the user to understand the usage and functionality more easily.
1.1. Requirements
Since @workflowDocu is a documentation, there are no dependencies to define. It is only necessary to extend the build.gradle file of the project with a javadoc that allows the @workflowDocu annotation in all classes.
javadoc {
source = sourceSets.main.allJava
options.tags = [
'workflowDocu:cm:Workflow Developer Documentation:'
]
}2. Usage
The following three chapters describe the usage of @workflowDocu for in- and output variables as well as on command-level.
2.1. @workflowDocu for input parameters
For input parameters, the block should contain sufficient information about what the command/parameter does.
In addition, it may contain the following elements:
/**
* @workflowDocu The authentication type used to authenticate
*/
@Group(GROUP_NAME)
@AllowedValues(values = "REST_BASIC") (1)
@Persistent(mandatory = false) (2)
private String authType;
-
Syntax information: Concrete specifications for the input which can be defined in annotations like
@Persistentor@AllowedValues1 @AllowedValues: Marks a field to only allow specific values. This annotation only works when used together with the @Persistentannotation. The field must be of type String or Enum.2 @Persistent: When setting @Persistentto mandatory false, the documentation block should be prefixed with „(Optional) „. It should also contain information about the default value that will be used if the user does not provide any input.
/**
*
* @workflowDocu The name of the job that should be started. Build job with this
* name should exist. If job does not exist, a
* {@link RestClientAdapterException} exception will be thrown.
* Example: Tests/job/JenkinsAdapterTestBuildJob/ (1)
*/
@Persistent
private String jobName;| 1 | Example Input: An example input with the correct format (optional) |
| Furthermore, formatting such as line breaks can be taken directly from the development environment by using the HTML tag <pre>. |
/**
* <pre>
* @workflowDocu Parameter map for the Jenkins job that will be executed.
* Caution:
* If the build job is not parametrized, the value must be
* null.
* If the build job is parameterized, the parameter map must
* not be null.
* For a parametrized build job the specified map can be empty. In
* this case, the build job will be started with its default
* values.
* A parameter consists of a parameter name (key) and a value
* (value). String, numbers and logic values are supported. Each
* object will be converted to a String using its toString()
* method.
*/
@Persistent(mandatory = false)
private Map<String, Object> parameters;
2.2. @workflowDocu for output parameters
For output parameters, the block should contain an information about the effect/output of the command
/**
* @workflowDocu The id of the build job. Can be retrieved with the
* {@link StartBuildJob} command.
*/
@Persistent(scope = FieldScope.WRITE_ONLY)
private Integer buildId;
2.3. @workflowDocu on Command-level
/**
* @workflowDocu This command gets an element by its id. (1)
*/
@JavaCommand
@CommandGroup("Element")
public class GetElement {
/**
* @workflowDocu Id of the element to fetch (2)
*/
@Persistent
private String id;
[...]
}| 1 | @workflowDocu tag for the command |
| 2 | @workflowDocu tag for a command variable |
Figure 5 shows the user documentation in the PAK BPMN Editor that results by using @workflowDocu.
You can open it by hovering over the command.
The user documentation can be accessed in the Workflow Executor as well by clicking/hovering over the small information symbol.
