Argument Sources

JS7 - GraalVM Python Jobs are based on Oracle® GraalVM. Job arguments 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.

Users who wish to keep things simple are invited to use access methods as explained with the next chapter Accessing Arguments. Subsequent chapters are aimed at users with a high load of possibly hundreds of arguments who require detailed information about the source of arguments.

FEATURE AVAILABILITY STARTING FROM RELEASE 2.8.2

Accessing Arguments

Download sample workflow implementing access to all arguments (upload .json): pdPythonAllArguments.workflow.json

Reading specific Arguments

The straightforward way to read the value for a specific argument works like this:

Example for implementation of JS7Job with GraalVM Python

class JS7Job(js7.Job):
    def processOrder(self, js7Step):
        # access argument by name
        js7Step.getLogger().info("[getAllArgumentsAsNameValueMap] by name:")
        color_blue = js7Step.getAllArgumentsAsNameValueMap()["color_blue"]
        js7Step.getLogger().info(f"argument color_blue={color_blue}")

Explanation:

The getAllArgumentsAsNameValueMap() method provides a map of all arguments. The map allows to read a single argument specifying the argument name.
Argument values are returned from one of the supported data types including string, number and Boolean.
Consider that argument names are case-sensitive.

Reading the list of all Arguments

To iterate the list of available arguments the following proceeding applies:

Example for implementation of JS7Job with GraalVM Python

class JS7Job(js7.Job):
    def processOrder(self, js7Step):
        logger = js7Step.getLogger()

        # Get list of all arguments
        args = js7Step.getAllArguments()

        # Converts Java JobArgument wrappers into a clean Python dict
        args_dict = {key: str(arg.getValue()) for key, arg in args.items()}

        logger.info("[getAllArguments]:")

        # Now we can log the dictionary cleanly
        logger.info(f"all arguments: {args_dict}")

        for key, arg in args.items():
            logger.info(f"argument: {key}={arg.getValue()}")

Explanation:

The example will return arguments from all sources.
The getValue() method returns a Java Object. To receive a string value, users must cast the result or use a method that enforces the string data type.
Argument values are returned in one of the supported data types including string, number and Boolean.

Accessing Arguments from Order Variables

Order Variables are carried by an order and are a subset of the Declared Variables specified by the workflow.

Order Variables have to be specified for any Declared Variables that are not assigned a default value.
Order Variables can specify Declared Variables holding default values. The Order Variable overrules the default value.

Download sample workflow implementing access to Order Variables (upload .json): pdPythonOrderVariables.workflow.json

Reading specific Order Variables

Order Variables can be accessed from their name like this:

Example for implementation of JS7Job with GraalVM Python

class JS7Job(js7.Job):
    def processOrder(self, js7Step):
        logger = js7Step.getLogger()
        
        logger.info("[getOrderArgumentsAsNameValueMap] by name:")

        # Access order argument by name
        # (i) Receives values passed as variables during order creation
        color_blue = js7Step.getOrderArgumentsAsNameValueMap()["color_blue"]
        
        logger.info(f"argument color_blue={color_blue}")

Reading the list of Order Variables

To iterate the list of Order Variables the following proceeding applies:

Example for implementation of JS7Job with GraalVM Python

class JS7Job(js7.Job):
    def processOrder(self, js7Step):
        logger = js7Step.getLogger()

        # Get list of order variables
        # (i) Receives values passed as variables during order creation
        args = js7Step.getOrderArgumentsAsNameValueMap()

        # Converts Java JobArgument wrappers into a clean Python dict
        args_dict = {key: str(arg) for key, arg in args.items()}

        logger.info("[getOrderArgumentsAsNameValueMap]:")

        # Now we can log the dictionary cleanly
        logger.info(f"all order variables: {args_dict}")

        for key, arg in args.items():
            logger.info(f"variable: {key}={arg}")

Accessing Declared Arguments

Declaration of arguments includes the following levels:

Arguments that are declared by the workflow.
Arguments that are declared by the job implementation.

Declaration of arguments with a workflow looks like this:

At workflow level any number of variables can be specified.
Specification includes the data type, most frequently using string, number, Boolean.
A default value can be provided that allows an order to optionally specify the variable with some value.

Download sample workflow implementing access to Declared Arguments (upload .json): pdPythonDeclaredArguments.workflow.json

Reading specific Declared Arguments

A job has to specify Declared Arguments by use of the js7.JobArgument class.

The argument specification can be redundant for arguments that are declared by the workflow.
The argument specification can introduce additional arguments that are not declared by the workflow. This suggests to specify a default value as otherwise an error is raised for a missing argument value.

Example for implementation of JS7Job with GraalVM Python

class JobArguments:
  def __init__(self):
      self.color_blue = js7.JobArgument("color_blue", True)

