JS7 JobScheduler

Space shortcuts

Page tree

Versions Compared

Old Version 1

changes.mady.by.user Andreas Püschel

Saved on

compared with

New Version Current

changes.mady.by.user Andreas Püschel

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The JITL OrderStateTransitionJob template can be used to move orders from a source state to a target state, for exampleperform transitions on orders, see JS7 - Order State Transitions. Examples for state transitions include to

  • continue orders from the FAILED state to the IN PROGRESS state and possibly to the RUNNING state in case of a JS7 - Job Instruction,
  • continue orders from the move orders from the FAILED or SUSPENDED state to the IN PROGRESS state they had before being suspended.
  • move continue orders from the PROMPTING state to the IN PROGRESS state and possibly to the RUNNING state.

The job template makes use of

...

the JS7 - REST Web Service API to perform JS7 - Order State Transitions.

Usage

When defining the job either:

  • invoke the Job Wizard that is available from the job properties tab in the Configuration view and select the JITL OrderStateTransitionJob and relevant arguments from the Job Wizard.

or

  • specify the JITL job class andcom.sos.jitl.jobs.orderstatustransition.OrderStateTransitionJob Java class name and add arguments specifying what order states to transition..

...

Download (upload .json): pdwCheckHistorypwdOrderStateTransitionJob.workflow.json

You can use the job wizard Job Wizard like this:
Image Removed

Explanation:

  • Add an empty job from the instruction panel.
  • Specify a name and a label for the job.
  • Select an Agent.

In a next step invoke the job wizard Job Wizard that you find in the upper right corner of the job property editor. The wizard Job Wizard brings up the following popup window:

Image RemovedImage Added


Explanation:

  • From the list of available job templates Job Templates select the CheckHistoryJob OrderStateTransitionJob.

Then hit the Next button to make the job wizard Job Wizard display available arguments:


Image RemovedImage Added


Explanation:

  • Required Arguments
    • query states : Specifies the expression that is used to query the execution history, for example isCompleted, isCompletedSuccessful, for the full list see Queries.
    • One or both of the following arguments are specified:
      • workflow: Specifies the name of a workflow for which the execution history is looked up. 
      • job: Specifies the name of a job for which the execution history is looked up.
      • If both arguments are specified then the job name is looked up in matching workflow names only.
      • Search for workflows and jobs is case-insensitive.
      • Wildcards can be used for both arguments, for example, accounting*, *account*.
        • * : matches zero or more characters
        • ? : matches any single character
    Optional Arguments
    • semicolon separated list of states on which the transition will be applied for example failed;scheduled
    • transition: Specifies the transition to be performed. Possible values are one of cancel, suspend, continue
    • Optional Arguments
      • workflow_folders:  Optionally the identifier of a Controller can be specified to limit results to workflows and jobs executed with the indicated Controller.
      • workflow_search_patterns:  Optionally the identifier of a Controller can be specified to limit results to workflows and jobs executed with the indicated Controller.
      • order_search_patterns:  Optionally the identifier of a Controller can be specified to limit results to workflows and jobs executed with the indicated Controller.
      • persist_duration:  Optionally the identifier of a Controller can be specified to limit results to workflows and jobs executed with the indicated Controller.
      • controller_id:  Optionally the identifier of a Controller can be specified to limit results to
      workflows and jobs executed
      • orders processed with the indicated Controller.
      • batch_size: Optionally limit the size of REST API requests.
  • Note that the the check box checkbox provided with each argument has to be selected to add the argument is to be added to the arguments of the CheckHistoryJob the OrderStateTransitionJob template.

When hitting the Submit button, the wizard adds the required selected arguments to the job which should can look like this:

Image RemovedImage Added

The job arguments can be specified:

...

Queries determine

  • the history status of orders or jobs:
    • completed: the order or job completed successfully or failed.
    • completed successful
    • completed failed
  • the period for which the execution history is looked up for orders and jobs that
    • started between two dates
    • completed between two dates
    • with periods being specified as absolute or relative dates

Syntax

Queries are specified from a function and optional arguments.

...

Functions

...

  • Scope: specifies that the workflow or job started without consideration if it completed or is still running.
  • Default Period: start on the same day.

