Skip to content

Creating and Running Orders Automatically (On‐demand Production)

Jump to bottom
Thomas Bassler edited this page Mar 6, 2024 · 9 revisions

Creating and Running Orders Automatically (On-demand Production)

This page describes how to create orders automatically using the prosEO native API. For the creation of on-demand processing orders via the ESA-defined On-demand Production Service Interface Point (ODPRIP) interface please see the separate reference page.

Create and Update a Processing Order

Starting from the sample test data provided for the prosEO Test Mission (PTM), an order to process level 1 (L1) and level 2 (L2) output products from level 0 (L0) input products shall be generated. We assume that the L0 products are annotated with a revision parameter, and the processing shall be based on revision 1. The L1 and L2 output products will receive revision 99 (to denote test output, since we are not yet quite sure of the quality of the algorithm). Also, since the scenario assumes a test situation, we will create the output products with a TEST file class.

Requesting orbit-wise output products for orbits 3000-3002 will result in the following JSON order structure, which we can pass on as request data to the order creation POST request:

{
    "missionCode": "PTM",
    "identifier": "L2_orbits_3000-3002",
    "orderState": "INITIAL",
    "slicingType": "ORBIT",
    "sliceOverlap": 0,
    "filterConditions": [
        {
            "key": "revision",
            "parameterType": "INTEGER",
            "parameterValue": "1"
        }
    ],
    "outputParameters": [
        {
            "key": "revision",
            "parameterType": "INTEGER",
            "parameterValue": "99"
        }
    ],
    "configuredProcessors": [ "PTML2_0.1.0_OPER_2020-03-25" ],
    "orbits": [
        { "spacecraftCode": "PTS", "orbitNumberFrom": 3000, "orbitNumberTo": 3002 }
    ],
    "requestedProductClasses": [ "PTM_L2A", "PTM_L2B" ],
    "inputProductClasses": [],
    "outputFileClass": "TEST",
    "processingMode": "OPER"
}

Note that we did not mention the L1 products at all in this order specification. prosEO will detect that the L1 products required as input products for L2 output are missing, but since (as per the test data specifications) it knows how to process them from the available L0 products, it will create the necessary job steps for the intermediate L1 products automatically (assigning them a revision number of 99 as per the outputParameters defined in the request).

These are the most relevant order parameters, which can be set during order creation (for more details see the Order Manager REST API reference documentation):

  • missionCode: The code of the mission to create the order for,
  • identifier: User-defined order identifier,
  • priority: Priority of the ProcessingOrder (lower number means lower priority; optional, default value is 50),
  • orderState: State of the processing order, must be INITIAL for order creation,
  • executionTime: Earliest allowed execution time (for deferred order scheduling; optional),
  • orbits: List of (non-consecutive) orbit ranges (mandatory, but may be empty), each orbit range being defined as:
    • spacecraftCode: The code of the spacecraft,
    • orbitNumberFrom: Lowest orbit number to include in the processing,
    • orbitNumberTo: Highest orbit number to include in the processing,
  • startTime/stopTime: The start and end time of the time interval to process (mandatory unless an orbit range is given),
  • slicingType: Method to be used to cut the processing time interval into individual output products (one of ORBIT, CALENDAR_DAY, CALENDAR_MONTH, CALENDAR_YEAR, TIME_SLICE [fixed length], NONE [do not slice the time interval into multiple output products]),
  • sliceDuration: Duration of a slice in seconds (only for slicingType TIME_SLICE),
  • sliceOverlap: Overlap between adjacent slices in seconds (applicable for all slicingTypes except NONE, default 0),
  • inputFilters: Filter conditions to apply to input products (per product class):
    • productClass: The product class the input filters apply to,
    • filterConditions: Filter conditions to apply to input products of the given product class, each specified as:
      • key: The parameter or attribute name to check,
      • parameterType: The type of the parameter (one of STRING, INTEGER, BOOLEAN, DOUBLE, INSTANT),
      • paramterValue: The value to filter by (only equality test is available),
  • outputParameters: Parameters to set for the generated products (may be empty), each specified as:
    • key: The name of the parameter name to set,
    • parameterType: The type of the parameter (one of STRING, INTEGER, BOOLEAN, DOUBLE, INSTANT),
    • paramterValue: The value to set,
  • classOutputParameters: Set of parameters to apply to a generated product of the referenced product class replacing the general output parameters:
    • productClass: The output product class to apply the parameters to,
    • outputParameters: Set of parameters to apply to the generated products (may be empty), each specified as above,
  • configuredProcessors: List of identifiers of the configured processors to use (if empty, prosEO will select a suitable configured processor automatically)
  • requestedProductClasses: List of product types (as configured in prosEO) requested as output from the order (at least one is required),
  • inputProductClasses: List of internal product types provided as input to the order (no job steps will be generated for missing input products of these classes; may be empty)
  • outputFileClass: The file class for the generated output products (from the set defined for the mission),
  • processingMode: The processing mode to run the processor(s) in (from the set defined for the mission),
  • notificationEndpoint: The endpoint to send order completion notifications to, consisting of:
    • uri: The URI used to notify the ProcessingOrder originator of the order completion (http(s) and mailto protocols allowed),
    • username: The username to authenticate with (using Basic Authentication; optional)
    • password: The password to authenticate with (CAUTION: clear text; mandatory if username is given)

To create the processing order the JSON-formatted order data is sent to the Order Manager endpoint at

POST https://<proseEO brain host>:<Order Manager port>/proseo/order-mgr/v1/orders

This will return the order data as received, but with addition of an order database ID, an object version and an order UUID.

As long as the processing order is in state initial, it can be changed by sending the updated order data to

PATCH https://<proseEO brain host>:<Order Manager port>/proseo/order-mgr/v1/orders/<order database ID>

Note that all requests to the Order Manager require Basic Authentication with a valid mission code, user name and password (e. g. for the proseo user in the PTM mission the Base64-encoded string PTM-proseo:passwd456).

Approve, Plan and Release a Processing Order

Processing orders submitted via the Order Manager API are subject to the same order life cycle operations as orders entered manually from the GUI or the CLI.

Therefore a new processing order must be approved at the endpoint

PATCH https://<proseEO brain host>:<Order Manager port>/proseo/order-mgr/v1/orders/<order database ID>

by passing the order data with the new state APPROVED.

It can then be planned for execution at a specific processing facility using the Production Planner endpoint at

PUT https://<proseEO brain host>:<Production Planner port>/proseo/planner/v1/orders/plan/<order database ID>?facility=<facility name>

If the additional query parameter wait is set to true, the execution will by synchronously (i. e. the Production Planner will only return once the planning process is completed and the order is in state PLANNED), otherwise the Production Planner will return immediately, setting the processing order to state PLANNING.

After the completion of the planning process (and possibly visual inspection of the planning result) the processing order can be released for execution:

PATCH https://<proseEO brain host>:<Production Planner port>/proseo/planner/v1/orders/release/<order database ID>

Adding the query parameter wait as true will again run the request synchronously, and the Production Planner will return once the order has reached the RELEASED state. Otherwise the Production Planner returns immediately and sets the order to state RELEASING.

Check the Processing Order Status

TODO

Close a Completed or Failed Processing Order

TODO

Delete a Processing Order

TODO

Reference Information

Tutorials

Clone this wiki locally