Develop a Human Task

This chapter describes how to develop Human Tasks in PAK.

1. Introduction

Human Tasks are commands, which can be developed using a special HTML-based notation. They generally describe tasks that can’t be automated and require the creative work from a human. Most Human Tasks are used in order to get specific inputs or confirmations by the user. They can be put in two categories, generic tasks which can be executed in most environments and domain specific tasks which are for example limited to the Workflow Executor.

2. Requirements

The HTML Interpreter is provided for Human Task development using HTML, JavaScript and CSS. Therefore, basic skills in HTML, JavaScript and CSS are required in order to develop Human Tasks.

Several dependencies and tasks are required as well, which will be described in the following. Additionally, an example implementation of a build.gradle and settings.gradle for Gradle and a pom.xml for Apache Maven are given.

2.1. Gradle

If you want to use Gradle for your Human Task Development you can use the following build.gradle and settings.gradle as orientation for needed dependencies.

Listing 1. build.gradle

plugins {
    id 'java'
    // only required if eclipse is used as the IDE
    id 'eclipse'
    // dependencies for html-processor, which it makes it possible
    // to process html-files into commandmetas
    id 'de.asap.pak.html.processor' version '1.6.15'
}


// the version of your human task
version = '1.7.5432-SNAPSHOT'
project.description = 'TestHumanTask'
project.group = 'html.org.example.pak.humantasks'

repositories {

    maven {
        name = 'pak-explorer-maven'
        url 'https://pak.asap.de/nexus/repository/pak-explorer-maven/'
    }
    mavenCentral()
}


task metaJar(type: Jar) {
    archiveClassifier = 'pakmeta'
    from sourceSets.main.output
    include 'meta/**'
    include 'entities/**'
    from sourceSets.main.java
    include 'icon/**'
}


eclipse {
    // automatically generate meta files on eclipse refresh
    synchronizationTasks analyseHtml
}
jar.dependsOn(analyseHtml)
// Creates the meta files always with each gradle build call
build.finalizedBy(analyseHtml)

Listing 2. build.gradle

pluginManagement {
    repositories {
        maven {
            name = 'asap-maven-public'
            credentials {
                username nexusUser
                password nexusPass
            }
            url 'https://in13sv-mc04.group.asap.de/nexus/repository/maven-public/'
        }
        gradlePluginPortal() // needs to be specified, since these settings overwrite all default repositories
    }
}

rootProject.name = 'humantasks'

2.2. Apache Maven

If you want to use Apache Maven for your Human Task Development you can use the following pom.xml as orientation for needed dependencies.

Listing 3. pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<groupId>html.org.example.pak.humantasks</groupId>
<artifactId>'TestHumanTask'</artifactId>
<version>1.7.5432-SNAPSHOT</version>

<properties>
    <pakVersion>1.6.15</pakVersion>
</properties>

<repositories>
    <repository>
        <id>pak-explorer-maven</id>
        <url>https://pak.asap.de/nexus/repository/pak-explorer-maven/</url>
    </repository>
</repositories>

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.0</version>
            </plugin>
            <plugin>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.0.2</version>
            </plugin>
            <plugin>
                <groupId>de.asap.pak.html</groupId>
                <artifactId>processor</artifactId>
                <version>${pakVersion}</version>
            </plugin>
        </plugins>
    </pluginManagement>
</build>

</project>

Several dependencies and tasks are required, which will be described in the following chapter.

2.3. Dependencies

The required dependencies (in an Apache Maven or Gradle based project setup) are described below.

`html-processor`	Processes HTML-files and automatically generates the corresponding command meta information based on the given datastore information.
`html-interpreter`	Similar to the Java interpreter, there is an HTML interpreter for the Human Tasks. The idea is that all kind of controls can be used and commands can be written that are suitable for display in a Web-UI as well as in a local client application (e.g. via JavaFx browser engine). Interprets the processed CommandMeta into a Java Command.

