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. Following is the URI that determines how the system processes the request:
http://[hostName]:[portNumber]/[api-context-root]/
-
/activities - create an activity but does not execute it
-
/activities/start - creates an activity and executes it
-
/activities/{activity_id}/start - starts the previously-created activity
When executing the activity (using /start
or /{activity_id}/start
) operation, the application creates a new task ActivitySubmissionTask
to start the activity.
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.
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 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 act_level="">
<links>
<link href="http://host:port/api/generic/financialtransactionsetactivities/activityid" rel="self" />
<link href="http://host:port/api/generic/activitymessages/search" rel="operator:messages" httpMethod="POST">
<body>
<resource q="activity.id.eq(activityid).or.(activity.rootActivityId.eq(activityid))" />
</body>
</link>
</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
POST api/generic/activitymessages/search
{
"resource": {
"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 href="http://host:port/api/generic/financialtransactionsetactivities/activityid" rel="self" />
<link href="http://host:port/api/generic/activitymessages/search" rel="operator:messages" httpMethod="POST">
<body>
<resource q="activity.id.eq(activityid).or.(activity.rootActivityId.eq(activityid))" />
</body>
</link>
</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> is 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 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=<server>: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, using ohi.activityprocessing.notification.endpoint.SELECT_TRANSACTIONS_IN_SET where SELECT_TRANSACTIONS_IN_SET is the activity type code. Setting this property delivers all notifications for activity type SELECT_TRANSACTIONS_IN_SET to a specific endpoint.
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 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 href="http://host:port/api/generic/financialtransactionsetactivities/activityid" rel="self" />
<link href="http://host:port/api/generic/activitymessages/search" rel="operator:messages" httpMethod="POST">
<body>
<resource q="activity.id.eq(activityid).or.(activity.rootActivityId.eq(activityid))" />
</body>
</link>
</links>
<fields>
<level />
<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>esponseDataFileSetCode" 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 href="http://host:port/api/generic/financialtransactionsetactivities/activityid" rel="self" />
<link href="http://host:port/api/generic/activitymessages/search" rel="operator:messages" httpMethod="POST">
<body>
<resource q="activity.id.eq(activityid).or.(activity.rootActivityId.eq(activityid))" />
</body>
</link>
</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://[hostName]:[portNumber]/[api-context-root]/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.
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.
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>