4 Integration with External Applications
BDI is an integration infrastructure product which integrates Oracle Retail applications and third-party applications. BDI Bulk Data Export Service is designed to address the complexities for third party integration with Oracle Retail application. In BDI, bulk data movement happens between sender and receiver application.
Bulk Data Export Service
Bulk Data Export Service is a new Restful Web service packaged under Job Admin, which allows authenticated user to get latest available data sets (either FULL or PARTIAL), fetch data for available data set ids and update status of transaction.
Below are the endpoints provided by Bulk Data Export Service. Ensure to invoke endpoints in below order to export data successfully.
Table 4-1 Bulk Data Export Service
| REST Resource | HTTP Method | Description |
|---|---|---|
|
j9/bulk-data/export/data-set/{interfcace_module}?consumingAppName={consumingAppName}&sourceAppName=rms |
GET |
Gets latest available FULL or PARTIAL dataset for given interface module |
|
/bulk-data/export/begin?dataSetId={dataset_id}&consumingAppName={ consumingAppName } |
POST |
Generates transaction id for given unprocessed transaction id. |
|
/bulk-data/export/data?transactionId={transaction_id} &page={pageNum}&maxRowsPerPage={maxRowsPerPage} |
GET |
Gets data from inbound tables for provided transaction id. |
|
/bulk-data/export/begin?dataSetId=15&consumingAppName=external |
POST |
Updates transaction status as SUCCESS/FAILURE based on input provided. |
Endpoints
Ping
This endpoint can be used to ensure that initial handshake with service is successful.
HTTP Method: GET
Path
resources/bulk-data/export/ping
Produces:
MediaType.APPLICATION_JSON/MediaType.APPLICATION_XML
Sample request:
<hostname>:<port>/<app_name>-batch-job-admin/resources/bulk-data/export/ping
Sample json response:
{
"returnCode": "PING_SUCCESSFUL",
"messageDetail": "Pinged Bulk Data Export Service successfully"
}getAllAvailableFullOrPartialDataSet
This endpoint can be used to get latest available data set. Data sets of type FULL are given priority over datasets of type PARTIAL. If there are no available datasets of type FULL, then this endpoint checks for data sets of type PARTIAL. If there are multiple PARTIAL data sets for given input, then data sets are sorted based on data set ready time before returning to consumer.
Path parameter consumingAppName and query parameter sourceAppName are not case sensitive.
Path parameter interfaceModule is case sensitive. Ensure to maintain appropriate case for interface module in request.
HTTP Method: GET
Path
resources/bulk-data/export/data-set/{interfaceModule is mandatory}?consumingAppName={consuming app name is mandatory}&sourceAppName={sourceAppName is optional}
interfaceModule : This field indicates name of interface module for which latest available data set is to be returned.
consumingAppName : This field indicates requesting system name.
sourceAppName : This field indicates source system name of data set.
Note:
interfaceModule and consumingAppName are mandatory inputs.
Produces
MediaType.APPLICATION_JSON/MediaType.APPLICATION_XML
Sample request
<hostname>:<port>/<app_name>-batch-job-admin/resources/bulk-data/export/data-set/Diff_Fnd?consumingAppName=external&sourceAppName=RMS
Sample json response
{
"Message": {
"returnCode": "DATA_SET_AVAILABLE",
"messageDetail": "data set is available for external"
},
"interfaceModule": "Diff_Fnd",
"dataSetType": "FULL",
"sourceSystemName": "RMS",
"consumingAppName": "external",
"AvailableDataSets": {"AvailableDataSet": [ {
"dataSetId": 10,
"dataSetReadyTime": "2020-03-06T02:21:25-08:00",
"InterfaceDetail": [
{
"interfaceShortName": "DIFF_GRP_DTL",
"interfaceDataCount": 100
},
{
"interfaceShortName": "DIFF_GRP",
"interfaceDataCount": 200
}
]
}]}
}Error Response
Response when latest data is not available
{"Message": {
"returnCode": "NO_AVAILABLE_DATA_SET",
"messageDetail": "No data set is available for external"
}}beginExport
This endpoint is used to indicate start of data export. If provided query parameters are valid, then this endpoint generates a transaction id indicating start of transaction, which is required to get data.
If there are multiple datasets (of type PARTIAL) returned by getAllAvailableFullOrPartialDataSet endpoint, ensure to process them in the same order.
HTTP Method: POST
Path
resources/bulk-data/export/begin?dataSetId={dataSetId is mandatory}&consumingAppName={consuming app name is mandatory}
dataSetId: This field indicates the dataset id that is to be exported.
consumingAppName: This field indicates the consuming application name.
Note:
dataSetId and consumingAppName is mandatory input for this endpoint
Produces
MediaType.APPLICATION_JSON/MediaType.APPLICATION_XML
Sample request
<hostname>:<port>/<app_name>-batch-job-admin/resources/bulk-data/export/begin?dataSetId=10&consumingAppName=external
Sample json response
{
"Message": {
"returnCode": "TRANSACTION_STARTED",
"messageDetail": "Transaction started for dataset Id 10"
},
"transactionid": "external:Diff_Fnd:10:1585633498380"
}getData
This endpoint can be used to get data from inbound tables. It uses transaction id provided in input to identify start and end sequence of available dataset for interface module. This end point uses pagination to fetch records. Query parameters "page" and "maxRowsPerPage" can be used to specify page number and number of records per page respectively.
"hasMorePages" field from response can be used to identify if there are more records to be fetched for dataset. True value indicates that there are more records to be fetched and false value indicates that current page is the last page.
"action" node in response signifies the action to be performed on "data" that is returned.
For example, "action:REPLACE" signifies that replace if existing records with the current one that is returned by getData endpoint.
"next" field from response can be used to get available data from next page.
page and maxRowsPerPage are optional query parameters.
If query parameter page is missing in request, then value of it will be defaulted to 1 by Bulk Data Export Service. If query parameter maxRowsPerPage is missing in request, then value of it will be defaulted to 500 records by Bulk Data Export Service
HTTP Method: GET
Path
resources/bulk-data/export/data?transactionId={transactionId is mandatory}&page={page}&maxRowsPerPage=500
transactionId: Provide transaction id generated by beginExport endpoint as value of this field.
page: This is an optional field. Ensure that value of this field is a numeric value.
Value will be defaulted to 1, if not specified in request.
maxRowsPerPage: This is an optional field. Ensure that value of this field is a numeric value.
Value will be defaulted to 500, if not specified in request
Note:
transactionId is mandatory input for this endpoint
Maximum number of records that can be returned by getData end point is controlled through an entry in SYSTEM_OPTIONS table called "ROWS_PER_PAGE_MAX_VALUE".
If value of query parameter maxRowsPerPage is greater than ROWS_PER_PAGE_MAX_VALUE, then maxRowsPerPage is defaulted to value of entry "ROWS_PER_PAGE_MAX_VALUE" in SYSTEM_OPTIONS table.
If SYSTEM_OPTIONS table misses entry for ROWS_PER_PAGE_MAX_VALUE, then ROWS_PER_PAGE_MAX_VALUE is defaulted to 10000 by Bulk Data Export Service.
Refer section "Steps to update values in System Options" to add/update ROWS_PER_PAGE_MAX_VALUE in SYSTEM_OPTIONS table.
Produces
MediaType.APPLICATION_JSON/MediaType.APPLICATION_XML
Sample request
<host>:<port>/<app_name>-batch-job-admin/resources/bulk-data/export/data?transactionId=external:Diff_Fnd:10:1585743226654&page=1&maxRowsPerPage=100
Sample Json Response:
{
"Message": {
"returnCode": "GET_DATA_SUCCESSFUL",
"messageDetail": "Records are available for interface module Diff_Fnd"
},
"hasMorePages": true,
"next": "http://blr00ccp:55663/rms-batch-job-admin/resources/bulk-data/export/data?transactionId=external:Diff_Fnd:10:1585743226654&page=2&maxRowsPerPage=5",
"interfaceModule": "Diff_Fnd",
"InterfaceData": [
{
"interfaceShortName": "DIFF_GRP_DTL",
"columnNames": "DIFF_GROUP_ID,DIFF_ID,DISPLAY_SEQ",
"recordCount": 5,
"Records": {"Record": [
{
"action": "REPLACE",
"data": "AAA1,AAAAAAAA,11"
},
{
"action": "REPLACE",
"data": "AAA1,AAAAAAAA,12"
},
{
"action": "REPLACE",
"data": "AAA1,AAAAAAAA,13"
},
{
"action": "REPLACE",
"data": "AAA1,AAAAAAAA,14"
},
{
"action": "REPLACE",
"data": "AAA1,AAAAAAAA,15"
}
]}
},
{
"interfaceShortName": "DIFF_GRP",
"columnNames": "DIFF_GROUP_DESC,DIFF_GROUP_ID,DIFF_TYPE_DESC,DIFF_TYPE_ID",
"recordCount": 5,
"Records": {"Record": [
{
"action": "REPLACE",
"data": "Test Value,AAA1,Test Value,seq"
},
{
"action": "REPLACE",
"data": "Test Value,AAA1,Test Value,seq"
},
{
"action": "REPLACE",
"data": "Test Value,AAA1,Test Value,seq"
},
{
"action": "REPLACE",
"data": "Test Value,AAA1,Test Value,seq"
},
{
"action": "REPLACE",
"data": "Test Value,AAA1,Test Value,seq"
}
}
],
"currentPageNumber": 1
}Error Response:
{
"Message": {
"returnCode": "GET_DATA_FAILED",
"messageDetail": "Data set is already processed for dataset id .10"
},
"hasMorePages": "false",
"currentPageNumber": "0"
}endExport
This endpoint can be used to mark status of data export for a given transaction. It accepts status of transaction as query parameter.Transaction status will be defaulted to SUCCESS, if not specified in input.
List of acceptable values for transaction status are "SUCCESS" and "FAILURE"
HTTP Method: POST
Path
resources/bulkdata/export/end?transactionId={transaction id mandatory}&transactionStatus={optional, default to success}
transactionId : Provide transaction id generated by beginExport endpoint as input to this field.
transactionStatus: This is an optional input. Value will be defaulted to SUCCESS, if not specified in input.
List of acceptable values for transaction status are "SUCCESS" and "FAILURE"
Any value apart from above two will result in exception.
Note:
transactionId is mandatory input to this end point
Produces
MediaType.APPLICATION_JSON/MediaType.APPLICATION_XML
Sample request
<host>:<port>/<app_name>-batch-job-admin/resources/bulk-data/export/end?transactionId=external:Diff_Fnd:10:1585633498380&transactionStatus=SUCCESS
Sample json response
When transactionStatus=SUCCESS
{
"returnCode": "TRANSACTION_COMPLETE",
"messageDetail": "Transaction completed successfully."
}When transactionStatus= FAILURE
{
"returnCode": "TRANSACTION_FAILED",
"messageDetail": "Transaction could not be completed.."
}Error Response
Invalid input for transaction Id:
{
"returnCode": "TRANSACTION_ERROR",
"messageDetail": "Transaction status could not be parsed. Provide one of the following value {SUCCESS,FAILURE}"
}Steps to test Bulk data export service:
Attached script can be used to test Bulk data export service.
Steps to execute the script:
-
Open the script using any editor or command line.
-
Replace the hostname and port number to point deployed app.
-
Can modify the consumingAppName, by default the script has it as "external"
-
Save the script.
-
Run the script with interface name. Below is the command to run the script.
Note:
Need to run using bash only. The script only works for a full data set.
bash bdi_poc.sh <Interface_Name> ---- Pass interface name for Full data set.
Example - bash bdi_poc.sh Clearance_Tx
-
Script will prompt for deployed app username and password.