html-processor

Processes HTML-files and automatically generates the corresponding command meta information based on the given datastore information.

html-interpreter

Similar to the Java interpreter, there is an HTML interpreter for the Human Tasks. The idea is that all kind of controls can be used and commands can be written that are suitable for display in a Web-UI as well as in a local client application (e.g. via JavaFx browser engine). Interprets the processed CommandMeta into a Java Command.

2.4. Project Structure

In order to achieve the generation of working CommandMetas it’s important to have the correct base project-structure. The following image will show one such example:

Figure 1. Sample Project Structure for the development of Human Tasks in Gradle

Create a new module where the Human Tasks are stored.
The sub-modules main and test (sub-module test is not required as Human Tasks can not be unit tested yet) are created automatically in a Gradle based project. Therefore, a build.gradle and settings.gradle file must be added to the module. In order to add the required dependencies to the module (The content of these files is specified here).
It makes sense to distribute the logic of the Human Tasks in different packages within the resources directory of the main sub-module. Scripts (js-files) can for example be saved within html.org.example.pak.humantasks.script and css-files in html.org.example.pak.humantasks.css. The general Human Tasks (html-files) can e.g. be stored in the html.org.example.pak.humantasks package.

3. Example Implementation

Listing 4. Development of example Human Task: HumanTaskExample.html

<div class="meta"><!-- Meta info for human task interpreter -->
    <#command major="1" minor="0" increment="0" group="HumanTasks.Generic"
    workflowDocu="My Sample Human Task Command" />  (1)
    <#datastore documentation="docu of specific read-variable" key="readVariable" scope="READ" mandatory="false" type="STRING"/> (2)
    <#datastore documentation="docu of specific write-variable" key="writeVariable" scope="WRITE" mandatory="true" type="INTEGER" deprecated="This variable is deprecated"/>
</div>

<html lang="en"> (3)
<head>
    <link rel="stylesheet" [...]>
    <title>SampleHumanTask</title>
</head>
<body>
[...]
<form method="POST" class="formBox"> (4)
    <div>Human Task</div>
    <!-- Hidden variable to write into DS -->
    <input type="hidden" id="writeVariable" name="writeVariable">
    <!-- The Button-Row -->
    <div class="right">
        <!-- Button action -->
        <input class="btn" type="submit" onclick="someJavaScriptMethod(this.value)" value="Button to press"/>
    </div>

</form>
</body>


<script> (5)
    // Internal logic of command, can be defined by using JavaScript

</script>
</html>

1	Defines the general information for the command. In this listing the `workflowDocu`, the `version` and the `CommandGroup` of the command are getting set. Furthermore, it’s possible to deprecate a command and enter a deprecated-docu, this can be achieved by using the `deprecated` flag and setting it to a concrete string-value.
2	Defines the information for the variables within the command (CommandMappings). Here it is possible to define the `scope`, the `documentation` and the `mandatory-level` of the mapping. Mappings can also be made deprecated, and a deprecation docu can be added, this can be achieved by using the `deprecated` flag.
3	It’s possible to introduce own designs by defining and referencing css files.
4	In here, the user can configure how the `WRITE` mapping is getting processed and what action should be taken if the button is pressed.
5	In the script-part of the html the business logic of the command can be defined. The business logic must be defined using `JavaScript`.

Here you can check out Human Tasks, which can already be used in the Workflow Executor.

3.1. Visualisation of Human Tasks in the Executor

The following image shows how the command defined in the example above gets displayed in the Workflow Executor.

Figure 2. Visualisation of a Human Task in the Workflow Executor

A Human Task does look quite similar in the Executor, compared to the normal Java Commands. The main difference is that on the right side of the screen a window is opened (after the user executes the command), where the user can „interact“ with the specific Human Task.

If you’re curious on how to test your human task, more information can be found here.

Please keep in mind that the design of your Human Task can differ from the one shown in this example. The design depends on the referenced css-files.