1. Implementation Guide
  2. Integration

3 Integration

This chapter describes the various scenarios which involve configuring & integrating the Process Orchestration and Monitoring (POM) application to connect with external systems.

Setting Up a New Batch Schedule in POM

When POM is first installed for a specific customer, it does not include any application batch schedules out of the box such as Merchandising or Retail Intelligence, and so on. An Oracle administrator or a system integrator need to first configure those schedules before they get loaded with the scheduling data. Configuring a new schedule entails setting up schedule properties such as the schedule name and description, and customer environment information for callbacks. It also entails setting up the location of different components and services with which different POM components need to interact to function properly.

Refer to the section "Configure New Schedule" in the "System Configuration" section of the POM User Guide.

Invoking Cycles in POM

Different SaaS customers operate in different models for running batch.

For some, the Oracle support team configures the time and frequency for running the batch cycles in POM on their behalf, based on their requirement.

Others may choose to use the Scheduler feature of the product. Refer to the POM User Guide for documentation on the Scheduler.

For others, the capability exists for them to control the time and frequency of batch executions by invoking the following ReST service.

Some may use a hybrid of all or some of the above methods.

Note:

All POM endpoints are protected by the OAuth authorization protocol. To invoke an endpoint in POM, a customer application must use an Access Token that was generated using the OAuth Client Credentials Grant. Refer to Invoking POM Services Using OAuth in this guide for further details.

Execution Request Creation

The specification of the ReST service to start the POM cycle execution is shown below:

HTTP Method POST

Path

http://<pom-server-host>/ProcessServices/services/private/executionEngine/schedules/<Schedule_Name>/execution

Note: <pom-server-host> and <Schedule_Name> variables need to be changed according to the target environment and schedule.

HTTP Headers

Content-Type = application/json

Authorization = Bearer <<OAuth_Token_FROM_IDCS_or_OCI_IAM>>

Request Body

 
{
   "cycleName": "<Cycle Name>",
   "flowName": "<Flow Name>",
   "processName": "<Process Name>",
   "requestParameters":"<Comma Separated Key Value Pairs>"
}

Notes:

  • processName attribute required only for Ad hoc cycles

  • requestParameters attribute is optional. This is useful if external systems would like to provide custom identifiers to POM and expect them to be returned on callbacks sent from POM.

Response Body

 
{
    "value": "171" -Execution Request ID,
    "cycleName": "CycleName",
    "flowName": "FlowName",
    "processName": "ProcessName",
    "jobName": "JobName",
    "requestType": "requestType",
    "requestParameters": ":"<Comma Separated Key Value Pairs>"
    "executionEngineInfo": "STARTED",
    "hyperMediaContent": {}
}
Invocation Request Payload

Nightly Cycle invocation

 
{
    "cycleName" : "Nightly",
    "flowName" : "Nightly",
    "requestParameters" : "callerId=XXX,correlationId=123"
}

Note: The Nightly Cycle contains a single flow hence a single invocation will suffice to start the Nightly Flow.

Hourly Cycle invocation

 
{
    "cycleName" : "Hourly_Cycle_<N>",
    "flowName" : "<FLOW_NAME>",
    "requestParameters" : "callerId=XXX,correlationId=456"
}

<N> is the cycle number (1 to 24)

<FLOW_NAME> is name of the flow (Process Group) to invoke. For example, SALESPROCESS_CYCLE. 

{
     "cycleName" : "Hourly_Cycle_1",
     "flowName" : "SALESPROCESS_CYCLE",
     "requestParameters":"callerId=Sys_Name,correlationId=456" 
}

Note: The Hourly Cycles comprise of many distinct flows and for each flow a separate invocation would be required.

Ad hoc Cycle invocation

In case of Adhoc processes, the parameters for Jobs can be overridden by parameters specified as part of the invocation request.

 
{
    "cycleName" : "Adhoc",
    "flowName" : "Adhoc",
    "processName" : "<ADHOC_PROCESS_NAME>",
    "requestParameters" : "callerId=xxx,correlationId=789"
}

Example:

{
    "cycleName": "Adhoc",
    "flowName":"Adhoc",
    "processName":"RPM_NEW_ITEM_LOCATION_PROCESS _ADHOC",
    "requestParameters":"callerId=Ext_System_Name, correlationId= 789"
}

