Invoke Activity or Process Steps

The Invoke step defines the way in which an Integration can invoke processes within an Oracle Health Insurance application or externally. It is possible to configure multiple of these steps for an Integration.

Activity Step

An invoke step of subtype ACTIVITY enables the users to invoke Activity processing in the Oracle Health Insurance application using the Activity Integration Point Semantics.

The following table lists the fields valid for this type of step.

Field	Description	Mandatory?
Code	Code of the Activity step	Yes
Sequence	The sequence of this step. The integration steps get executed in ascending order of their sequence.	Yes
Subtype	ACTIVITY	Yes
Condition Invocation Check	A dynamic logic condition to check if this step should be invoked. The step is skipped if the condition returns false.	No
Function Post Process	A dynamic logic function to post process the results of the step.	No
Destination	Reference to REST Destination For invoke activity step, the system automatically constructs URL upto activity endpoint in the end application. The end application is determined based on context information specified by the destination address key. The destination address key must specify the URL value till the context root of the application.	Yes
Indicator Wait For Notification	Indicates if this invocation should wait for a notification for completion. Possible values are true/false. Default is false.	No
Output Name	Dynamic logic bind variable name. This variable holds the data files as received in the activity notification or the notification payload (when data files are absent) and is available as a bind variable to subsequent dynamic logic. If output name is not specified, then integration step code is used as the bind variable.	No
Type Config	level: The activity level, example GL. code: The activity type code, example GENERATE_FINANCIAL_MESSAGES. description: The activity description. contextFields: This is a list of context fields that defines the activity level. name: Name of the context field value: Value of the context field parameters: This is a list of parameters that are required for activity invocation. name: Name of the parameter field value: Value of the parameter field autoRecovery : true or false - Setting this as true, marks integration invocation as failed if the activity processing gets concluded with an error. When the invocation instance is recovered, the failed activity is also recovered. Default is true. downloadMessages: true or false - Indicates if the messages attached to the activity notification should be auto downloaded. Default is true. timeAllowed: The time allowed for this activity step to finish, before the Integration Gateway tries to fetch the status of the activity from target application. This can also be overwritten at the time of invocation. The value is specified in minutes. See below. Please note that autoRecovery, downloadMessages and timeAllowed are relevant only when indicator wait for notification is set to true	Yes

Activities in Oracle Health Insurance are long-running processes that work on large data and may produce data files. This step has pre-built capabilities to read the data files from the notification response. This feature helps in configuring integrations that invoke activities in the Oracle Health Insurance application, and later collect the data (Data File Sets) and store the data to be able to deliver (and transform) it subsequently. For this out of the box data collection to work, wait for notification must be set to true.

In addition, the activity notification endpoint system property and the credential key for the notification to come back to the gateway, must be set up in the interfacing application. This is detailed in Activity Integration Point. For details on Activity Integration Point, refer to Developer Guide in the interfacing the Oracle Health Insurance application.

Recovery

When the invoked process is an Oracle Health Insurance Activity it is possible to recover the activity, when the exchange (run time instance of the integration. For details on exchange and exchange steps refer to the chapter Gateway Runtime Model) is recovered.

This is possible by setting typeConfig attribute autoRecovery to true. In case, it is desired to not auto-recover but to decide based on the messages, it is possible to set this flag to false and determine based on the errors reported. This can be done by processing the downloaded messages (which are made available by the system as exchange log added as part of notificationCollectMessage exchange step) and using the predefined method markForRecovery on exchange object in the post process function dynamic logic. See Predefined Methods for more details on this method.

When the exchange is recovered, it results in re-triggering the activity step. Note that if there are data files that were downloaded as part of a previous run, then these files are not discarded by the system. New files received as part of recovery action are added to the existing data set. If no data set exists, only then a new data set is created.

Timeout

When the activity process is invoked, the target application replies with the location header of the activity. If a timeout is configured and when the timeout expires, the Integration Gateway framework tries to fetch the status of the activity through the location header of the invoked activity process. If the status is a final state, the process at the gateway end continues in the same way as when a notification is received. If the status is not in a final state, the process sleeps again and retries again for a maximum of three times (this can be overridden by system property ohi.timeout.maxRepeatAttempts). If after retry attempts, the process is not finished, exchange is marked as TimedOut. The timeout value can be overwritten at the time of invocation using the parameter < Integration Step Code>-timeAllowed for below sample, it would be: invokeGenerateFinancialMessage-timeAllowed). This overwritten value is in milliseconds. If there is no configuration present and there is no invocation time parameter, the process takes in the default of 5 minutes.

Please note that if the process resumes through a timeout and at a later the point in time, the notification of the same process also arrives, then this notification would fail as the process has already resumed and the process is not in the state of being resumed anymore.

Sample Configuration: Invoke activity Generate Financial Messages in Policies application

The activity step is configured as follows:

