Documaker Integration

Purpose of this section is to explain how Oracle Insurance Gateway can be configured to mediate an exchange of Policies data and a Documaker document creation and publication. First a more detailed description is provided as to what type of interaction patterns are provided by this integration. After that information about the configuration is provided. Lastly how to trigger the exchange and how one could (optionally) deal with the result.

Detailed Description for Interactive Invocation

In this example an exchange for a configured integration called documakerdata is triggered to produce a specific document that uses member and policy data. In this case the member ID is passed as a parameter, on the withParameters sub-resource - like:

https://...//api/exchanges/integration/documakerdata/withParameters

 {
    "id" : "123"
 }

The Gateway then retrieves the member and policy data from Policies, transforms it to XML and sends it to the Documaker client.

The Documaker service that is configured in the integration by default is called in request/reply mode. This means that Oracle Insurance Gateway instructs Documaker to complete production and publication of a document in its entirety, before handing back control. Effectively this means that once the Documaker delivery step completes successfully, a document has been produced and published. In case a caller wants to shorten the time that Oracle Insurance Gateway worker threads are kept busy, an additional request parameter can be specified, like is shown below.

https://...//api/exchanges/integration/documakerdata/withParameters

 {
    "id" : "123",
    "fireAndForget" : true
 }

With this (fireAndForget) setting, Documaker is instructed to only accept a request for the production and publication of a document. As a consequence the system does not wait for that process to complete. Using this setting should be considered in cases where:

A caller "trusts" the system enough in that it produces and publishes requested documents, or
A caller wants to deal with querying and/or polling for the actual result in Documaker itself.

Alternatively the optional header parameter ohi-exchange-execute-immediately can be set to the value true. This results in the system executing all the configured steps for this exchange on the calling thread. Put differently - the client (e.g. a portal) that initiated this exchange blocks until the whole process completes. This provides the maximum level of control, from a caller perspective, at the potential cost of increased resource consumption.

Detailed Description for Non-interactive, Event-Based Invocation

The example description in the previous paragraph focuses on a Documaker interaction pattern which is triggered interactively, for example from a portal. It should be noted that it is also possible to have the Documaker integration be triggered non-interactively, from an event. A canonical example of this is an exchange that is triggered from a configurable the Oracle Health Insurance application event, where the event payload contains all required information for a Documaker extract payload to be constructed and be delivered to the Documaker web service. In this case this whole payload is passed to the exchange endpoint - like:

https://...//api/exchanges/integration/documakernewpolicy

Here documakernewpolicy is a fictitious name that reflects a configured integration, with a single 'DELI’very step. Part of that delivery step could be a transformation that takes the input payload, and turns that into a Documaker extract format.

Configuration

The configuration is done using HTTP APIs. The below steps are for an interactive invocation. Event based invocation, typically only requires a single delivery step.

The configuration steps are:

Configure Credentials for accessing Policies application with key POLICIES_BASIC.
Configure a Dynamic Logic dataTransformation that takes care of taking the query result from Policies and turning it into a Documaker readable extract.

Configure Destination DocumakerClient using /api/generic/documakerdestinations with method POST. The payload looks something like:

{
  "code"           : "DocumakerClient",
  "addressKey"     : "address.key.documaker.client",
  "credentialKey"  : "documaker.credential.key",
  "subtype"        : "DOCUMAKER",
  "typeConfig"     : {
       "fireAndForget" : "{fireAndForget}"
  }
}

In the above configuration block the address.key.documaker.client and documaker.credential.key (example) values have to be resolved through specified system properties. In this particular example the address.key.documaker.client system property specified, should refer to the Documaker SOAP 1.2 webservice endpoint. The documaker.credential.key refers to a system property pointing to a configured credential.

The Documaker webservice endpoint typically comes in two (2) flavors; a SOAP 1.1 version and a SOAP 1.2 version. From Oracle Insurance Gateway perspective, support for the SOAP 1.2 version is provided. This means that the system property for the destination to the Documaker webservice, needs to point to the SOAP 1.2 version. If instead the SOAP 1.1 version is configured, invoking an exchange that uses the Documaker client yields an unsupported media type error.

Configure the integration as follows:

{
  "code"             : "documakerdata",
  "integrationSteps" : [
    {
      "code"           : "QueryStep",
      "sequence"       : 1,
      "subtype"        : "QUERY",
      "credentialKey"  : "POLICIES_BASIC",
      "outputName"     : "data",
      "typeConfig"     : {
        "resourceName"    : "persons",
        "q"               : "id.eq({id})",
        "fields"          : "prefix.code|language.code|addressList.country.code|addressList.countryRegion.code",
        "expand"          : "addressList|maritalStatusList"
      }
    },
    {
      "code"           : "DataDelivery",
      "sequence"       : "2",
      "subtype"        : "DELIVERY",
      "functionTransformation": {
        "code"            : "dataTransformation"
      },
      "destination"           : {
          "code"          : "DocumakerClient"
      }
    }
  ]
}

Initiating an Exchange

Create an exchange for the documakerdata integration through an HTTP POST on /api/exchanges/integration/documakerdata using:

https://.../api/exchanges/integration/documakerdata/withParameters

The invoked integration collects data from policies using the Query Step.

The transformation dynamic logic is invoked with the following parameters

Parameter Name	Parameter Value
data	The JSON object as retrieved from policies
exchangeStep	Object that represents the exchange step for the transformation.
parameters	The map of key/value pairs that are used to invoke the integration configuration. Here a map with x and y.

Parameter Name

Parameter Value

data

The JSON object as retrieved from policies

exchangeStep

Object that represents the exchange step for the transformation.

parameters

The map of key/value pairs that are used to invoke the integration configuration. Here a map with x and y.

The response from the dynamic logic is delivered by the Documaker Client using the Destination configuration.

Optionally - Handling Exchange Result

Depending on how the Exchange was initiated (see introduction), a caller might need to deal with the Exchange result more explicitly. Information about the Documaker process, more specifically the Documaker JOB status and Documaker JOB ID can be retrieved via the exchange resource that is created as a result of initiating the exchange. The address of this created exchange is returned as an HTTP location header resulting an HTTP Post that completed with a status 200 OK. This segment looks something like this:

...
  "exchangeStepPayload": {
    "payloadType": "R",
    "rawPayload": "{\"documakerJobID\":1563397309374,\"documakerJobStatus\":999}"
  },
...