Activities
An activity is an action or set of actions performed by the application. The actions are pre-defined by the activity type. Parameters enable specifying the context and the detailed behavior of the activity.
Depending on the type of activity, activities can result in input, for example REFERENCE SHEET LINE IMPORT, output, for example GENERATE OUTPUT, or in processing data, for example CALCULATE PREMIUM in Policies.
Operations
This specific API supports creating and starting activities and monitoring the status.
|
|
|
|
|
|
|
|
|
|
|
|
Oracle Health Insurance supports a generic activities API and a specific activities API. |
The generic activities API supports the standard generic operations.
Oracle Health Insurance also supports generic APIs on
-
/generic/groupaccountactivities
-
/generic/basefinancialobjectactivities
-
/generic/groupclientactivities
-
/generic/financialtransactionsetactivities
-
/generic/policyactivities
-
/generic/connectorconfigurationactivities
-
/generic/globalactivities
.
These are all subsets of the data returned by the generic /activities
API.
Rules
-
Only activities with status "Initial" can be started. An attempt to start an activity that is not in a valid state, that is, an already completed activity, or an activity that is currently being processed, results in an error (ACT-IP-ACTY-006).
-
Activities that run an import have the following additional rules:
-
The payload must have a parameter
dataFileSetCode
. -
The payload parameter
responseDataFileSetCode
, the data file set code for the data file set of the response file, is optional. If not provided, the system uses the generated id as data file set code. -
The Indicator Locked on the data file set must be "N". The system raises error ACT-VL-FIAT-001 if the indicator is not "N".
Once the activity picks up a data file set for processing (that is, starts a created activity), it places a lock on it by updating the indicator Locked to "Y". If the indicator Locked is already found to be "Y" then an error ACT-VL-FIAT-001 is raised. Activity must unlock the data file set in case if the processing completes with the errors.
-
The data file set must contain one or more data files.
The system raises error ACT-VL-DAFI-001 if no data file exists in the data file set. -
The datafile must not be empty.
The system raises error ACT-VL-DAFI-002 if the data file is empty. -
The data file must be of the correct type for the import activity (that is, it must have the correct root element).
The system raises error ACT-VL-DAFI-003 if the data file does not have the correct root element.
-
Create or Update Behavior
-
The
POST
on/activities
and the/activities/start
APIs always creates a new activity.
ThePOST
on/activities/{activityId}/start
and the/activities/{activityId}/recover
APIs always searches for an existing activity.
Context Field
Some activity types can only be started in a specified context. Provide this information via the <contextFields> element. The attribute "name" of element <contextField> specifies the context and the attribute "value" specifies the logical key for the context.
The allowed options for the context name are:
-
For activities of level
TS
(Transaction Set) the name is "transactionSet" and the value is the code of the financial transaction set. -
For activities of level
CO
(Contract) the name is "contract" and the value is the code of the capitation contract. -
For activities of level
GA
(Group Account) the name is "groupAccount" and the value is the code of the group account.
Request Messages
The POST
request on /activities/start
creates and starts an activity.
Example Request Message to Create or Create and Start an Activity (click to open)
{ "code": "REFSHEETLINE_IMPORT", "description": "REFSHEETLINE_IMPORT", "level": "GL", "parameters": [ { "name": "dataFileSetCode", "value": "aprDRGBaseFileSet5" }, { "name": "responseDataFileSetCode", "value": "aprDRGBaseResultFileSet_5" } ] }
The POST
request on /activities/{activityId}/start
starts the previously-created activity.
Example Request Message to Create or Create and Start an Activity with a Context Field (click to open)
{ "code":"SELECT_TRANSACTIONS_IN_SET", "description":"Transaction in Set 123", "level":"TS", "parameters": [ {"name":"transactionCreatedDateFrom", "value":"2023-05-26"} ], "contextFields":[ {"name":"transactionSet", "value":"TS_12345"} ] }
Response Messages
Success
If the activity was successfully created but not started (that is, URI /activities
was used), the response has the following structure:
Example of a Response Message after Create but not yet Start an Activity (click to open)
{ "status": "IN", "level": "GL", "type": "REFSHEETLINE_IMPORT", "workId": "\{activityId}", "links": [ { "href": "{apiurl}/activities/\{activityId}/start", "rel": "action/startprocessing", "httpMethod": "POST" }, "href": "{apiurl}/activities/\{activityId}", "rel": "self", "httpMethod": "GET" } ] }
Note that the status of the activity is Initial (IN) and the response message provides a link to start the activity.
Example of a Response Message after Create and Start an Activity (click to open)
{ "status": "IP", "level": "GL", "type": "REFSHEETLINE_IMPORT", "workId": "\{activityId}", "links": [ "href": "{apiurl}/activities/\{activityId}", "rel": "self", "httpMethod": "GET" } ] }
Note that the status of the activity is In Process (IP) and the response message does not provide a link to start the activity.
Unable to Create the Activity
In case the activity can’t be registered in the system, the application returns an HTTP Error response as specified under the "Indicating Failure" topic in Response Messages.
Activity Error
In case the activity is successfully registered in the system but runs into an error during processing, the response has the following structure:
Example of a Response Message for a Failed Activity (click to open)
{ "status": "BE", "level": "GL", "type": "REFSHEETLINE_IMPORT", "workId": "\{activityId}", "links": [ { "href": "{apiurl}/activities/\{activityId}/recover", "rel": "operator/restart", "httpMethod": "POST" }, "href": "{apiurl}/activities/\{activityId}", "rel": "self", "httpMethod": "GET" } ] }
The status can be "BE", "CB", "TE", or "CT" depending on the type of error and the level of the activity.
Note that the URI in the link can be used to recover the activity.
Recover an Activity
The POST
request on http://[hostName]:[portNumber]/[api-context-root]/activities/{activityid}/recover
recovers a failed activity.
Not only non-spawned (with origin "Manual" or "IP" and status "Business error", "Completed with business errors", "Technical error" or "Completed with technical errors") failed activities but also the Top-Level (marked as an indicator on activity type) failed activities can be recovered. Examples of such failures could be the inability of sending out financial messages or errors in dynamic logic or any other technical error.
An attempt to recover an activity that is not in a valid state results in an error (ACT-IP-ACTY-007).
The recover request has a similar response as that of a start activity.
Monitor Activity Status
Step 1: Get Activity Status
To monitor the status of an activity send a GET
request to /activities/{activityid}
.
Response Message
Example of a Response Message for a Successful Completed Activity (click to open)
{ "status": "CO", "level": "TS", "type": "GENERATE_FIN_MSG_XML", "workId": "\{activityId}", "links": [ { "href": "{apiurl}/generic/activitymessages/search", "rel": "operator:messages", "httpMethod": "POST", "body": { "resource": { "q": "activity.id.eq\{activityId}.or.(activity.rootActivityId.eq\{activityId})"}} }, {"href": "{apiurl}/activities/\{activityId}", "rel": "self", "httpMethod": "GET" } ] }
The activity status has one of the following values:
-
BE (Business error)
-
CB (Completed with business errors)
-
CO (Completed)
-
CT (Completed with technical errors)
-
IN (Initial)
-
IP (In process)
-
QD (Queued)
-
TE (Technical error)
The links in the response message depend on the status of the activity.
To see the the result messages of an activity send a POST
request to http://[hostName]:[portNumber]/[api-context-root]/generic/activitymessages/search
with the body
{ "resource": { "q": "activity.id.eq(\{activityid}).or.(activity.rootActivityId.eq(\{activityid}))" } }
|
... { "href": "{apiurl}/generic/activitymessages/search", "rel": "operator:messages", "httpMethod": "POST", "body": { "resource": { "q": "activity.id.eq(\{activityid}).or.(activity.rootActivityId.eq(\{activityid}))" } } }, ...
Response Message
The response has the following structure:
Example of a Response Message for Activity Messages (click to open)
{ "id": "246362953", "objectVersionNumber": 1, "value0": "3383073", "links": [ { "href": "{apiurl}/generic/activitymessages/246362953", "rel": "self" } ], "activity": { "id": "2444362888", "act_level": "TS", "links": [ { "href": "{apiurl}/generic/financialtransactionsetactivities/2444362888", "rel": "canonical" }, { "href": "{apiurl}/generic/activitymessages/search", "rel": "operator:messages", "httpMethod": "POST", "body": { "resource": { "q": "activity.id.eq(2444362888).or.(activity.rootActivityId.eq(2444362888))" } } }, { "href": "{apiurl}/activities/2444362888", "rel": "self", "httpMethod": "GET" }, { "href": "{apiurl}/datafilesets/3383073/datafiles/3383082/data", "rel": "file", "httpMethod": "GET" } ] }, "message": { "id": "253700", "links": [ { "href": "{apiurl}/generic/messages/253700", "rel": "canonical" } ] } }
ElementId
The elementId
in the activity message refers to the element the activity was processing when it raised the message.
The content of the elementId' depends on the activity type.
For example, the provider import activity fills the `elementId
with the provider code in combination with the flex field code for the provider resource.
The elementId
can be used as search criterion.
{ "resource": { "q": "elementId.eq('PR001, Abcde')" } }
Activity Notification
The activity integration point calls back a pre-configured endpoint once the activity - that triggers from an external system through an integration point - is complete. You can configure the generic notification endpoint using the ohi.activityprocessing.notification.endpoint property. Following is an example of how you can set a property to send notifications to Oracle Insurance Gateway:
ohi.activityprocessing.notification.endpoint=http://[hostName]:[portNumber]/[api-context-root]/notifications
Refer to Property Management for more information on setting up a property.
You can override the notification endpoint for an activity type.
For example, setting the value of the property ohi.activityprocessing.notification.endpoint.SELECT_TRANSACTIONS_IN_SET
delivers all notifications for activity type SELECT_TRANSACTIONS_IN_SET to the endpoint specified in the value.
If you configure an activity notification endpoint on an activity type code, the integration point fetches all properties (described below) for the activity type code or defaults. If you configure an endpoint for the activity notification without the activity type code then, the integration point fetches all other properties with a generic code ActivityNotificationClient.
Category | Property Name | Value | Explanation |
---|---|---|---|
Media Type |
ohi.service.{0}.media.type |
Optional. Sample: ohi.service.ActivityResponseClient.media.type=application/json ohi.service.<activity_type_code>.media.type=application/xml |
The media type in which the response is sent to the external endpoint. Default value is application/json |
Http Method |
ohi.service.{0}.notification.method |
Optional. Possible values are POST or PUT ohi.service.ActivityResponseClient.notification.method= POST ohi.service.<activity_type_code>.notification.method= PUT |
Control which HTTP Method to use to send out the notification. Default is POST |
Authentication Mechanism |
ohi.service.{0}.client.authentication |
Optional. Possible values are BasicAuthentication, OAuth or None ohi.service.ActivityResponseClient.client.authentication= BasicAuthentication ohi.service.<activity_type_code>.client.authentication= None |
Controls which Authentication mechanism to use to send out the notification. Default value is BasicAuthentication. |
If Authentication mechanism is not None, it is also essential to set up Credentials.
For Basic Authentication, it is done using Credentials Integration Point. The credentialKey to setup the credentials is same as the one which is used to set up the endpoint. Generic: ActivityResponseClient or Specific on activity type code, example: SELECT_TRANSACTIONS_IN_SET.
For Oauth Based Integration, please set it up using "Securing Outbound RESTful Service Invocations using OAuth2", section Callout Rule.
Failure to send a notification, for example when no end point is configured or a wrong endpoint is configured, is not considered as an activity failure. |
Notification Response Message
The notification response message has the following common structure:
Example of a Notification Response Message (click to open)
{ "correlationId" : "123456789 ", "workId" : "\{activityId}", "status" : "Success/Failure", "links" : [ { "href" : "{apiurl}/generic/activitymessages?q=activity.id.eq(\{activityid}).or.(activity.rootActivityId.eq(\{activityid}))", "rel" : "messages" }, <link rel="self" uri="{apiurl}/activities/\{activityId}"/> <link rel="file" uri="{apiurl}/datafilesets/\{datafilesetcode}/datafile/\{datafilecode}/data"/> ], "fields" : [ <level></level> <activityStatus></activityStatus> ] }
In case of failure to retrieve the status of activity (Example: activity code is unknown) the response is as specified under "Indicating Failure" topic in Response Messages.
The application expects the endpoint to which the notification is sent, to respond with either an HTTP 200 or 202.
responseDataFileSetCode
The responseDataFileSetCode parameter specifies the code of the datafileset that the activity uses to store the results of the activity.
The system only accepts a responseDataFileSetCode parameter for specific activity types (those that have been designed for storing their data in a data set).
Example Request Message to Create an Activity and Store results in a datafileset (click to open)
{ "code": "REFSHEETLINE_IMPORT", "description": "REFSHEETLINE_IMPORT", "level": "GL", "parameters": [ { "name": "dataFileSetCode", "value": "aprDRGBaseFileSet5" }, { "name": "responseDataFileSetCode", "value": "aprDRGBaseResultFileSet_5" } ] }
Example Response Message of an Activity that stored Results in a datafileset (click to open)
{ .... "activity": { "id": "2444362888", "act_level": "TS", "links": [ { "href": "{apiurl}/generic/activitymessages/search", "rel": "operator:messages", "httpMethod": "POST", "body": { "resource": { "q": "activity.id.eq(2444362888).or.(activity.rootActivityId.eq(2444362888))" } } }, { "href": "{apiurl}/activities/2444362888", "rel": "self", "httpMethod": "GET" }, { "href": "{apiurl}/datafilesets/3383073/datafiles/3383082/data", "rel": "file", "httpMethod": "GET" } ] }, ...
The data file can be downloaded by using "Get details of a data file" request from the data file integration point.
Throttling Concurrent Parent-Level Activities
To prevent the system from overloading, the application throttles and runs limited parent-level activities in parallel. The application starts a few activities, and queues the others to start after the running activities are complete.
Disable Activity Processing on a Specific JVM/Node
Processing of activities is enabled by default.
To disable the activity processing on a specific JVM, set the property ohi.activityprocessing.enabled
to false
using JAVA_OPTIONS.
- Example
-
If a common (shell) script is used for all the managed servers in the cluster, the following example shows how to disable activity processing only on
managed_server1
,
if [ "$SERVER_NAME" = "managed_server1" ] ; then
JAVA_OPTIONS="${JAVA_OPTIONS} -Dohi.activityprocessing.enabled=false"
export JAVA_OPTIONS
fi
Automatic Detection of Stuck Activities
For the activities that get stuck, the application detects and resubmits the activities. If the resubmissions exceeds the configured attempt count, the application sends a notification (see Activity Notification) for the stuck activities. To disable this feature, set the ohi.activityprocessing.heartbeat.frequency
property to 0
.
System Properties
-
The
ohi.activityprocessing.max.resubmit.attempt.count
(default value is3
) controls the maximum number of resubmissions of an activity. -
The
ohi.activityprocessing.heartbeat.frequency
(default value is300 seconds
) controls the heartbeat frequency. To disable this feature, set the property value to0
. -
The
ohi.activityprocessing.cleanup.frequency
(default value is600 seconds
) controls the cleanup frequency.
Error Messages
The following error messages, that are specific to the activity interface may be returned to the response messages:
Code | Severity | Message |
---|---|---|
ACT-IP-ACTY-001 |
Fatal |
Activity code {0} is unknown |
ACT-IP-ACTY-002 |
Fatal |
Activity type level {0} is unknown |
ACT-IP-ACTY-003 |
Fatal |
Parameter set code {0} is unknown |
ACT-IP-ACTY-005 |
Fatal |
Use either a parameter set or parameters but not both |
ACT-IP-ACTY-006 |
Fatal |
Only initial activities can be started |
ACT-IP-ACTY-007 |
Fatal |
Only non-spawned failed activities can be recovered |
ACT-FL-DAFI-001 |
Informative |
Messages are written to the Data File Set(s) {comma separated list of data file set ids} |