Introduction

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

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

MethodArgumentReturn Value
processOrder()[object] js7Stepn/a

Objects

ObjectPurpose
js7StepThe built-in object js7Step provides a number of methods
AreaMethodArgumentReturn Value
ArgumentgetAllArgumentsn/a[object[]] arguments

getAllArgumentsAsNameValueMapn/a[map] argumentMap

getAllDeclaredArgumentsn/a[object[]] arguments

getDeclaredArgument[string] argumentName[object] argument

getDeclaredArgumentValue[string] argumentName[string|int|bool] argumentValue

getJobResourcesArgumentsAsNameDetailValueMapn/a[map] arguments

getOrderArgumentsAsNameValueMapn/a[map] arguments
JobgetAgentIdn/a[string] agentId

getJobEnvironmentn/a[object] jobEnvironment

getJobEnvironment().getJobKeyn/a[string] jobKey

getJobEnvironment().getEncodingn/a[string] encoding

getJobEnvironment().getDeclaredArgumentsn/a[object[]] jobArguments

getJobInstructionLabeln/a[string] label

getJobNamen/a[string] jobName

getControllerIdn/a[string] controllerId

getOrderIdn/a[string] orderId

getWorkflowNamen/a[string] workflowName

getWorkflowPathn/a[string] workflowPath

getWorkflowPositionn/a[string] position

getWorkflowVersionIdn/a[string] versionId
OutcomegetLastFailedOutcomesn/a[object[]] outcomes

getLastSucceededOutcomesn/a[object[]] outcomes

getOutcomen/a

[object] outcome


getOutcome().putVariable[string] name,
[string|int|bool] value
n/a

getOutcome().setReturnCode[int] returnCoden/a
LogginggetLogger().info[string] messagen/a

getLogger().warn[string] messagen/a

getLogger().error[string] messagen/a

getLogger().debug[string] messagen/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 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 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

ConstructorArgumentExplanation
js7.JobArgument()

[string] argumentName

Specifies the name of the argument from a string. Argument names are case-sensitive.

[bool] isRequiredOptionally 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] defaultValueOptionally specifies a default value using one of the indicated data types.

[enum] displayModeOptionally 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 the following ways how to access declared arguments:
    • Accessing the argument object: offers using 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 of different data types.
  • The getAllDeclaredArguments() method returns the list of arguments for iteration.

Resources


  • No labels