Example with overriding job parameters:

{
    "cycleName": "Adhoc",
    "flowName":"Adhoc",
    "processName":"RPM_NEW_ITEM_LOCATION_PROCESS _ADHOC",
    "requestParameters":"callerId=Ext_System_Name, correlationId=789,jobParams.RPM_NEW_ITEM_JOB=param1|param2"
}

Note: Ad hoc Cycles are composed of many discrete individual Processes. For each Process, a separate invocation is required.

Execution Request Status Tracking

The following endpoints provide the ability to check the status of an execution request in POM:

HTTP Method GET

Path

http://<pom-server-host>/ProcessServices/services/private/executionEngine/schedules/<scheduleName>/requests/{executionId}

Note: Replace <pom-server-host> according to the target environment.

<scheduleName>: Name of the schedule. For MOM apps, the schedule name is "MERCH". For RDE, the schedule name is "RDE".

<executionId>: ID of the execution request returned by POM when execution request was submitted.

HTTP Headers

Content-Type = application/json

Authorization = Bearer <<OAuth_Token_FROM_IDCS_or_OCI_IAM>>

Response Body

  • executionId - ID of the execution request

  • scheduleName - Name of the schedule for which this execution request was created.

    Sample values: MERCH, RDE, and so on.

  • cycleName - Name of the Cycle for which this execution request was created.

    Sample values: Nightly, Hourly, or Adhoc.

  • flowName - Name of the Flow for which the execution request was created

    Sample Values:

    For Ad hoc Cycle: Adhoc

    For Nightly Cycle: Nightly

    For Hourly Cycle: Name of the flow such as DEAL_PURGE_CYCLE, and so on.

  • processName - Name of the Process for which the execution request was created.

    Sample Values:

    For Ad hoc: Name of the process such as POINDBATCH_PROCESS_ADHOC, and so on.

    For Nightly/Hourly: Always set to "ALL".

  • requestParameters - Parameters associated with the execution request.

  • status - Status of the execution request.

  • Possible Values:

  • QUEUED: Request is queued up for execution.

  • RUNNING: Jobs from this request are being executed

  • ERROR: One of the job in this request has failed. Note that a failed job would be restarted by POM Admin; there is no need to re-submit the execution request.

  • COMPLETED: All jobs from this request were executed successfully.

External Status Update

The External Status Update feature provides the ability for external systems to register with POM to receive the Job status notifications as a callback to their ReST interface.

Figure 3-1 External Dependency


External Dependency

Schedule Configuration

This section details the steps to configure the External Status Updates feature at the schedule level:

  1. Navigate to the System Configuration screen.

  2. Click the Edit icon on the External Configuration Panel to open the External Configuration window.

    Figure 3-2 External Configuration Window


    External Configuration Window

  3. Enter the configuration values:

    • External Status URL - External system's URL that needs to be called for status updates.

      Note:

      In addition to this configuration, you must work with Oracle support to get the External Status URL allowlist.

    • External Status Update Mode - Choose one of the options below:

      • ALL - POM will send a status update to the external system for each job's execution in the schedule regardless of success or failure.

      • FAILED - POM will notify only for failed jobs.

      • NONE - No status updates will be sent by POM.

      Note:

      The External Status Update Mode defined on this screen applies to all the jobs in a schedule. If status update is desired only for specific jobs then set the mode on the above screen to NONE and follow the steps defined in the Job Configuration section below.

    • Click Update Credentials and provide the credentials for the external system.

Job Configuration

This section describes the steps to configure the External Status Update Mode at job level.

  1. Navigate to the Batch Administration screen and select the schedule to update with the external status.

    Figure 3-3 Batch Administration Screen


    Batch Administration Screen

  2. Select one of the Cycle - Nightly/Recurring/Standalone

  3. Select the Process/Job combination and click Edit from table action menu to open the popup below.

    Figure 3-4 Edit Job Dialog


    Edit Job Dialog

  4. Set the External Status Update Mode one of the following values:

    • ALL - POM will send a status update to the external system for each job's execution regardless of success or failure.

    • FAILED - POM will notify only for when this job fails.

    • NONE - No status update will be sent by POM for this job.

Payload Specification