Field	Configuration	Remarks
code	invokeGenerateFinancialMessage
sequence	1	Assuming this is the first step in the Integration
destination	policies	Refers to a rest destination with code "policies"
outputName	financialData	The financial message data files returned with the activity notification can be accessed in the dynamic logic of the subsequent step using "financialData" bind variable.
indicatorExpectNotification	true	Set the activity notification endpoint in the Policies application to the Oracle Insurance Gateway notification endpoint. This requires the system property ohi.activityprocessing.notification.endpoint.GENERATE_FIN_MSG_XML to be set to: http(s)://{host:port}/{oig application context}/notifications Also, in the Policies application, the credential and the authentication property must be set for the key GENERATE_FIN_MSG_XML. This is similar to the set up of credential and authentication for the key policies_user as explained in the Query step example
type config	code: GENERATE_FIN_MSG_XML description: {description} level: TS contextFields: name: transactionSet value: {financialTransactionSetCode} parameters name: createInvoiceDynLogic, value: {createInvoiceDynLogic} name:createInvoiceLineDynLogic , value:{createInvoiceLineDynLogic} name:createAccountingDetailDynLogic , value:{createAccountingDetailDynLogic}, name:cutOffDate:{cutOffDate} , value: cutOffTime:{cutOffTime}	Description, financialTransactionSetCode, createInvoiceDynLogic, createInvoiceLineDynLogic, createAccountingDetailDynLogic,cutOffDate, cutOffTime are parameterized. The value for them can be provided as 'invocation parameters' while invoking the integration. For details refer to the section 'Integration Parameters and Exchange Properties'

An example of the JSON payload for the creation of such an Activity Step step using API is given below. Note that this JSON is part of the larger payload needed to create an Integration.

{
  "code":"invokeGenerateFinancialMessage",
  "indicatorExpectNotification":true,
  "subtype":"ACTIVITY",
  "sequence":"1",
  "destination":{
    "code":"policies"
  },
  "typeConfig":{
    "code":"GENERATE_FIN_MSG_XML",
    "description":"{description}",
    "level":"TS",
    "contextFields":[{
        "name":"transactionSet",
        "value":"{financialTransactionSetCode}"
    }],
    "parameters":[
      { "name":"createInvoiceDynLogic",
        "value":"{createInvoiceDynLogic}"
      },
      {
        "name":"createInvoiceLineDynLogic",
        "value":"{createInvoiceLineDynLogic}"
      },
      {
        "name":"createAccountingDetailDynLogic",
        "value":"{createAccountingDetailDynLogic}"
      },
      {
        "name":"cutOffDate",
        "value":"{cutOffDate}"
      },
      {
        "name":"cutOffTime",
        "value":"{cutOffTime}"
      }

    ]}
}

Process Step

An invoke step of subtype PROCESS enables users to invoke a process in any external application or an Oracle Health Insurance application (example invoking a long-running process or submit claims).

The following table lists the fields valid for this type of step.

Field	Description	Mandatory?
Code	Code of the integration step	Yes
Sequence	The sequence of this step. The integration steps get executed in an ascending order of their sequence.	Yes
Subtype	PROCESS	Yes
Condition Invocation Check	A dynamic logic condition to check if this step should be invoked. The step is skipped if the condition returns false	No
Function Post Process	A dynamic logic function to post process the results of the step.	No
Destination	Reference to the Destination.	Yes
Indicator Wait For Notification	Indicates if this invocation should wait for a notification for completion. Possible values are true/false. Default is false.	No
Output Name	Dynamic logic bind variable name. This variable holds the data files as received in the notification response or the process response (when data files are absent) and is available as a bind variable to all the subsequent dynamic logic. If output name is not specified, then integration step code is used as the bind variable.	No
Type Config	functionPayload: A dynamic logic function to provide the payload for invocating the process. If not present, it sends the output of the latest previous step that has raw payload as the payload for this step. payloadContentType: The mime type of the payload. It should follow the standard HTTP Content-Types. Default is application/json. notificationPayloadExtraction: A dynamic logic function to extract the Notification object from the custom notification payload that resumes the exchange after completion. autoRecovery : true or false - Setting this as true, marks integration invocation as failed if the external process gets concluded with an error. On Integration Invocation recovery, the failed process also gets auto-recovered, if the notification received has recovery links. Default is true. downloadMessages: true or false - Indicates if messages attached to the process notification should be auto downloaded. Default is true. timeAllowed: The time allowed for this process step to finish, before the Integration Gateway tries to fetch the status of the process from target application. This can also be overwritten at the time of invocation. The value is specified in minutes. See below. Please note that autoRecovery, downloadMessages and timeAllowed are relevant only when indicator wait for notification is set to true	Yes

Recovery

When the invoked process is an Oracle Health Insurance long-running process, it is possible to recover the process, when the exchange is recovered (run time instance of the integration. For details on exchange and exchange steps refer to the chapter Gateway Runtime Model). This is possible by setting typeConfig attribute autoRecovery true. In case, it is desired to not auto-recover but to decide based on the messages, it is possible to set this flag to false and determine based on the errors reported. This can be done by processing the downloaded messages (which are made available by the system as exchange log added as part of notificationCollectMessage exchange step) and using predefined method markForRecovery on exchange object in the post process function dynamic logic. See Predefined Methods for more details on this method.

