Introduction

JS7 offers an API for jobs that are executed in the Agent's Java Virtual Machine:

JS7 - Java Jobs
- Such jobs are operated in the Java Virtual Machine used with the related JS7 Agent.
JS7 - JavaScript Jobs
- Such jobs require use of the Oracle® GraalVM Java Virtual Machine with the related JS7 Agent.
  - JS7 - Installing Oracle GraalVM
  - JS7 - Installing 3rd-party Packages for Oracle GraalVM JavaScript Runtime

JS7 offers an API to such jobs that serves the purpose of

accessing arguments available to the job from various sources such as JS7 - Order Variables, job and node arguments, JS7 - Job Resources,
allowing to specify the outcome of a job including return values that are passed to subsequent jobs from order variables.

Support for Java Jobs and JavaScript Jobs is available starting from the following releases:

FEATURE AVAILABILITY STARTING FROM RELEASE 2.5.4

FEATURE AVAILABILITY STARTING FROM RELEASE 2.6.1

Argument Sources

Arguments to jobs originate from a number of sources:

Workflow Variables
- They are declared with the workflow and can hold default values. If no default value is specified then an order has to carry the variable and to assign a value. Otherwise an order optionally can assign a value to the variable.
- Declared Variables include all variables declared with the workflow, optionally holding default values.
- Order Variables include the variables specified with the order. This is a subset of the Declared Variables as carried by the order:
  - Orders are forced to specify variables for which no default value is declared.
  - Orders can specify any Declared Variables optionally over-ruling the variable's default value.
Job Arguments
- The arguments are specified as key/value pairs with the given job. In case of multiple occurrence of the same job in a workflow the same arguments are used.
Node Arguments
- The arguments are specified as key/value pairs with the job's node that is specific for the occurrence of a job in a workflow. Node Arguments allow to specify different argument sets if the same job is used a number of times in the workflow.
Job Resource Variables
- The variables are specified as key/value pairs from JS7 - Job Resources.
- Job Resources can be assigned individually per job or to all jobs in a workflow.

Access to arguments by a job includes to read arguments from a specific source or to read all arguments.

Classes

Class js7.Job

The js7.Job class is an abstract class that is implemented by the JS7Job class in the job:

Methods

Method	Argument	Return Value
`processOrder()`	`[object] js7Step`	n/a

Objects

Object		Purpose
`js7Step`		The built-in object `js7Step` provides a number of methods
Area	Method	Argument	Return Value
Argument	`getAllArguments`	`n/a`	`[object[]] arguments`
	`getAllArgumentsAsNameValueMap`	`n/a`	`[map] argumentMap`
	`getAllDeclaredArguments`	`n/a`	`[object[]] arguments`
	`getDeclaredArgument`	`[string] argumentName`	`[object] argument`
	`getDeclaredArgumentValue`	`[string] argumentName`	`[string\|int\|bool] argumentValue`
	`getJobResourcesArgumentsAsNameDetailValueMap`	`n/a`	`[map] arguments`
	`getOrderArgumentsAsNameValueMap`	`n/a`	`[map] arguments`
Job	`getAgentId`	`n/a`	`[string] agentId`
	`getJobEnvironment`	`n/a`	`[object] jobEnvironment`
	`getJobEnvironment().getJobKey`	`n/a`	`[string] jobKey`
	`getJobEnvironment().getEncoding`	`n/a`	`[string] encoding`
	`getJobEnvironment().getDeclaredArguments`	`n/a`	`[object[]] jobArguments`
	`getJobInstructionLabel`	`n/a`	`[string] label`
	`getJobName`	`n/a`	`[string] jobName`
	`getControllerId`	`n/a`	`[string] controllerId`
	`getOrderId`	`n/a`	`[string] orderId`
	`getWorkflowName`	`n/a`	`[string] workflowName`
	`getWorkflowPath`	`n/a`	`[string] workflowPath`
	`getWorkflowPosition`	`n/a`	`[string] position`
	`getWorkflowVersionId`	`n/a`	`[string] versionId`
Outcome	`getLastFailedOutcomes`	`n/a`	`[object[]] outcomes`
	`getLastSucceededOutcomes`	`n/a`	`[object[]] outcomes`
	`getOutcome`	`n/a`	`[object] outcome`
	`getOutcome().putVariable`	`[string] name,` `[string\|int\|bool] value`	`n/a`
	`getOutcome().setReturnCode`	`[int] returnCode`	`n/a`
Utility	`getLogger().info`	`[string] message`	`n/a`
	`getLogger().warn`	`[string] message`	`n/a`
	`getLogger().error`	`[string] message`	`n/a`
	`getLogger().debug`	`[string] message`	`n/a`

Examples

The following examples are straightforward. Find further examples from JS7 - How to read arguments in JavaScript Jobs.

Example: Implementing a basic Job

A job is implemented by a class with the name JS7Job as from the below JavaScript example:

Example for implementation of JS7Job with JavaScript

class JS7Job extends js7.Job {

	processOrder(js7Step) {
		js7Step.getLogger().info( 'hello world' ); 		

		// do some stuff
    }
}

Explanation:

The implementation class with the name JS7Job is required.
The processOrder() method is required to be implemented by the job.
- The method is parameterized by the js7Step object provided by the Job API.
- The js7Step object is used with its getLogger() method to write output to the job's log.

Example: Reading specific Arguments

Example for implementation of JS7Job with JavaScript

class JS7Job extends js7.Job {
 
    processOrder(js7Step) {
        // access argument by name
        js7Step.getLogger().info('[getAllArgumentsAsNameValueMap] by name:');
        var colorBlue = js7Step.getAllArgumentsAsNameValueMap()['color_blue'];
        js7Step.getLogger().info('argument color_blue=' + colorBlue);
    }
}

