Activity Integration Point
The activity integration point provides the following functions:
-
Create an activity with the intention to start it later.
-
Create and immediately start an activity.
-
Recover an activity.
-
Monitor status of an activity.
Creating and Starting an Activity
This request enables an external system to create and start an activity. The URI that is used determines how the system processes the request. Use URI:
http://{{hostname_port}}/component-ws/api/
-
/activities -to create an activity but not execute it yet.
-
/activities/start -to create an activity and immediately execute it.
-
/activities/{activity_id}/start -to start an activity that was created earlier.
Request Message
The start activity request will have the following structure:
<activity level="" code="" description="" parameterSetCode=""> <contextFields> <contextField name="" value=""/> </contextFields> <parameters> <parameter name="" value=""/> </parameters> </activity>
{ "code": "REFSHEETLINE_IMPORT", "description": "REFSHEETLINE_IMPORT", "level": "GL", "parameters": [ { "name": "dataFileSetCode", "value": "aprDRGBaseFileSet5" }, { "name": "responseDataFileSetCode", "value": "aprDRGBaseResultFileSet_5" } ] }
Context Field
Some activity types can only be started in a specified context. This information is provided via the <contextFields> element. The attribute "name" of element <contextField> must point to the context and the attribute "value" must contain the logical key for the context.
The allowed options are:
-
for level TS (Transaction Set) the name should be 'transactionSet' and the value the code of the financial transaction set
-
for level CO (Contract) the name should be 'contract' and the value the code of the capitation contract
-
for level GA (Group Account) the name should be 'groupAccount' and the value the code of the group account
Response Message
If the activity was successfully created but not started (that is, URI /activities was used) then the response will have the following structure:
<activity level="" status=""> <links> <link rel='action/startprocessing' uri='http://host:port/api/activities/{activityId}/start'/> <link rel='self' uri='http://host:port/api/activities/{activityId}'/> </links> </activity>
Note that the URI in the link can be used by the client to start the activity. Only initial (status "Initial") activities can be started. An attempt to start an activity that is not in a valid state that is, already completed activity, or an activity that is currently being processed will result in an error (ACT-IP-ACTY-006).
If the activity was created and executed immediately (that is, URI /activities/start was used) then the response will have the following structure:
<activity level="" status=""> <links> <link rel='self' uri='http://host:port/api/activities/{activityId}'/> </links> </activity>
In case the activity could not be registered in the system, for example because the activity code is unknown, the response will be as specified under "Indicating Failure" topic in Response Messages.
Recover an Activity
This request enables an external system to recover a failed activity. This is a URI based request with the following pattern: /activities/{activityid}/recover.
Only non-spawned failed (with origin "Manual" or "IP" and status "Business error", "Completed with business errors", "Technical error" or "Completed with technical errors") 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 will result in an error (ACT-IP-ACTY-007).
The recover request will have a similar response as that of a start activity.
Status Monitoring
Step 1: Get activity status
This feature provides the ability to fetch the status of an activity. This is a URI based request with the following pattern: /activities/{activityid}.
Response Message
<activity level="" status=""> <links> <link rel='messages' href='http://host:port/api/generic/activitymessages?q=activity.id.eq({activityid}).or.(activity.rootActivityId.eq({activityid}))'/> <link rel='self' uri='http://host:port/api/activities/{activityId}'/> </links> </activity>
If the activity has concluded with errors and it is desirable to have the details of the errors then Step 2 must be performed.
Step 2: Get activity result messages
This feature provides the ability to get the result messages of an activity. The URI received from the step 1 should be used, that is, api/generic/activitymessages?q=activity.id.eq({activityid}).or.(activity.rootActivityId.eq({activityid})). This supports Pagination.
Response Message
The response will have the following structure:
<activityMessages> <activityMessage elementId=""> <links> <link rel='self' uri='http://host:port/api/generic/activitymessages/{activitymessageId}'/> </links> <activity act_level="" > <links> <link rel='messages' href='http://host:port/api/generic/activitymessages?q=activity.id.eq({activityid}).or.(activity.rootActivityId.eq({activityid}))'/> <link rel='self' uri='http://host:port/api/activities/{activityId}'/> </links> </activity> <message id="> <links> <link rel='canonical' uri='http://host:port/api/generic/messages/{messageId}'/> </links> </message> </activityMessage> </activityMessages>
Element and Attribute
-
<activityMessage elementId> its an optional parameter. It provides consolidation of the messages based on its value. The elementId attribute usage for an activity is defined in the description of the activity type. Example: For the provider import activity the element id can be provider code in combination with the flex field code for the provider resource.
Optional: Activity Notification
The activity integration point provides a call back feature to a pre-configured endpoint. This feature provides the following response to the configurable endpoint once the activity triggered by an external system through IP has concluded. The generic notification endpoint can be configured as property 'ohi.activityprocessing.notification.endpoint' in the Oracle Health Insurance Components application’s properties file. The notification endpoint can be overridden for specific activity types, for example, specify property 'ohi.activityprocessing.notification.endpoint.SELECT_TRANSACTIONS_IN_SET' to have the system deliver all notifications for activity type SELECT_TRANSACTIONS_IN_SET to a specific endpoint. Here SELECT_TRANSACTIONS_IN_SET is the activity type code.
If the activity notification endpoint is configured on the specific activity type code, all other properties (described below) are also fetched based on activity type code or else defaults are used. Similarly if the endpoint for the activity notification is configured without the activity type code, then all other properties are fetched on a generic usecase 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 notification, for example when no end point is configured or a wrong endpoint is configured is not considered as an activity failure. |
Response Message
The response message once the activity has concluded will have the following common structure:
<notification correlationId="" workId="{activityId}" status="Success/Failure"> <links> <link rel='messages' href='http://host:port/api/generic/activitymessages?q=activity.id.eq({activityid}).or.(activity.rootActivityId.eq({activityid}))'/> <link rel='self' uri='http://host:port/api/activities/{activityId}'/> <link rel='file' uri='http://host:port/api/datafilesets/{datafilesetcode}/datafile/{datafilecode}/data'/> ... </links> <fields> <level></level> <activityStatus></activityStatus> </fields> </notification>
In case of failure to retrieve the status of activity (Example: activity code is unknown) the response will be as specified under "Indicating Failure" topic in Response Messages.
The endpoint to which the notification is sent is expected to respond with either an HTTP 200 or 202.
Conversation Parameter
The responseDataFileSetCode parameter influences the standard request-response mechanism for an activity, it is therefore referred to as a conversation parameter.
As is the case with any activity parameters, conversation parameters can only be used if they are defined for the activity type. The following is an example of a start activity request that makes use of the responseDataFileSetCode parameter:
<activity level="" code=""> <parameters> <parameter name="responseDataFileSetCode" value="RESPONSE_DFS"/> </parameters> </activity>
Assuming that the parameters and values are valid, the request in this example creates an activity. As part of the execution a response data file set with code "RESPONSE_DFS" is created. The response to the status monitoring requests that is, get activity status and the call back response (<resultDataFileset > element will be added to the above response) will have the following structure:
Response Message
<activity level="" status=""> <links> <link rel='messages' href='http://host:port/api/generic/activitymessages?q=activity.id.eq({activityid}).or.(activity.rootActivityId.eq({activityid}))'/> <link rel='self' uri='http://host:port/api/activities/{activityId}'/> <link rel='file' href='http://host:port/api/datafilesets/{datafilesetcode}/datafile/{datafilecode}/data'/> </links> </activity>
The response file can be downloaded by using "Get details of a data file" request from data file integration point the following URI should be use to initiate a request to download the response file.
http://host:port/api/datafilesets/{datafilesetcode}/datafile/{datafilecode}/data
The response file will have the following structure:
<{rootElelement}> <resultMessages result="" elementId=""> <resultMessage code ="" > Text Message </resultMessage> </resultMessages> </{rootElelement}>
The {rootElelement} for the response file is described in the activity type.
Error Messages
The following error messages, that are specific to the activity integration point may be returned in the response messages:
Message code | Scenario | Message | Severity |
---|---|---|---|
ACT-IP-ACTY-001 |
Create or Create & Start activity |
Activity code {0} is unknown |
Fatal |
ACT-IP-ACTY-002 |
Create or Create & Start activity |
Activity type level {0} is unknown |
Fatal |
ACT-IP-ACTY-003 |
Create or Create & Start activity |
Parameter set code {0} is unknown |
Fatal |
ACT-IP-ACTY-005 |
Create or Create & Start activity |
Use either a parameter set or parameters but not both |
Fatal |
ACT-IP-ACTY-006 |
Start activity |
Only initial activities can be started |
Fatal |
ACT-IP-ACTY-007 |
Recover activity |
Only non-spawned failed activities can be recovered |
Fatal |
ACT-FL-DAFI-001 |
Activity Notification |
Messages are written to the Data File Set(s) {comma separated list of data file set ids} |
Informative |
Examples
Create or Start Activity request - SELECT_TRANSACTIONS_IN_SET
<activity level="GL" code="SELECT_TRANSACTIONS_IN_SET" description="Select processed transaction in a new set"> <parameters> <parameter name="financialTransactionSetCode" value="FINANCIALTRANSACTIONSRUN_20141107"/> <parameter name="financialTransactionSetDescr" value="Financial transactions set for Nov-07, 2014"/> <parameter name="transactionCreatedDateFrom" value="2010-01-01"/> <parameter name="transactionCreatedTimeFrom" value="0800"/> <parameter name="transactionCreatedDateTo" value="2014-11-06"/> <parameter name="transactionCreatedTimeTo" value=""/> <parameter name="paymentDueDateFrom" value="2010-01-01"/> <parameter name="paymentDueDateTo" value="2014-11-14"/> <parameter name="includeUnfinalized" value="Y"/> ..... </parameters> </activity>
Create or Start Activity request - SUPERSEDE
<activity level="TS" code="SUPERSEDE" description="Supersede applicable transaction in the set FINANCIALTRANSACTIONSRUN_20141107"> <contextFields> <contextField name="transactionSet" value="FINANCIALTRANSACTIONSRUN_20141107"/> </contextFields> </activity>