...

  • Scope: specifies that the workflow or job completed without consideration of success of failure.
  • Arguments: if the argument startedFrom is specified, then the default value of the startedTo argument is 0d.
  • Default Period: start and completion on the same day.

...

  • Scope: specifies that the workflow or job completed successfully.
  • Arguments: if the argument startedFrom is specified, then the default value of the startedTo argument is 0d.
  • Default Period: start and completion on the same day.

...

  • Scope: specifies that the workflow or job failed.
  • Arguments: if the argument startedFrom is specified, then the default value of the startedTo argument is 0d.
  • Default Period: start and completion on the same day.

...

  • Scope: specifies that the last run of the job completed successfully.
  • Arguments: if the argument startedFrom is specified, then the default value of the startedTo argument is 0d.
  • Default Period: start and completion on the same day.

...

  • Scope: specifies that the last run of the workflow or job failed.
  • Arguments: if the argument startedFrom is specified, then the default value of the startedTo argument is 0d.
  • Default Period: start and completion on the same day.

Documentation

The Job Documentation including the full list of arguments can be found from: https://www.sos-berlin.com/doc/JS7-JITL/OrderStateTransitionJob.xml

Authentication

The Job makes use of the JS7 - REST Web Service API that is available from JOC Cockpit. 

  • The job is executed with an Agent and requires a network connection to JOC Cockpit.
  • The job has to authenticate with JOC Cockpit, for the related configuration see JS7 - JITL Common Authentication.

Anchor
arguments
arguments
Arguments

The OrderStateTransitionJob template accepts the following arguments:

NameRequiredDefault ValuePurpose
statesyesn/a

Possible values: pending, scheduled, failed, suspended, waiting, inprogress, prompting. Values can be specified in uppercase, lowercase or mixed letters.

Values can be specified from a semicolon separated list. Each state in the list is handled separately, for example

  • the transition continue for prompting orders will move orders to the IN PROGRESS and possibly to the RUNNING state,
  • the same transition for suspended orders will put orders to the state they had before being suspended.

Example: failed;suspended

transition

yesn/a

Possible values are one of:

  • cancel: execute cancel operation on related orders
  • continue: execute resume operation on failed and suspended orders. Execute confirm operation on prompting orders.
  • suspend: execute suspend operation on orders that are not failed, not finished and not suspended.