Explanation:

The implementation class with the name JS7Job is required.
The processOrder() method is required to be implemented by the job.
- The method is parameterized by the js7Step object.
- The js7Step object is used with its getLogger() method to write output to the job's log.
- The getAllArgumentsAsNameValueMap() method provides a map of all arguments. The map allows to read a single argument from the argument name.

Example: Reading the list of Arguments

Example for implementation of JS7Job with JavaScript

class JS7Job extends js7.Job {
 
    processOrder(js7Step) {
        // get list of all arguments
        var args = js7Step.getAllArguments();
        js7Step.getLogger().info('[getAllArguments]:');
        js7Step.getLogger().info('all arguments: ' + args);
 
        for (var arg in args) {
            js7Step.getLogger().info('argument: ' + arg + '=' + args[arg].getValue());
        }
    }
}

Class js7.JobArgument

The js7.JobArgument class can optionally be used to access declared variables.

Users implement a class for arguments with an arbitrary name that creates objects for declared arguments.
Users instantiate the class for arguments in their JS7Job class implementation.

Constructor

Constructor	Argument	Explanation
`js7.JobArgument()`	`[string] argumentName`	Specifies the name of the argument from a string. Argument names are case-sensitive.
	`[bool] isRequired`	Optionally specifies if the argument is required. If required and the argument is not declared with the workflow and no default value is provided then an error will be raised.
	`[string\|int\|bool] defaultValue`	Optionally specifies a default value using one of the indicated data types.
	`[enum] displayMode`	Optionally specifies the `js7.DisplayMode.MASKED` enumeration value that prevents argument values from being logged.

Examples

The following examples are straightforward. Find further examples from JS7 - How to read arguments in JavaScript Jobs.

Example: Reading specific Declared Arguments

Example for implementation of js7JobArgument with JavaScript

class JobArguments {
	workflowPath = new js7.JobArgument('js7Workflow.path', true);
}

class JS7Job extends js7.Job {
	declaredArguments = new JobArguments();

	processOrder(js7Step) {
        // option 1: access declared argument
      	// option 1.a: access declared argument by name
        js7Step.getLogger().info('[GetDeclaredArgument] by name:');
      	var declaredArg1a = js7Step.getDeclaredArgument('js7Workflow.path');
		js7Step.getLogger().info('declaredArgument: ' + declaredArg1a.getName() + '=' + declaredArg1a.getValue());

      	// option 1.b: access declared argument by object name
        js7Step.getLogger().info('[GetDeclaredArgument] by object name:');
      	var declaredArg1b = js7Step.getDeclaredArgument(this.declaredArguments.workflowPath.name);
		js7Step.getLogger().info('declaredArgument: ' + declaredArg1b.getName() + '=' + declaredArg1b.getValue());

        // option 2: access declared argument value
        // option 2.a: access declared argument value by name
		js7Step.getLogger().info('[GetDeclaredArgumentValue] by name:');
		js7Step.getLogger().info(js7Step.getDeclaredArgumentValue('js7Workflow.path'));

        // option 2.b: access declared argument value by object name
		js7Step.getLogger().info('[GetDeclaredArgumentValue] by object name:');
        js7Step.getLogger().info(js7Step.getDeclaredArgumentValue(this.declaredArguments.workflowPath.name));
    }
}

Explanation:

The example suggests two ways how to access declared arguments:
- Accessing the argument object: offers to use the getName() and getValue() methods of the argument object.
- Accessing the argument value: directly returns the argument value.
Argument names can be specified by strings or by using the declaredArguments instance of the JobArgument class and the argument objects included.

Example: Reading the list of Declared Arguments

Example for implementation of js7JobArgument with JavaScript

class JobArguments {
    // arguments with string data type
	colorBlue = new js7.JobArgument('color_blue', true, 'blue');
	colorRed = new js7.JobArgument('color_red', true, 'red');
	colorOrange = new js7.JobArgument('color_orange', true, 'orange');
  
    // arguments with numeric data type
    numOfDays = new js7.JobArgument('num_of_days', true, 5);

    // arguments with Boolean data type
    isEndOfMonth = new js7.JobArgument('is_end_of_month', true, true);

    // arguments with masked output that prevents value from being logged
    password = new js7.JobArgument('password', true, 'secret', js7.DisplayMode.MASKED);
}

class JS7Job extends js7.Job {
	declaredArguments = new JobArguments();

	processOrder(js7Step) {
        // get list of all declared arguments
		var allArgs = js7Step.getAllDeclaredArguments();
		js7Step.getLogger().info('[getAllDeclaredArguments]:');
		js7Step.getLogger().info('all declared arguments: ' + allArgs);

        for (var arg in allArgs) {
			js7Step.getLogger().info('declared argument: ' + arg + '=' + allArgs[arg]);
		}
    }
}

Explanation:

The example declares a number of arguments with default values in different data types.
The getAllDeclaredArguments() method returns the list of arguments that can be iterated.

Space shortcuts

Page tree

Introduction

Argument Sources

Classes

Class js7.Job

Methods

Objects

Examples

Example: Implementing a basic Job

Example: Reading specific Arguments

Example: Reading the list of Arguments

Class js7.JobArgument

Constructor

Examples

Example: Reading specific Declared Arguments

Example: Reading the list of Declared Arguments

Further Resources

Space shortcuts

Page tree

JS7 - Job API

Introduction

Argument Sources

Classes

Class js7.Job

Methods

Objects

Examples

Example: Implementing a basic Job

Example: Reading specific Arguments

Example: Reading the list of Arguments

Class js7.JobArgument

Constructor

Examples

Example: Reading specific Declared Arguments

Example: Reading the list of Declared Arguments

Further Resources