class JS7Job(js7.Job):
    def __init__(self):
        self.declaredArguments = JobArguments()

    def processOrder(self, js7Step):    
        logger = js7Step.getLogger()
        
        # option 1: access declared argument
        # option 1.a: access declared argument by name
        logger.info("[GetDeclaredArgument] by name:")
        declared_arg_1a = js7Step.getDeclaredArgument("color_blue")
        logger.info(f"declaredArgument: {declared_arg_1a.getName()}={declared_arg_1a.getValue()}")
        
        # option 1.b: access declared argument by object name
        logger.info("[GetDeclaredArgument] by object name:")
        declared_arg_1b = js7Step.getDeclaredArgument(self.declaredArguments.color_blue.name)
        logger.info(f"declaredArgument: {declared_arg_1b.getName()}={declared_arg_1b.getValue()}")
        
        # option 2: access declared argument value
        # option 2.a: access declared argument value by name
        logger.info("[GetDeclaredArgumentValue] by name:")
        logger.info(js7Step.getDeclaredArgumentValue("color_blue"))
        
        # option 2.b: access declared argument value by object name
        logger.info("[GetDeclaredArgumentValue] by object name:")
        logger.info(js7Step.getDeclaredArgumentValue(self.declaredArguments.color_blue.name))

Explanations:

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

Reading the list of Declared Arguments

Similarly to reading specific Declared Arguments the job has to specify the Declared Arguments by use of the js7.JobArgument class.

Example for implementation of JS7Job with GraalVM Python

class JobArguments:
  def __init__(self):
      # arguments with string data type
      self.color_blue = js7.JobArgument("color_blue", True, "N/A")
      self.color_red = js7.JobArgument("color_red", True, "N/A")
      self.color_orange = js7.JobArgument("color_orange", True, "N/A")
      
      # arguments with numeric data type
      num_of_days = js7.JobArgument("num_of_days", True, 0)
      
      # arguments with Boolean data type
      is_end_of_month = js7.JobArgument("is_end_of_month", True, False)
      
      # arguments with masked output that prevents value from being logged
      password = js7.JobArgument("password", True, "secret", js7.DisplayMode.MASKED)

class JS7Job(js7.Job):
    def __init__(self):
        self.declaredArguments = JobArguments()
        
    def processOrder(self, js7Step):
        logger = js7Step.getLogger()
        
        # Get list of all declared arguments
        all_args = js7Step.getAllDeclaredArguments()
        
        # Unpacks Java argument wrappers and converts values to a clean Python dictionary
        args_dict = {arg.getName(): str(arg.getValue()) for arg in all_args}
        
        logger.info("[getAllDeclaredArguments]:")
        logger.info(f"all declared arguments: {args_dict}")
        
        for arg in all_args:
            logger.info(f"declared argument: {arg.getName()}={arg.getValue()}")

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.
The getValue() method returns a Java Object. To receive a string value, users must cast the result or use a method that enforces the string data type.

Accessing Job Resource Arguments

JS7 - Job Resources hold key/value pairs that are passed as arguments to a workflow (indicating all jobs) or to a specific job.

Any number of Job Resources can be assigned a job. When accessing arguments then all assigned Job Resources are taken into account.
JS7 implements a precedence of Job Resources holding the same variable names: the variable included with the first Job Resource assigned beats variables with the same name in subsequent Job Resources.

Download sample job resource and workflow implementing access to Job Resource Arguments

Reading specific Job Resource Arguments

Job Resource Arguments can be accessed from their name like this:

Example for implementation of JS7Job with GraalVM Python

class JS7Job(js7.Job):
    def processOrder(self, js7Step):
        logger = js7Step.getLogger()

        # access argument by name
        logger.info("[getJobResourcesArgumentsAsNameDetailValueMap] by name:")
        color_blue = js7Step.getJobResourcesArgumentsAsNameDetailValueMap()["color_blue"]
        js7Step.getLogger().info(f"argument color_blue={color_blue.getValue()}")

Reading the list of Job Resource Arguments

The list of Job Resource Arguments is available for iteration like this:

Example for implementation of JS7Job with GraalVM Python

class JS7Job(js7.Job):
    def processOrder(self, js7Step):
        logger = js7Step.getLogger()
        
        # get list of Job Resource arguments
        args = js7Step.getJobResourcesArgumentsAsNameDetailValueMap()

        # Unpacks Java argument wrappers and converts values to a clean Python dictionary
        args_dict = {key: str(arg.getValue()) for key, arg in args.items()}

        logger.info("[getJobResourcesArgumentsAsNameDetailValueMap]:")
        logger.info(f"arguments: {args_dict}")

        for key, arg in args.items():
            logger.info(f"argument: {key}={arg.getValue()}")

Resources

Space shortcuts

Page tree

Argument Sources

Accessing Arguments

Reading specific Arguments

Reading the list of all Arguments

Accessing Arguments from Order Variables

Reading specific Order Variables

Reading the list of Order Variables

Accessing Declared Arguments

Reading specific Declared Arguments

Reading the list of Declared Arguments

Accessing Job Resource Arguments

Reading specific Job Resource Arguments

Reading the list of Job Resource Arguments

Resources

Space shortcuts

Page tree

JS7 - How to read arguments in GraalVM Python Jobs

Argument Sources

Accessing Arguments

Reading specific Arguments

Reading the list of all Arguments

Accessing Arguments from Order Variables

Reading specific Order Variables

Reading the list of Order Variables

Accessing Declared Arguments

Reading specific Declared Arguments

Reading the list of Declared Arguments

Accessing Job Resource Arguments

Reading specific Job Resource Arguments

Reading the list of Job Resource Arguments

Resources