workflow_foldersno/*A list of folders that hold workflows for which orders should be transitioned.

If more than one folder is specified then folders are separated by semicolon. When used with the trailing characters /* then the folder will be looked up recursively. By default all folders will be looked up recursively.

Example: /folder/sub1;/another_folder/sub2/*

workflow_search_patternsnon/a

A list of search patterns for names of workflow for which orders should be transitioned. The wildcard characters * (zero or more characters) and ? (a single character) can be used. If more than one search pattern is used then they are separated by semicolon.

Example: *myWorkflow*;my?orkflow

order_search_patternsno/n/a

A list of search patterns for order names. If more than one search pattern is used then they are separated by semicolon.

Examples: *myWorkflow*;/folder/sub1/my?orkflow

persist_durationnon/a

This argument is available for FAILED orders. It specifies the minimum duration for which the order is in the failed state.

  • A format for the duration relative to the current time, e.g. 6h, 12h, 1d, 1w that specifies the quantity followed by a qualifier.
  • Example:  
      • 2d
  • Possible qualifiers are:
    • s (seconds)
    • m (minutes)
    • h (hours)
    • d (days)
    • w (weeks)
    • M (months)
    • y (years)
controller_idnoCurrent Controller ID

Arguments

...

Absolute Dates

Absolute date can be specified as values to the startedFrom, startedTo, completedFrom and completedTo arguments.

Dates are specified in ISO-8601 format like this:

  • 2021-12-05
    • The date is specified as yyyy-MM-dd
    • The time is assumed to be midnight UTC time.
  • 2021-12-05T01:30:15
    • The date and time are separated by the T character.
    • The time is specified as hh:mm:ss.
    • The time zone is assumed to be UTC.
  • 2021-12-05T01:00:00+02:00
    • In addition to date and time the time zone offset is specified. A + character specifies a positive offset to UTC time, a - character specifies a negative offset.

Relative Dates

Relative dates can be specified as values to the startedFrom, startedTo, completedFrom and completedTo arguments.

Relative dates are specified like this:

  • -1s, -2s
    • one second ago, two seconds ago
  • -1m, -2m
    • one minute ago, two minutes ago
  • -1h, -2h
    • one hour ago, two hours ago
  • -1d, -2d
    • one day ago, two days ago
  • -1w, -2w
    • one week ago, two weeks ago
  • -1M, -2M
    • one month ago, two months ago
  • -1y, -2y
    • one year ago, two years ago

Examples

...

Documentation

The Job Documentation including the full list of arguments can be found from: https://www.sos-berlin.com/doc/JS7-JITL/CheckHistoryJob.xml

...

n/a results to workflows and jobs executed with
NameRequiredDefault ValuePurpose
queryyesn/a

Specifies the expression that is used to look up the execution history, for example isCompleted, isCompletedSuccessful etc., for the full list see Queries.

workflow

non/a

Specifies the name of a workflow for which the execution history is looked up. A workflow name or job name has to be specified.

jobnon/aSpecifies the name of a job for which the execution history is looked up. A workflow name or job name has to be specified.
controller_idnoThe identifier of a Controller can be specified to limit the resulting list of orders to the indicated Controller.

...

batch_

...

size

...

Returns the Boolean result of the query.
Note: The query result is similarly returned with the returnCode return variable and the values 0=true, 1=false.

...

js7CheckHistoryResultControllerId

...

Returns the Controller ID of the resulting history entry.

The value of the return variable is empty if the query returns no result. If the query returns a result then the return variable holds the Controller ID of the youngest resulting history entry.

...

Returns the workflow name of the resulting history entry.

The value of the return variable is empty if the query returns no result.
If the query returns a result then the return variable holds the workflow name of the youngest resulting history entry.

...

Returns the job name of the resulting history entry.

The value of the return variable is empty if the query returns no result.
If the query returns a result then the return variable holds the job name of the youngest resulting history entry.

...

Returns the start date and time of the resulting history entry.

The value of the return variable is empty if the query returns no result. If the query returns a result then the return variable holds the start date and time of the youngest resulting history entry in ISO-8601 format.

...

Returns the completion date and time of the resulting history entry.

The value of the return variable is empty if the query returns no result. If the query returns a result then the return variable contains the completion date and time of the youngest resulting history entry in ISO-8601 format.

...

Returns the value of the query argument.

Returns a copy of the value of the query argument that was used with the query.

...

js7CheckHistoryQueryControllerId

...

Returns the value of the controller_id argument.

Returns a copy of the value of the controller_id argument that was used with the query.

...

Returns the value of the workflow argument.

Returns a copy of the value of the workflow argument that was used with the query.

...

Returns the value of the job argument.

Returns a copy of the value of the job argument that was used with the query.

...

Job Dependencies

The CheckHistoryJob template can be used to implement backward job dependencies:

  • Jobs based on the CheckHistoryJob template do not fail if the underlying query does not return results.
  • Instead, the CheckHistoryJob template provides Return Variables that can be inspected to determine further execution of jobs in a workflow.
  • JS7 offers the JS7 - If Instruction to check the values of Return Variables and to decide what instructions to execute next.

...

Image Removed

Explanation:

...

no10000

The maximum number of orders that are processed in a single request.

Orders are transitioned in a single transaction. This includes that either all orders in a transaction are transitioned or none. If the number of orders exceeds the batch size then a further transaction is executed.

If the value 1 is used for the batch_size then each order is transitioned individually with a successful or failed result.

The batch size should not exceed a value of approx. 15000 in order to limit the size of requests to the Controller to approx. 4 MB which is a frequently applied limit of Proxy Servers that might be in place between the Agent running the job and JOC Cockpit.

Return Variables

The OrderStateTransitionJob template does not return variables:

...

Image Removed

Explanation:

...

  • the value 0 if the query of the CheckHistoryJob template returns one or more hits.
  • the value 1 if the query of the CheckHistoryJob template returns no hits.
  • Alternative solutions include to check the value of the $js7CheckHistoryResult return variable for a Boolean value that indicates if the query did return any hits:
    • $js7CheckHistoryResult == true
    • $js7CheckHistoryResult == false

...

Further Resources

...