Job Definitions

Journey Manager (JM) The transaction engine for the platform. | System Manager / DevOps | 24.10This feature was updated in 24.10

Manager uses job services to process collaboration jobs. You can define and configure a job service as a single JSONJSON (JavaScript Object Notation) is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of attribute–value pairs and arrays. document, which is called a job definition. The job definition includes the list of steps that make up the collaboration job. Each of the individual steps has the list of actions to be performed when the step runs, and the routes property, which defines the next step transition by mapping the route name to the next step.

The job definition consists of the following properties:

jobDetails
jobGroups
steps
actions
properties
routes

jobDetails

The jobDetails property defines a collaboration job and how it is processed. The snippet of the jobDetails is shown below:

{
	"jobDetails": {
		"name": "1 Step Review",
		"processSubmitImmediate": "true",
		"allowEarlyCreation": true,
		"version": "0.1.0"
	},
	"steps":[
		{ .. step definition ...},
		{ .. step definition ...},
		...
	]
}

The jobDetails has the following attributes:

name: The name of the collaboration job, which is set by the job controller service when the collaboration job has been saved.; If defining multiple jobs, use distinct names for each job definition to ensure you can differentiate between them in the Journey Analytics scope selector.
processSubmitImmediate: The collaboration job processing mode. If this attribute is omitted or set to false, the job will use the standard mode. Otherwise, it will use the process immediate mode.
allowEarlyCreation: A boolean flag that allows you to create a collaboration job and associate it with a transaction that can only be in the Opened or Saved state.; This requires the Job Controller to be associated with a form version of a transaction and Job Controller service has the allowEarlyCreation flag set to true in its job definition. The processJobAfterCreate attribute will be ignored in this case.; | 24.10 This feature was introduced in 24.10
version: The version of Manager that the job was created in.

Let's look at a simple example of using the above configuration to create a job given the job controller service and version for a non submitted Txn as the initial Txn:

import com.avoka.tm.svc.*
import com.avoka.tm.vo.*
Job job3 = new JobBuilder()
   .setSvcName('1 Step Review')
   .setSvcVersion('0.1.0')
   .setReferenceNumber('ABC123')
   .setInitialTxnTrackingCode('ABC123')
   .build()

jobGroups

The jobGroups property lists collaboration job groups, so job coordinators can manage the collaboration job. The snippet of the jobGroups is shown below:

"jobGroups": {}

The jobGroups has the following attributes:

name: The name of the job group, which will be displayed in the Job Groups dropdown from the Reviews tab of the form space.
description: The description for the job group.

The job groups can be created in one of the following ways:

If a job group defined in a job definition, as in above, has not been created, then the job group will be automatically created the first time a user submits a form associated to this job. This is the preferred way to create job groups.
Job groups can be manually created. By manually creating the job group, you must ensure that the job group names and descriptions match with the job definition. Any mismatch will not be subsequently updated to the job groups.

steps

The steps property is an JSON array that defines steps. The snippet of the steps property is shown below:

{
      "name": "Initial Review",
      "type": "",
      "expiryRule": "+5d"
      "expiryServiceName": "An Expiry Service"
      "actions": [
        { ... Action 1 Definition ... },
        { ... Action 2 Definition ... }
      ],
      "routes": [
        { "name": "Approve",  "nextStep": "Application Delivery" },
        { "name": "Decline",  "nextStep": "Applicant Update" },
        { "name": "Exceeds Threshold",  "nextStep": "Additional Review",  "display": "false" },
        { "name": "Terminate",  "nextStep": "Terminated Initial" }
      ]
},

The steps has the following attributes:

name

The name of the step, which is unique within a collaboration job.

type

The type of the step, that can be:

start: the first step for the collaboration job. "type":"start"
endpoint: the processing stops and the job completes. Endpoints do not specify actions, routes or customProperties. "type":"endpoint"
"": empty string. "type":""

expiryRule

The step scheduled completion time, the step expiry, calculation rule. If specified, the job_step.time_completion_scheduled is set as the step creation time plus the expiry rule value, for example, 2014-03-05 + 5d = 2014-03-10. The valid values are:

"expiryRule" : "+4h" (hours)
"expiryRule" : "+5d" (days)
"expiryRule" : "+4w (weeks)
"expiryRule" : "+4m". (months)

This is an optional attribute.

Note

We recommend setting it up to some default value so an action doesn't stay in the queue forever, if an associated form never abandons and the task is never submitted, even as a transaction expires.

expiryServiceName

Specifies a job expiry service that is used to clean up some items, such as incomplete submissions. This service should specify a route.

Note

If the expiryRule is used, but the exprityServiceName is not specified, then expiryRoute must be provided.

actions

The actions property defines the list of actions for each step, which are executed sequentially. Actions are required for all steps except endpoints. The snippet of the actions property is shown below:

