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.

POST

/activities creates an activity but does not start it.

POST

/activities/start creates and starts an activity.

POST

/activities/{activityId}/start starts the previously-created activity.

POST

/activities/{activityId}/recover recovers the failed activity.

GET

/activities/{activityId} retrieves the status of the activity.

GET

/activities/{activityId}/messages retrieves the result messages of an activity.

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.

Uniqueness

The system generates a unique identifier key (the id) for each activity.

Create or Update Behavior

The POST on /activities and the /activities/start APIs always creates a new activity.
The POST 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"}
  ]
}

Authorization

This API requires a grant for access restriction Activities IP.

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}))"
  }
}

This request returns the messages for the activity itself as well as for the activities spawned by this activity.
The response message for a GET request on an activity with messages, provides a link for the above messages request.

...
{
   "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.

Table 1. Optional: Activity Notification
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.

System Properties

The ohi.processing.concurrentparentactivities.throttle (default value is true) controls the throttling behaviour.
The ohi.processing.max.concurrentparentactivities.size (default value is 2) system property determines the number of parallel activities that run in parallel.

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 is 3) controls the maximum number of resubmissions of an activity.
The ohi.activityprocessing.heartbeat.frequency (default value is 300 seconds) controls the heartbeat frequency. To disable this feature, set the property value to 0.
The ohi.activityprocessing.cleanup.frequency (default value is 600 seconds) controls the cleanup frequency.

Authorization

The integration point is protected by activities IP access restriction.

Error Messages

The following error messages, that are specific to the activity interface may be returned to the response messages:

Table 2. Error 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}