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 (i.e. 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 i.e. 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 (i.e. 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 i.e 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, e.g. 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.

Note

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 therefor 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 i.e. 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.

Authorization

The integration point is protected by 'activities IP' access restriction.

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>

Create or Start Activity request - PROVIDER_IMPORT

<activity
  level="GL"
  code="PROVIDER_IMPORT"
  description="Processed data file set 001V11">
   <parameters>
     <parameter   name="dataFileSetCode" value="001V11"/>
     <parameter   name="responseDataFileSetCode" value="response001V11"/>
   </parameters>
</activity>