11 Invoking POM Services
This chapter lists the ReST APIs that can be invoked and the steps needed to invoke them.
All the POM APIs are protected by the Oauth standard. It allows users to securely delegate access to resources without sharing their original credentials. Oauth2 has been around since 2012 as a standard and is built on lessons from other, earlier standards, including Oauth1 and SAML.
Note:
ReST service calls from POM to external systems (customers), such as the call for External Status Update, are limited to Basic Auth at this time.Oauth Token Generation
Using the Oauth protocol is a two-step process:
-
Request an access token from an authentication provider: IDCS or OCI IAM.
-
Provide the access token as an authorization header when invoking a service.
Prerequisite
rgbu:pom:services-customer-administrator-<ENV_ID>
where <ENV_ID> represents the unique environment identifier such as PRD1, STG1, DEV1 and so on.
rgbu:pom:services-customer-administrator-DEV1
For more information about creating the OAuth client (one-time setup), refer to the "Creating IDCS OAuth 2.0 Client Apps" chapter in the Retail Home Administration Guide.
Invoke IDCS Token Endpoint
To generate a token from IDCS, the following information is needed:
-
IDCS URL
-
Client Id and Client Secret
-
OAuth Scope
The curl command below invokes an IDCS service to generate an access token:
curl -I
-H 'Authorization: Basic <base64Encoded Oauth_Clientid:Secret>'
-H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8'
--request POST <IDCS_URL>/oauth2/v1/token
-d 'grant_type=client_credentials&scope=rgbu:pom:services-customer-administrator-<ENV_ID>'
This is a standard ReST call, with the following specifics:
-
<IDCS URL>
is the IDCS URL of this instance. -
<base64Encoded OAuth_Clientid:Secret>
is the Base64-encoded OAuth Client Id and Client Secret provided as a Basic Authentication header. -
Specify the body as:
grant_type=client_credentials&scope= rgbu:pom:services-customer-administrator-<ENV_ID>
The response to this call will be in this format:
{ "access_token": "<TOKEN>", "token_type": "Bearer", "expires_in": 3600 }
Invoking the POM Service
To invoke the POM ReST service, you must add an authorization header as Bearer <token>, that is:
-
The word Bearer
-
A space
-
A valid token obtained as described above
For example, the POM nightly cycle start request would look something like the following:
curl -i
-H 'Authorization: Bearer <OAuth Token>'
-H 'Content-Type: application/json'
--request POST 'https://<pom-server-host>/ProcessServices/services/private/executionEngine/schedules/<Schedule_Name>//execution?skipVersion'
-d '{ "cycleName" : "Nightly", "flowName" : "Nightly"}'
Note:
There are POM APIs where the schedule name must be passed in the URL itself, or as part of the request payload. To get the schedule name, follow one of the following two methods:-
Login to POM UI and open the System Configuration screen from the Tasks menu. Under the Schedules tab, at the top of the desired schedule column, look at the name in parentheses. In the screenshot below for example, the schedule name to use in the API calls is RI. RI-Test is the Display Schedule Name.
-
In the Batch Schedule spreadsheet, get the schedule name from the
ScheduleName
field in the Schedule sheet. Refer to the screenshot below, for example:
Schedule Information API
These APIs provide general information regarding the Batch Schedule in POM.
View Batch Schedules
This endpoint will fetch all the Batch Schedules within POM.
HTTP Method |
GET |
||||||||||||||
Path |
|
||||||||||||||
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
||||||||||||||
Response Body |
Sample Response
|
View Batch Cycles for Schedule
This endpoint will provide a list of Batch Cycles for the given schedule.
HTTP Method |
GET |
||||||||||||||
Path |
|
||||||||||||||
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
||||||||||||||
Response Body |
Sample Response
|
Batch Execution API
Different SaaS customers operate in different models for running their batch. Some may choose to use the POM Scheduler to schedule the different entities such as Nightly, Recurring or Standalone. Refer to the POM User Guide for documentation on the POM Scheduler.
Others may choose to control the time and frequency of batch executions by invoking the provided ReST APIs. This section describes these APIs.
Execution Request Creation
POM also provides users the capability to control the time and frequency of batch executions by invoking the following ReST service.
HTTP Method |
POST |
||||||||||
Path |
|
||||||||||
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
||||||||||
Request Body |
|
||||||||||
Response Body |
|
Examples of all the Batch Entities in POM that can be invoked by the endpoint above, are shown in the table below
Invocation | Request Payload |
---|---|
Nightly Flow |
Note: The Nightly Cycle contains a single default Nightly Flow. Hence a single invocation will suffice to start the Nightly Flow. |
Hourly Flow |
Note: The Hourly Cycles comprise of many distinct Batch Flows and for each Batch Flow a separate invocation is required. |
Adhoc Flow |
Note: The Adhoc Cycle comprises of many distinct Batch Flows and for each Batch Flow a separate invocation is required. |
Adhoc Process |
In case of Adhoc Batch Processes, the parameters for Batch Jobs can be overridden by parameters specified as part of the invocation request.
Note: Adhoc Cycles are composed of many discrete individual Batch Processes. For each Batch Process, a separate invocation is required. |
Execution Request Status
The endpoint below provides the ability to check the status of an Execution Request in POM
HTTP Method |
GET |
||||||||||||||||
Path |
|
||||||||||||||||
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
||||||||||||||||
Response Body |
|
Execution Requests for Batch Cycle
The endpoint fetches all the Execution Requests for a given Schedule and given Batch Cycle
HTTP Method |
GET |
||||||||||||||||||||||||||||||||||
Path |
|
||||||||||||||||||||||||||||||||||
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
||||||||||||||||||||||||||||||||||
Response Body |
Sample Response
|
External Dependency API
This API operates solely on Batch External Dependencies.
Releasing External Dependency
The endpoint below releases an External Dependency setup in POM. Customers can call this endpoint to synchronize the execution of the Batch Schedule in POM with their other systems.
HTTP Method | POST | ||||||||
---|---|---|---|---|---|---|---|---|---|
URL |
Note: Ensure the status COMPLETED is specified in the path correctly, or the External Dependency will not be released. |
||||||||
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
||||||||
Request Body |
None |
||||||||
Response Body |
|
Utilities API
These APIs are general utilities, that have come as requirements from various Customers.
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 |
|
||||||||||||||
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
||||||||||||||
Request Body |
|
||||||||||||||
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.
|
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 and also the execution links.
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.
Custom Batch Entities API
The following endpoints are for the creation, updating, and deletion of Custom Batch Entities within POM.
Creating / Updating Custom Flows
This API provides the ability to create / update custom flows.
HTTP Method |
PUT |
Path |
|
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
Request Body |
Sample Request Body
|
Response Body |
|
Deleting Custom Flow
This API provides the ability to delete the given custom flow.
HTTP Method |
DELETE |
Path |
|
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
Request Body |
Sample Request Body
|
Response Body |
204 No content |
Fetching All Custom Flows
This API provides the ability to fetch all custom flows.
HTTP Method |
GET |
Path |
|
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
Request Body |
N/A |
Response Body |
|
Fetching a Custom Flow
This API provides the ability to fetch details of a given custom flow.
HTTP Method |
GET |
Path |
|
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
Request Body |
N/A |
Response Body |
|
Creating / Updating Custom Processes
This API provides the ability to create / update custom processes.
HTTP Method |
PUT |
Path |
|
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
Request Body |
Sample Request Body
|
Response Body |
|
Deleting Custom Process
This API provides the ability to delete the given custom process.
HTTP Method |
DELETE |
Path |
|
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
Request Body |
Sample Request Body
|
Response Body |
204 No content |
Fetching all Custom Processes
This API provides the ability to fetch all custom processes.
HTTP Method |
GET |
Path |
|
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
Request Body |
N/A |
Response Body |
|
Fetching a Custom Process
This API provides the ability to fetch details of a given custom process.
HTTP Method |
GET |
Path |
|
HTTP Headers |
Include Authorization header as shown in Oauth Token Generation |
Request Body |
N/A |
Response Body |
|