Chapter 61. Work item definitions

Red Hat Process Automation Manager requires a work item definition (WID) file to identify the data fields to show in Business Central and accept API calls. The WID file is a mapping between user interactions with Red Hat Process Automation Manager and the data that is passed to the work item handler. The WID file also handles the UI details such as the name of the custom task, the category it is displayed as on the palette in Business Central, the icon used to designate the custom task, and the work item handler the custom task will map to.

In Red Hat Process Automation Manager you can create a WID file in two ways:

  • Use a @Wid annotation when coding the work item handler.
  • Create a .wid text file. For example, definitions-example.wid.

61.1. @Wid Annotation

The @Wid annotation is automatically created when you generate a work item handler project using the Maven archetype. You can also add the annotation manually.

@Wid Example

@Wid(widfile="MyWorkItemDefinitions.wid",
    name="MyWorkItemDefinitions",
    displayName="MyWorkItemDefinitions",
    icon="",
    defaultHandler="mvel: new com.redhat.MyWorkItemWorkItemHandler()",
    documentation = "myworkitem/index.html",
    parameters={
      @WidParameter(name="SampleParam", required = true),
      @WidParameter(name="SampleParamTwo", required = true)
    },
    results={
      @WidResult(name="SampleResult")
    },
    mavenDepends={
      @WidMavenDepends(group="com.redhat",
      artifact="myworkitem",
      version="7.52.0.Final-example-00007")
    },
    serviceInfo={
      @WidService(category = "myworkitem",
      description = "${description}",
      keywords = "",
      action = @WidAction(title = "Sample Title"),
      authinfo = @WidAuth(required = true,
      params = {"SampleParam", "SampleParamTwo"},
      paramsdescription = {"SampleParam", "SampleParamTwo"},
      referencesite = "referenceSiteURL"))
    }
)

Table 61.1. @Wid descriptions

 Description

@Wid

Top-level annotation to auto-generate WID files.

widfile

Name of the file that is automatically created for the custom task when it is deployed in Red Hat Process Automation Manager.

name

Name of the custom task, used internally. This name must be unique to custom tasks deployed in Red Hat Process Automation Manager.

displayName

Displayed name of the custom task. This name is displayed in the palette in Business Central.

icon

Path from src/main/resources/ to an icon located in the current project. The icon is displayed in the palette in Business Central. The icon, if specified, must be a PNG or GIF file and 16x16 pixels. This value can be left blank to use a default “Service Task” icon.

description

Description of the custom task.

defaultHandler

The work item handler Java class that is linked to the custom task. This entry is in the format <language> : <class>. Red Hat Process Automation Manager recommends using mvel as the language value for this attribute but java can also be used. For more information about mvel, see MVEL Documentation.

documentation

Path to an HTML file in the current project that contains a description of the custom task.

@WidParameter

Child annotation of @Wid. Specifies values that will be populated in the Business Central GUI or expected by API calls as data inputs for the custom task. More than one parameter can be specified:

name - A name for the parameter.

Note

Due to the possibility of this name being used in API calls over transfer methods such as REST or SOAP, this name should not contain spaces or special characters.

required - Boolean value indicating whether the parameter is required for the custom task to execute.

@WidResult

Child annotation of @Wid. Specifies values that will be populated in the Business Central GUI or expected by API calls as data outputs for the custom task. You can specify more than one result:

name - A name for the result.

Note

Due to the possibility of this name being used in API calls over transfer methods such as REST or SOAP, this name should not contain spaces or special characters.

@WidMavenDepends

Child annotation of @Wid. Specifies Maven dependencies that will be required for the correct functioning of the work item handler. You can specify more than one dependency:

group - Maven group ID of the dependency.

artifact - Maven artifact ID of the dependency.

version - Maven version number of the dependency.

@WidService

Child annotation of @Wid. Specifies values that will be populated in the service repository.

category - The UI palette category that the handler will be placed. This value should match the category field of the @Wid annotation.

