powered by ASAP

This chapter demonstrates how to document a command with advanced formatting and functions.

You can use classes, methods or write human tasks with HTML. How to document your command changes based on what approach was chosen.
You can also apply the HTML logic of this guide to the documentation of workflows.
This guide only applies to the documentation visible in the workflow executor.

1. Introduction

In this howto you learn how you can improve your documentation by using selected HTML tags.

Advanced option can also be used in Human Tasks and workflows.
Any advanced option covered by this guide is only applicable to the documentation of the full command, not to its inputs and outputs!

2. Prerequisites

To complete this guide you need:

  • Roughly 10 minutes

  • JDK11+ installed with JAVA_HOME configured appropriately

  • An IDE (we recommend IntelliJ)

  • Some kind of build tool (like gradle, maven or ant)

  • Know how to use the Single Command Runner in the Workflow Executor

3. Document your command

For the following examples a java command is used. How to apply these concepts to human tasks will be explained at the end of this guide.

3.1. Using classes as Commands

You can document your command by using the @workflowDocu annotation in the javaDoc like follows:

[...]

/**
 * This is a sample command for displaying purposes
 *
 * (1)
 * @workflowDocu  This is the documentation of this command!
 */
@JavaCommand
public class Example {
	[...]
}
BaseDocumentation
Figure 1. The resulting documentation.
1 The @workflowDocu annotation in the javaDoc signalizes that the text afterwards should be regarded as documentation of the command.

The input field can be documented as follows:

[...]
@JavaCommand
public class Example {

    /**
     * @workflowDocu  This is the documentation of the input! (2)
     *
     */
    @Persistent
    private String input;
}

The documentation will be shown here:

InputDocumentation
Figure 2. Documented input
1 Click on the info icon.
2 Under the documentation headline, the @workflowDocu marked text will appear.

3.2. Using methods as commands

When creating commands from legacy code, you might create commands from methods. Their documentation works different from using a class as command. The regular documentation of the command still needs to be marked with @workflowDocu. The documentation of inputs and outputs will be taken from the @param <parameter name> and @return annotation respectively.

[...]

@JavaCommandService
public class ExampleMethodCommandClass {

	/**
	 * @workflowDocu This is regular command documentation! (1)
	 *
	 * @param input This is input documentation! (2)
	 * @return This is output documentation! (3)
	 */
	public String example(final String input) {
		return "Input was: " + input;
	}
}
CommandFromMethodBase
Figure 3. Command generated from a method
CommandFromMethodInput
Figure 4. Documentation of an input of a command generated from a method
CommandFromMethodOutput
Figure 5. Documentation of an output of a command generated from a method
1 Regular command Documentation. In this part you can also you the advanced options.
2 Documentation of the parameter is the same as the documentation of the input.
3 Documentation of the return value is the same as the documentation of the command output.

4. Writing advanced documentation

Sometimes plain text might not be enough to explain complex commands. Then you might want to use formatting, styling and maybe some functional tags to empower your documentation. You can do this by using following HTML tags: <p>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <div>, <br>, <b>, <strong>, <table>, <a> and <code>. How these effect you documentation, will be explained in the following paragraphs!

The given examples are using classes as commands. If you are using methods as commands, you can still use these tags in the documentation text!

4.1. Formatting

4.1.1. Linebreak

If you want to format the text with a linebreak, you need to use the HTML tag <br>:

