@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.

Listing 1. Integration of @workflowDocu via the build.gradle file

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:

Listing 2. Usage of @workflowDocu for input-variables in combination with other annotations

         /**
	 * @workflowDocu The authentication type used to authenticate
	 */
	@Group(GROUP_NAME)
        @AllowedValues(values = "REST_BASIC") (1)
        @Persistent(mandatory = false) (2)
	private String authType;

Figure 1. The resulting documentation, using @AllowedValues and @Persistent

Syntax information: Concrete specifications for the input which can be defined in annotations like @Persistent or @AllowedValues

1	@AllowedValues: Marks a field to only allow specific values. This annotation only works when used together with the `@Persistent` annotation. The field must be of type String or Enum.
2	@Persistent: When setting `@Persistent` to 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.

Listing 3. Usage of @workflowDocu for input-variables giving an example

	/**
	 *
	 * @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)

Figure 2. The resulting documentation, using an example

Furthermore, formatting such as line breaks can be taken directly from the development environment by using the HTML tag <pre>.

Listing 4. @workflowDocu using the <pre> tag

	/**
         * <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;

Figure 3. The resulting documentation, using the <pre> tag

2.2. @workflowDocu for output parameters

For output parameters, the block should contain an information about the effect/output of the command

Listing 5. Usage of @workflowDocu for output-variables

	/**
	 * @workflowDocu The id of the build job. Can be retrieved with the
	 *               {@link StartBuildJob} command.
	 */
	@Persistent(scope = FieldScope.WRITE_ONLY)
	private Integer buildId;

Figure 4. The resulting documentation for output-parameters

2.3. @workflowDocu on Command-level

Listing 6. Usage of @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.

Figure 5. User documentation in the PAK BPMN Editor

Figure 6. User documentation in the Workflow Executor