{
    "name": "Create Task",
    "type": "Job Task Assign",
    "properties": [
        { "name": "Process Message Send Email",  "value": "true" },
        { "name": "Process Message Submission Step",  "value": "Start" },
        { "name": "Process Message Text",  "value": "Your ${submission.formName} application is at the Initial Review Step" },
}

The actions has the following attributes:

name

The name of the action, which is unique within a collaboration job.

type

The action service type, which can be one of the following:

listed above in the Standard Actions Services.
groovy action services can have a type of Job Action.

properties

The action-specific properties. For more information, see the properties object definition below. This is an optional attribute.

The standard Action Property classes (com.avoka.fc.core.service.job.impl) define a fixed set of Action Properties. The JobTaskAssignService defines a broad range of separate properties, so you can add them to your script when creating a new job action. This makes a job action re-useable across a collaboration job and the whole form application. For example, if the job definition has this property:

"properties": [
   { "name": "ABC Widget Name",  "value": "Aplle Blue Catapillar" },
   ...
 ]

Then, you can retrieve it using the Groovy code below:

def abcName = actionStepProperties.getProperty("ABC Widget Name")

However, you should consider the following:

There is no submission associated with the job actions by default.
$formDataMap.name doesn't resolve as the job action and it doesn't have any concept of a submission.
$func.previousSubmission().formDataMap.name resolves a submission as it obtained the submission from the previous step.
$job.submission(0).name resolves a submission as it obtained the first submission linked to the collaboration job.

For more information, see job functions.

properties

The properties property defines the job definition properties. The snippet of the properties property is shown below:

"properties": [
    { "name": "Task Assign Group",  "value": "$func.formProperty('Initial Review')" },
    { "name": "Task Type",  "value": "Review" },
]

Properties can be used to pass information into an instance of the Action Service. In this case, they are called action properties and can be defined at the action, step or collaboration job level. Properties with the same name defined at an action level override properties defined at the step level. Step override properties of the same name at the job level. This is illustrated in the snippet below:

{
  "jobDetails": { ... },
  "properties": [
    { "name": "Task Form Code", "value": "$func.startFormCode()" }
  ],
  "steps":[
    {
      "name": "Initial Review",
      "type": "",
      "actions": [
        {
          "name": "Create Task",
          "type": "Job Task Assign",
          "properties": [
            { "name": "Process Message Text",  "value": "Your ${submission.formName} application is at the Initial Review Step" },
            { "name": "Task Assign Group",  "value": "$func.formProperty('Initial Review')" },
            { "name": "Task Message",  "value": "Please perform the initial review of the ${submission.formName} from ${formDataMap.firstName} ${formDataMap.lastName}." },
            { "name": "Task Review Previous Step",  "value": "true" },
            { "name": "Task Subject",  "value": "Initial review of ${submission.formName} from ${formDataMap.firstName} ${formDataMap.lastName}" },
            { "name": "Task Type",  "value": "Review" },
          ]
        },
        { ... }
      ],
      "properties": [
        { "name": "Task Form Code", "value": "$func.startFormCode()" }
      ],
      "routes": [
        { "name": "Approve",  "nextStep": "Application Delivery" },
        { "name": "Decline",  "nextStep": "Applicant Update" }
      ],
    },
    { ... }
  ]
}

The properties has the following attributes:

name

The name of the property. The predefined action services, such as the job task assign service, have a set number of action properties.

value

A property value that can include an Apache Velocity template. The action properties are templates that are evaluated when an action service is run. The templates can be:

static text values, for example, { "name": "Task Email Message", "value": "An Email Message" }
substitute values from the form data extract, for example, { "name": "Process Message Text", "value": "Your ${job.submission.formName} application is at the Initial Review Step" }

template

It evaluates the value as a velocity template and forces the return value to return a String. This can evaluate nested function calls. This is can be used with property values that start with "$func", these can return an object. For example, $func.startUser() will return a user.

{ "name": "Task Email Message", "value": "$func.getSubmission().formXml()", "template": "true" }

routes

The routes property defines the route mapping between the route name and the next step, which are required for all steps except endpoints. An action can return a route result name, as a string, which is listed in each step. If a valid name is returned, the step routes the collaboration job to the next step. However, if the action returns an invalid route name, an error is thrown. The snippet of the routes property is shown below:

"routes": [
   { "name": "Approve",  "nextStep": "Application Delivery" },
   { "name": "Decline",  "nextStep": "Applicant Update" },
   { "name": "Exceeds Threshold",  "nextStep": "Additional Review",  "display": "false" },
   { "name": "Terminate",  "nextStep": "Terminated Initial" }
]

The routes has the following attributes:

name

The route name that can be any name except the following reserved names:

Default - If there is no step found with a route name or if the route name is empty, the default route is used.
Expiry - the route taken when the step has expired.

nextStep

The next step, which can be one of the following:

A valid step name contained in the job definition.
A special case is ##PREVIOUS_STEP the job processing assign the next step as the previous step name.

display

The collaboration job provides a list of available routes to the form. However, the "display": "false" removes the route from the available routes. This is an optional attribute.

You can see the complete example of a job definition here.

Next, learn how to configure job definition.

Topics

Job Definitions

jobDetails

jobGroups

steps

actions

properties

routes

In this topic

Need More Help?