[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  This is the documentation of this command! (1)
 *                This results in the line to be continued! <br> (2)
 *                This will be displayed in the next line!
 */
@JavaCommand
public class Example {
	[...]
}
Linebreak
Figure 6. The resulting documentation.
1 Regular line breaks in the source code will have no effect on the displayed documentation in the workflow executor.
2 The br tag will result in a linebreak at its location.

4.1.2. Paragraph

You can also use paragraphs, using the HTML tag <p>:

[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  This is the documentation of this command!
 *                <p> (1)
 *                This is the paragraphs content!
 *                </p> (2)
 *                This will be displayed in the next line!
 */
@JavaCommand
public class Example {
	[...]
}
Paragraph
Figure 7. The resulting documentation.
1 Paragraphs will always leave an empty line to the content before, if there is any!
2 Paragraphs will always space them self one line apart to the content following the paragraph!
The tags <p>, <div>, <table> and heading tags <h1-6> are unavailable whilst within a paragraphs ⇒ No nesting of these tags inside paragraphs!

4.1.3. Headings

The documentation supports 6 different headings. You can use those with the tags <h1>, <h2>, <h3>, <h4>, <h5> and <h6> with the biggest heading being <h1> and the smallest being <h6>.

Headings can be used in the same way as paragraphs, but they affect font size and text style. Common usage is for dividing the documentation into smaller sections.

4.1.4. Container

Containers work differently as how they would work in a regular HTML file!

Containers in the documentation mark a new line before and after the content.

[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  This is the documentation of this command!
 *                <div> (1)
 *                This is the containers content!
 *                </div> (2)
 *                This will be displayed in the next line!
 */
@JavaCommand
public class Example {
	[...]
}
Container
Figure 8. The resulting documentation.
1 Containers always start in a new line!
2 Any content after the container will start in a new line!

Containers can be used for wrapping multiple tags.

An example of that is:

[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  This is the documentation of this command!
 *                <div> (1)
 *                <p>
 *                This is the first paragraph!
 *                </p>
 *                <p>
 *                This is the second paragraph!
 *                </p>
 *                <p>
 *                This is the third paragraph!
 *                </p>
 *                </div> (2)
 *                This will be displayed in the next line!
 */
@JavaCommand
public class Example {
	[...]
}
Example 1. Command run with no optional inputs
ContainerWithParagraphs
ContainerWithParagraphsEnding
1 The container starts in a new line before the paragraph lists adds it own spacing.
2 The paragraph adds its spacing before the container ends by entering a new line.
With longer lists it gets easier to spot where the list starts and ends using the <div> tag.

4.1.5. Table

You can use tables in your documentation.

Tables have a fixed format. You cannot change it!
A table only supports plain text. It ignores any tags that are not part of the table.

This is how a table can be structured:

[...]

/**
* This is a sample command for displaying purposes
*
*
* @workflowDocu  This is the documentation of this command!
*                <table> (1)
*                <tr> (2)
*                <th> (3)
*                Table Heading of column one
*                </th> (3)
*                <th>
*                Table Heading of column one
*                </th>
*                </tr> (2)
*                <tr>
*                <td> (4)
*                Some table content
*                </td> (4)
*                <td>
*                Some more table content
*                </td>
*                </tr>
*                <caption>This is an example table!</caption> (5)
*                </table> (1)
*                This will be displayed in the next line!
*/
@JavaCommand
public class Example {
[...]
}
Table
Figure 9. The resulting documentation.
1 Everything within the <table> tag is parsed as part of the table. Unknown or wrongly placed tags or elements will be ignored.
2 A table row is signified with the <tr> tag. A table row can contain multiple elements that are the contents of this row.
3 A table head <th> is a special kind of table content as they can be seen as a headline.
4 Regular table data is marked with the <td> tag.
5 (Optional) This is a <caption> for the table that will be displayed above the Table.
You can space the table from the surrounding documentation by nesting the table into containers!

4.2. Styling tags

Inline styles will be ignored.

4.2.1. Making text bold

There are currently two different options of making certain text elements bold: Using <b> or <strong>

Both tags work in the exact same way! The only difference between the two is a semantic difference: Use <strong> to highlight something and use <b> out of a stylistic choice!
[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  This is the <strong>documentation</strong> of this command! (1)
 *                I still want this <b>bold!</b> (2)
 */
@JavaCommand
public class Example {
	[...]
}
Bold
Figure 10. The resulting documentation.
1 Making documentation bold out of an emphasis on this part!
2 Making bold! bold out of a stylistic choice!

4.3. Functional tags

Only plain text is allowed within those tags!

You can embed links into your documentation with the <a> tag:

[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  More information available on our <a href='https://pak.asap.de/'>website</a>! (1)
 */
@JavaCommand
public class Example {
	[...]
}
Link
Figure 11. The resulting documentation.
1 The word website will have an on click event, which opens an external website in your default browser. The URL specified behind the href is the website that opens, in this case https://pak.asap.de/!

4.3.2. Examples

If you want to add an example that the user can copy, you should use the <code> tag. The user then can click on the text to copy it into the clipboard

This also has a style to highlight the example!
[...]

/**
 * This is a sample command for displaying purposes
 *
 *
 * @workflowDocu  Try to run the command with following input:<code>This is an example that can be used to run the command</code> (1)
 */
@JavaCommand
public class Example {
	[...]
}
Example
Figure 12. The resulting documentation.
1 The example being highlighted and having an on click event pasting the content into the clipboard for pasting into command inputs!

5. Human Task Documentation

You can use all the different option listed above in human tasks.

Documenting human tasks is fundamentally different from documenting java commands.

5.1. Documenting a human task

In a human task is a container, that is of class meta. This class contains the meta information about the human task. In this container we also document the human task.

Using the advanced formatting options is not as simple as in java. The tags will regularly be interpreted as part of the actual file and not as part of the documentation text. For that reason you need to escape the HTML tags in your documentation.

The meta information can look like this:

<div class="meta"><!-- Meta info for human task interpreter -->
<#command major="1" minor="0" increment="0" group="HumanTasks.Generic"
workflowDocu="A link to our &lt;a href='https://pak.asap.de/';&gt;website&lt;/a&gt;" /> (1) (2)
<#datastore documentation="Documentation of an input!" key="input" scope="READ" mandatory="true" type="STRING"/> (3)
</div>

[...]
HumanTaskWithEscapedLink
Figure 13. Human task being opened in the single command runner
HumanTaskInputDocu
Figure 14. Input Documentation of a human task
1 The documentation is under the workflowDocu argument of the <#command /> tag.
2 Using advanced options like a link requires to write the HTML tags within the documentation text with the < and > parts of the tag being replaced with &lt; and &gt; respectively. These are the escaped character replacements for writing a < or > as text and not as a beginning or end of a tag.
3 The documentation of <#datastore /> tag is under the documentation argument.

6. Nice to know

6.1. Copying text from documentation

To copy text from the documentation you can simply click on the word you want to copy, as selecting text is not possible.

Following tags will only let you copy their whole content: <td>, <th>, <a> and <code>!

6.2. Inline arguments

You cannot use inline arguments like inline styles or classes!

Any inline argument of HTML tags is ignored, except the href on the <a> tags!

6.3. Applying HTML to the documentation of a workflow

This requires knowledge about how to use the PAK Editor to build workflows.

Documenting a workflow with advanced HTML tags works similar to documenting a java command. You are still restricted by the same HTML logic. You can add the HTML to your workflow documentation like follows:

AddHtmlToWorkflowDocu.bpmn

1 You can simply add HTML tags like this.
2 You can do this with all previously mentioned supported HTML tags.

Sonatype Nexus

PAK features connectors and commands for Sonatype Nexus. This means the software can directly interact with Nexus repositories for storing and managing artifacts. Through these connectors, PAK can automate tasks like uploading binaries or retrieving dependencies, ensuring efficient artifact management within Nexus.

Jenkins

PAK has connectors and commands for Jenkins. This allows the software to directly communicate with Jenkins servers, enabling the automation of CI/CD (Continuous Integration/Continuous Deployment) tasks. Through these connectors, PAK can trigger builds, fetch build statuses, or manage job configurations, streamlining the CI/CD processes within Jenkins.

Git Hub

PAK possesses connectors and commands for GitHub. This means the software can interface directly with GitHub repositories, facilitating actions like code pushes, pull requests, or issue tracking. Through these connectors, PAK can automate various GitHub operations, enhancing code collaboration and repository management.

Atlassian Confluence

PAK is equipped with connectors and commands for Atlassian Confluence. This enables the software to directly interact with Confluence spaces and pages. Through these connectors, PAK can automate actions such as creating, updating, or retrieving documentation, ensuring efficient content management and collaboration within Confluence.

Codebeamer

PAK features connectors and commands for Codebeamer. This allows the software to seamlessly integrate with Codebeamer’s ALM (Application Lifecycle Management) platform. Through these connectors, PAK can automate tasks like issue tracking, test management, or requirements tracing, enhancing the coordination and management of software development processes.

JFrog Artifactory

PAK has connectors and commands for JFrog Artifactory. This means the software can directly interface with Artifactory repositories, enabling actions like artifact storage, retrieval, and management. Through these connectors, PAK can automate tasks such as deploying artifacts or managing repository configurations, streamlining the integration and management of binary artifacts within Artifactory.

Amazon Web Services (AWS)

PAK has connectors and commands for Amazon Web Services (AWS). This means the software possesses specialized interfaces to directly interact with AWS services and execute actions on the AWS platform. Through these connectors, PAK can automate AWS-specific commands, such as launching EC2 instances, managing S3 buckets, or configuring Lambda functions. This allows for efficient integration, management, and automation of AWS resources and services directly from PAK.

Atlassian Jira

PAK features integration tools and capabilities for Atlassian Jira. These tools allow for a direct connection to Jira and the execution of specific actions. Using these integration tools, PAK can automate Jira actions such as adding comments or changing ticket priorities, ensuring seamless handling and coordination of Jira processes.

Git

PAK has connectors and commands for Git. This means it has interfaces to directly communicate with Git and execute actions. Through these connectors, the software can automate Git commands such as retrieving changes or creating branches, enabling efficient integration and management of Git tasks.

Generic Human Tasks

PAK offers you a standard set of commands which require creative input from the user. Enables you to start with automating your workflows, that still need abit of human input.

Generic Commands

PAK offers a standard set of commands giving you the first steps to automate your workflows.

Nexus Maven Command Pool

Nexus is an artifact repository manager for storing binaries, libraries, and artifacts, supporting formats like Maven. Maven, a software project management tool, is based on the Project Object Model (POM) and allows developers to consistently define projects and dependencies. Our Command Pool offers commands for interactions between Maven and Nexus, such as artifact uploads or dependency retrieval.

Artifactory Maven Command Pool

Artifactory allows developers to store, retrieve, and manage binary files and artifacts, providing a
central source for all binaries used in a development process. Apache Maven is a software project
management and comprehension tool that enables developers to consistently describe a project and
its dependencies. Our Command Pool offers a collection of commands used to facilitate interactions
between Maven and Artifactory, such as uploading artifacts or retrieving dependencies.

Open API Command Interpreter

The OpenApi Command Interpreter allows you the automatic parsing of commands from an OpenApi defintion. No additional code needs to be written anymore, just add the address to the definition and our framework does the rest!

Kotlin Command Interpreter

The Kotlin Command Interpreter allows you the parsing and execution of commands within a Kotlin environment to automate various tasks or processes.

Bpmn Interpreter

Workflows come in many shapes and forms. The BPMN (Business Process Model and Notation) Interpreter enables the parsing of worklows defined in the BPMN format into the PAK intern model.

Human Task Interpreter

The Human Task Interpreter allows you the parsing and running of commands within a HTML and Javascript environment. Use this to build commands which need the creative input of a workflow user!

Java Command Interpreter

The Java Command Interpreter allows you the parsing and execution of commands within a Java
environment to automate various tasks or processes.

Core

The heart of the PAK-Framework. Contains the means to run workflows with the PAK engine, but also the possibility to enrich the frameworks interfaces with your own implementations and solutions.

RocksDB Persistence

Data that is generated by a workflow run needs to be saved for short or longer terms. Our solution to the Persistence Interface of the PAK-Framework is to use the high-performance, key-value based RocksDB developed by Facebook.

PAK online

PAK Online is a web based application and provides an Open API based REST API. It enables you to upload workflows and run them periodically or on REST demand.

Command Line App

Run tasks and workflows on the console or as part of a CI/CD Pipeline with our Command Line Interface.

Workflow Editor

With our specially developed editor, a wide variety of workflows can be easily modeled in the wide known BPMN process format.

Workflow Executor

The Workflow Executor is the application to run your workflows. It features a multilingual UI and easy managment of your favorite workflows.

Support

We offer a community website where you can exchange ideas and support each other. For our Pro packages we also offer full support via email.