4.5 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:

• /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>

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. 

Example: activity type SUPERSEDE_REVERSE that is defined at level TS (or TransactionSet) can only be started in context of a financial transaction set. The financial transaction set code must be provided as value to set-up the execution context.

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' type='application/xml' uri='/activities/{activityId}/start'/>
  </links>
</activity>

Note that the URI in the link can be used by the client to start the activity. 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 have a similar response as that of get activity status.  

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' type='application/xml' uri='/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 activities that failed in status TE/CT can be recovered. Examples of such a failure could be the inability of sending out financial messages or errors in dynamic logic or any other technical error. Attempt to recover an activity that is not in valid state will have a similar response as that of get activity status. 

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='/activities/{activityid}/messages'/>
   </links>  
</activity>

The <resultMessages> element will only be available when the activity has concluded with errors.  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 /activities/{activityid}/messages. This supports pagination.

Response Message

The response will have the following structure:

<activityMessages> 
  <resultMessages result="" elementId="">    
     <resultMessage 
       code =""
      >
      messageText
    </resultMessage>
  </resultMessages>  
</activityMessages>

Element and Attribute

• <resultMessage 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 OHI 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.

Response Message

The response message once the activity has concluded will have the following structure: 

<activity level="" status="">  
   <links>    
     <link rel='messages' href='/activities/{activityid}/messages'/>
   </links>     
</activity>

Note: the response may contain a <dataFileSets> element. Refer to Special parameters for details. 

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.