When the exchange is recovered, it results in re-triggering of the Invoke step. Note that if there are data files that were downloaded as part of a previous run, then these files are not discarded by the system. New files received as part of recovery action are added to the existing data set. If no data set exists only then a new data set is created.

Timeout

When the long-running process is invoked and if the target application replies back with the location header of the process, the gateway process can try to fetch the status of the process after the timeout expires. If a timeout is configured and when the timeout expires, the Integration Gateway framework tries to fetch the status of the process through the location header of the invoked process. If the status is a final state, the process at the gateway end continues in the same way as when a notification is received. If the status is not in a final state, the process sleeps again and retries again for a maximum of three times (this can be overridden by system property ohi.timeout.maxRepeatAttempts). If after retry attempts, the process is not finished, exchange is marked as TimedOut. The timeout value can be overwritten at the time of invocation using the property < Integration Step Code>-timeAllowed (for the sample configuration specified below, it would be: InvokeClaimsUnfinalization-timeAllowed). This overwritten value is in milliseconds. If there is no configuration present and there is no invocation time property, the default value of 5 minutes is applied.

Please note that if the process resumes through a timeout and at a later the point in time, notification of the same process also arrives, the notification would fail as the process has already resumed and the process is not in the state of being resumed anymore.

Sample Configuration: Unfinalize Claim

The process step is configured as follows:

Field	Configuration	Remarks
code	InvokeClaimsUnfinalization	Unfinalize a specific claim
indicatorExpectNotification	false	This is a synchronous call with Claims
destination	claimsUnfinalize	Refers to a rest destination with code "claimsUnfinalize" (for details refer to "polices" destination explained with query step) Here, the system expects the value of path and httpMethod to be configured to reach to claims unfinalization endpoint. path = claims/{claimid}/unfinalize , httpMethod=POST claimId can be resolved by fetching the claim based on the claim code, that is sent in as request parameter during the integration invocation. See example dynamic logic.
sequence	1	Assuming this is the first step in integration
outputName	unfinalizeClaimsResponse	The response returned from unfinalizing claim can be accessed in the dynamic logic of the subsequent step using "unfinalizeClaimsResponse" bind variable
type config	functionPayload: unfinalizationRequest payloadContentType: application/json

An example of the JSON payload for the creation of such a process step using the API is given below. Note that this JSON is part of the larger payload for the creation of the Integration.

{
  "code": "UnfinalizeClaims",
  "sequence": 1,
  "subtype":"PROCESS",
  "outputName":"unfinalizeClaimsResponse",
  "destination": {
    "code": "claims"
   },
   "typeConfig": {
     "payloadContentType":"application/json",
     "functionPayload":"unfinalizationRequest"
   }
}

Dynamic Logic - unfinalizationRequest

Assuming that the claims code and finalize reason are provided as the invocation parameters the dynamic logic would look like

import groovy.json.JsonBuilder
import groovy.json.JsonSlurper
import javax.ws.rs.core.Response

def jsonPayload = JsonOutput.toJson([
  resource: [q: "code.eq(" + properties.get("claimcode") + ")"], resourceRepresentation: [expand: "all"]
])

Response claimsresponse = webTarget("claims")
  .path("generic").path("claims/search")
  .request()
  .header("Accept", "application/json)
    .buildPost(Entity.json(jsonPayload))
    .invoke()

def reasoncode = properties.get("reasonCode")

if (claimsresponse.status == 200) {
    (new JsonSlurper()
            .parseText(claimsresponse.readEntity(String.class)))
            .items.each { item ->
        // assign value to parameterized {claimId} by setting exchange property
        properties.put("claimId", item.id.toString())
        // construct unfinalization request
        def unfinalizationRequest = new JsonBuilder()
        def jsonBuilder = new JsonBuilder()
        def claimUnfinalizeReasons = new ArrayList()
        def unfinalizeReason = {
            unfinalizeReason {
                code reasoncode
            }
        }
        claimUnfinalizeReasons.add(unfinalizeReason)
        unfinalizationRequest {
            claimUnfinalizeReasonList(jsonBuilder.call(claimUnfinalizeReasons))
        }
        return  unfinalizationRequest.toString()
    }
}
return ""

Payload constructed by the dynamic logic

{
  "claimUnfinalizeReasonList": [
    {
      "unfinalizeReason": {
        "code": "<reason>"
      }
    }
  ]
}

Notification

Oracle Insurance Gateway expects notification from an Oracle Health Insurance application or from an external system to resume an integration invocation that is currently in waiting status. This notification can come in a custom format or in a specific format and must be received on the Integration Gateway’s notification endpoint. For more details on Notification, refer to the Notification Integration Point in the Developer Guide.