Go to primary content
Oracle® Retail Process Orchestration and Monitoring Oracle® Retail Process Orchestration and Monitoring Implementation Guide
Release 19.1
F35029-04
  Go To Table Of Contents
Contents
Previous
Previous 		 Next
Next		  

3 Integration

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

Invoking Cycles in POM

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

However, the capability exists in POM for customers if they so desire to control the time and frequency of batch executions by invoking the following ReST service.

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

Accept-Version = 16.0

Authorization = Basic <Base64 Encoded Credentials>
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 
{
    "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"
}

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

Accept-Version = 16.0

Authorization = Basic <Base64 Encoded Credentials>
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.

    External Confguration 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.

    Batch Admin 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.

    Edit Job

  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-2 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.

    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.

    Click Job Name

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

  6. Provide the external job name.

    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

Accept-Version = 16.0

Authorization = Basic <Base64 Encoded Credentials>
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.

Business Date Alignment

This API provides the ability to adjust the business date of a Batch Schedule. This allows for aligning the business date with other schedules, or a customer's internal processing date.

HTTP Method POST
Path 
https://<pom-server-host>/ProcessServices/services/private/administration/utilities/alignBusinessDate
<pom-server-host> - This is the POM URL.
HTTP Headers Content-Type = application/json

Accept-Version = 16.0

Authorization = Basic <Base64 Encoded Credentials>
Request Body 
{  
  "businessDate" :"Business Date in yyyy-MM-dd format",
  "scheduleName" :"Schedule Name",
  "advanceDateOnly" :"<true|false>",
  "updateDependentSchedules" :"<true|false>",
  "comment":"<Comment>" 
}
businessDate -- Desired business date in yyyy-MM-dd format (API will determine if to move it backward or forward)

scheduleName -- Schedule name for which the business date has to be aligned

advanceDateOnly - Optional boolean flag to enforce business dates only move forward. If the business date (for the given Schedule or its dependents) has to move backwards, the request will fail. Defaults to false, if not specified.

updateDependentSchedules -- Optional boolean flag to en-force business date alignment for all Batch Schedules that are dependents of the specified Schedule.

comment - Mandatory field. Provides the reason to align business date and is mainly used for auditing purposes.
Response Body The response of this endpoint, provides a clear understanding of which Batch Schedules were adjusted, what were their previous business dates and what their current business date is. 
{
  "instances": [
      {
        "status":"<SCHEDULE_STATUS>",
        "scheduleName":"<SCHEDULE_NAME>",
        "schedulerIn-stanceId":"<SCHEDULER_DAY>",
        "businessDate":"<BUSINESS_DATE>",
        "previousBusi-nessDate":"<PREV_BUSINESS_DATE>",
        "activationTime":"<ACTIVATION_TIME>"
      }
    ]
}

instances - Array containing Schedule objects.

scheduleName - Name of the Batch Schedule adjusted.

status - Status of the Batch Schedule.

businessDate - Current business date of the Schedule

previousBusinessDate - Previous business date of the Schedule, prior to adjustment.

activationTime - The time at which the Scheduler Day with the new business date was created.

Solution Diagram

The endpoint identifies dependent Schedules mainly by using the Inter-Schedule Dependency flag that is set on the System Configuration screen in POM, at a Schedule level.

Once dependent Schedules are identified, the EJB Timers used by the POM Scheduler are cancelled (if configured and in use), prior to moving the business date of the Schedule.

The general flow of this endpoint in moving the business dates of the Schedules is depicted in the flowchart below.

Solution Diagram
  Previous
Previous 		 Next
Next
  Go To Table Of Contents
Contents