Attribute Description

processName

Name of the root process in a given cycle/flow

Note: Process names in the callback response are prefixed with the name of the schedule. For instance, a callback response sent for Process "P1" would have processName attribute as MERCH_P1 on return.

processExecutionId

Unique identifier generated by POM to track the process executions.

activityName

Name of the job for which the callback/status update is sent.

activityExecutionId

Unique identifier generated by POM to track the job run instance.

callerId

Identifier provided by the caller to POM when submitting the invocation/execution request. POM returns the same ID back to caller.

correlationId

Identifier provided by the caller to POM when submitting the invocation/execution request. POM returns the same ID back to caller

callBackServiceDataDetail.<KeyName>

Key value pairs supplied to POM when submitting the invocation/execution request. Those are returned back to the caller

failedActivity

In the case where the callback is for a failed job, this field is populated with the details of the failed Job.

status

Status of the job execution -

  • COMPLETED

  • SKIPPED

  • ERROR

  • SKIPPED_ON_ERROR

activityStatus

Status of the job, and the derived activity state:

  • ERROR - ACTIVITY_FAILED

  • COMPLETED - ACTIVITY_COMPLETED

  • SKIPPED - ACTIVITY_COMPLETED

  • SKIPPED_ON_ERROR - ACTIVITY_COMPLETED

Payload Examples

Below are sample external status update payloads for the MERCH schedule.

Description Payload

Hourly Job Callback

 
{
   " callerId " : "XXX",
   " correlationId " : "37",
   " processName " : "MERCH_ BATCH_PROCESS _01",
   " processExecutionId " : "MERCH_ BATCH_PROCESS_01 ~asfasfdasdfas",
   " activityName " : " MERCH_ BATCH_JOB",
   " activityExecutionId " : "123456",
   " status " : "COMPLETED",
   " activityStatus " : "ACTIVITY_COMPLETED",
   " failedActivity " : null
}

Nightly Job Callback

 
{
   " callerId " : "XXX",
   " correlationId " : "37",
   " processName " : "MERCH_ START_NIGHT_BATCH_PROCESS ",
   " processExecutionId " : "MERCH_ START_NIGHT_BATCH_PROCESS ~asfasfdasdfas",
   " activityName " : " MERCH_ START_NIGHT_BATCH_JOB",
   " activityExecutionId " : "123456",
   " status " : "COMPLETED",
   " activityStatus " : "ACTIVITY_COMPLETED",
   " failedActivity " : null
}

External Dependency

This feature allows customers to control the execution of a schedule running in POM by defining custom pre-dependencies. POM pauses the schedule execution on encountering these external pre-dependences and resumes the execution once they are released by customer.

Figure 3-5 External Dependency


External Dependency

Configuration

This section details the steps involved in setting up the external dependency.

  1. Navigate to the Batch Administration screen and select the schedule to which the external dependency will be added.

    Figure 3-6 Batch Administration Screen


    Batch Administration Screen

  2. Select a Cycle - Nightly/Recurring/Standalone.

  3. Find the Process/Job combination to which dependency needs to be added.

  4. Click on the Job name to open the Batch Job Details panel.

    Figure 3-7 Batch Job Details


    Batch Job Details

  5. On the External Dependency section of the screen, click the Add button to create the external dependency.

  6. Provide the external job name.

    Figure 3-8 Add External Dependency


    Add External Dependency

  7. Click Ok to save and exit or Ok and add another to create another dependency.

Releasing Dependency

External systems need to invoke the following POM ReST service to release/fulfill the external dependencies.

HTTP Method POST

URL

http://<pom-server-host>/ProcessServices/services/private/schedules/<Schedule_Name>/external/jobs/<Ext_Dependendy_Name>/status/COMPLETED

Note: <pom-server-host>, <Schedule_Name> and <Ext_Dependendy_Name> variables need to be changed according to the target environment and schedule.

HTTP Headers

Content-Type = application/json

Authorization = Bearer <<OAuth_Token_FROM_IDCS_or_OCI_IAM>>

Request Body

None

Response Body

 
{
   "value": "true",
   "links": [],
   "hyperMediaContent" : {  "linkRDO": []}
}

The true/false in the value attribute shown above indicates the success/failure of releasing the external dependency respectively.