description - Description of the handler that will be displayed in the service repository.

keywords - Comma-separated list of keywords that apply to the handler. Note: Currently not used by the Business Central service repository.

action - The @WidAction object.

authinfo - The @WidAuth object. Optional.

@WidAction

Object of @WidService.

title - The title for the handler action.

description - The description for the handler action.

@WidAuth

Object of @WidService.

required - The boolean value that determines whether authentication is required.

params - The array containing the authentication parameters required.

paramsdescription - The array containing the descriptions for each authentication parameter.

referencesite - The URL to where the handler documentation can be found. Note: Currently not used by the Business Central service repository.

61.2. Text File

A global WorkDefinitions WID text file is automatically generated by new projects when a business process is added. The WID text file is similar to the JSON format but is not a completely valid JSON file. You can open this file in Business Central. You can create additional WID files by selecting Add Asset > Work item definitions from an existing project.

Text file example

[
  [
    "name" : "MyWorkItemDefinitions",
    "displayName" : "MyWorkItemDefinitions",
    "category" : "",
    "description" : "",
    "defaultHandler" : "mvel: new com.redhat.MyWorkItemWorkItemHandler()",
    "documentation" : "myworkitem/index.html",
    "parameters" : [
      "SampleParam" : new StringDataType(),
      "SampleParamTwo" : new StringDataType()
    ],
    "results" : [
      "SampleResult" : new StringDataType()
    ],
    "mavenDependencies" : [
      "com.redhat:myworkitem:7.52.0.Final-example-00007"
    ],
    "icon" : ""
  ]
]

The file is structured as a plain-text file using a JSON-like structure. The filename extension is .wid.

Table 61.2. Text file descriptions

 Description

name

Name of the custom task, used internally. This name must be unique to custom tasks deployed in Red Hat Process Automation Manager.

displayName

Displayed name of the custom task. This name is displayed in the palette in Business Central.

icon

Path from src/main/resources/ to an icon located in the current project. The icon is displayed in the palette in Business Central. The icon, if specified, must be a PNG or GIF file and 16x16 pixels. This value can be left blank to use a default “Service Task” icon.

category

Name of a category within the Business Central palette under which this custom task is displayed.

description

Description of the custom task.

defaultHandler

The work item handler Java class that is linked to the custom task. This entry is in the format <language> : <class>. Red Hat Process Automation Manager recommends using mvel as the language value for this attribute but java can also be used. For more information about mvel, see MVEL Documentation.

documentation

Path to an HTML file in the current project that contains a description of the custom task.

parameters

Specifies the values to be populated in the Business Central GUI or expected by API calls as data inputs for the custom task. Parameters use the <key> : <DataType> format. Accepted data types are StringDataType(), IntegerDataType(), and ObjectDataType(). More than one parameter can be specified.

results

Specifies the values to be populated in the Business Central GUI or expected by API calls as data outputs for the custom task. Results use the <key> : <DataType> format. Accepted data types are StringDataType(), IntegerDataType(), and ObjectDataType(). More than one result can be specified.

mavenDependencies

Optional: Specifies Maven dependencies required for the correct functioning of the work item handler. Dependencies can also be specified in the work item handler pom.xml file. Dependencies are in the format <group>:<artifact>:<version>. More than one dependency may be specified

Red Hat Process Automation Manager tries to locate a .wid file in two locations by default:

  • Within Business Central in the project’s top-level global/ directory. This is the location of the default WorkDefinitions.wid file that is created automatically when a project first adds a business process asset.
  • Within Business Central in the project’s src/main/resources/ directory. This is where WID files created within a project in Business Central will be placed. A WID file may be created at any level of a Java package, so a WID file created at a package location of <default> will be created directly inside src/main/resources/ while a WID file created at a package location of com.redhat will be created at src/main/resources/com/redhat/
Warning

Red Hat Process Automation Manager does not validate that the value for the defaultHandler tag is executable or is a valid Java class. Specifying incorrect or invalid classes for this tag will return errors.