Property Representation and Handling (PUT, POST, PATCH)

Each resource representation contains data values of a root element (e.g. organization or organization provider) that have been created or updated in a source system. Within representation are several categories of data such as simple entity-level properties, lists of non-time valid details and lists of time-valid details, dynamic fields and dynamic records. This section describes how each category of data is handled by Oracle Health Insurance applications and also covers guidelines for handling differences in data categories between source systems and Oracle Health Insurance applications.

The way that an Oracle Health Insurance application handles requests is based on the principle that the copy of information in the Oracle Health Insurance application is to be kept up-to-date with the (master) information in the system of record. It is not required that the Oracle Health Insurance application is informed of every update in the system of record; only the values at the time of creating the requests are important. For example, if an interface periodically creates requests for all outstanding additions and updates, only the values of source system data at the time that the interface is run, need to be sent. Whether a record has been updated several times or once since the last interface run is irrelevant.

If an existing record is sent again and it contains the exact same data(except multi-value, time-valid dynamic fields and dynamic records) that is already stored in the system, the existing data will not be updated. This means that the audit columns in the database will also remain unchanged.

Note

In this document, "properties" and "attributes" are considered synonyms.

Incomplete Resource Representation

Resource representation sent to Oracle Health Insurance components need not be complete. For example, if the claims resource has 100 possible properties, it is perfectly possible to send in just 10. The HTTP API will only process the properties that are present in the resource representation it received. Properties that are not included will not be touched. The same goes for sub resources, only the included sub resources are processed.

Note

It may be possible that Oracle Health Insurance Components does fill properties that are not present. Examples are the audit columns and default values that are applied during a POST. This has however nothing to do with HTTP API. The principle of HTTP API is: do not process/change anything that was not in the resource representation sent in.

Clearing values

As said, non present properties are not processed. Oracle Health Insurance Components does not set properties that are not present to null. When a property must be cleared, it must be explicitly sent in with an empty value.

Clear "languagePreferred" in XML:

<organization
  id="123"
  languagePreferred=""
  objectVersionNumber="<some value>"
/>

Clear "languagePreferred" in (JSON-format)

{
  "id" : "123",
  "languagePreferred" : "",
  "objectVersionNumber" : "<some value>"
}

Note

Please note that direct attributes cannot be cleared using 'null', for that empty quotes should be used.

For multi valued and/or time valid properties, an empty array must be used. Example for clearing the "claimMessages" of a claim.

{
  "id" : "123",
  "objectVersionNumber" : "<some value>"
  "claimMessages" : {}
}

Identification

For every resource and sub resource that is present in an incoming resource representation, Oracle Health Insurance Components needs both "id" and "objectVersionNumber". The "id" is needed to find the matching database record, the "objectVersionNumber" is used for optimistic locking.

Example: both a field of the claim and the claim line resource must be changed:

{
  "id" : "",
  "objectVersionNumber" : "<object version number of the claim>",
  "claimLineList" : [
    {
      "id" : "",
      "objectVersionNumber" : "<object version number of claim line 1>"
    },
    {
      "id" : "",
      "objectVersionNumber" : "<object version number of claim line 2>"
    }
  ]
}

"id" and "objectVersionNumber" are included by HTTP API in each resource representation it creates. It is important that clients return them unmodified. Changing them on the client side is not supported.

The next sections describe how each property type is processed when it is present in an incoming resource representation as part of POST, PUT, or PATCH processing.

Single Value Properties

Basic Properties (Single Value)

The basic properties can be sent it with their new value or the empty value ("'). The new value should match the format as described in the section Property Representation (GET)

Amount and Currency

In some cases the currency is derived. In that situation, the "currency" can be left out. For example:

{
  requestedAmount : {
    amount="100"
  }
}

Note

If the currency is derived, and the currency is included in the payload as well, HTTP API will ignore the payload value and use the derived currency

Reference Properties (Single Value)

For a reference property, the new "id" value can be supplied. The example below assigns an another location type to a claim:

{
  "id" : "",
  "objectVersionNumber" : "<object version number of the claim>",
  "locationType": {
    "id" : ""
  }
}

It is also possible to use another attribute of the linked resource, like "code":

{
  "id" : "",
  "objectVersionNumber" : "<object version number of the claim>",
  "locationType": {
    "code" : "<code of the new location type to be assigned to the claim>"
  }
}

Or use a combination of attributes that together uniquely identify the linked resource:

{
  "id" : "",
  "objectVersionNumber" : "<object version number of the claim>",
  "locationProvider": {
    "name" : "<name of the new location provider to be assigned to the claim>",
    "startDate" : "<startDate of the new location provider to be assigned to the claim>"
  }
}

Note

For sub type based references, only id or code based lookup will yield results, combination of attributes will not yield any lookup result.

HTTP API/IP can only successfully process this payload if "name" and "startDate" result in a single matching provider. If that’s not the case, an error is returned:

Linked resource not uniquely identified for {0}

{0} is substituted with the property name, for example "locationProvider"

Clearing a reference, in this case the locationType can be done by supplying the "" :

{
  "id" : "",
  "objectVersionNumber" : "<object version number of the claim>",
  "locationType": ""
}

As described in the section Property Representation (GET), a reference resource is represented as:

"<propertyName>": {
    "links": [
        {
            "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/{referenceCollection}/{id}",
            "rel": "canonical"
        }
    ]
}

Clients can return the resource representation they received with a GET, without changing the reference resource like this:

{
  "id" : "",
  "objectVersionNumber" : "<object version number of the claim>",
  "brand": {
      "links": [
          {
              "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/brands/{id}",
              "rel": "canonical"
          }
      ]
  }
}

In this case, HTTP API will notice the brand property did not change, and will not process it.

Insurable Entity referencing Properties

Those properties are handled exactly the same as "normal" reference properties. Everything that is described in the previous section is valid for insurable entities as well.

Flex Code based Properties Flex Code Set, Diagnosis,

Procedure and Provider (Single Value)

Those properties can be changed by sending them in with new values for "flexCodeSystem" and/or "value". Please note that if 'value' is omitted from the payload, the property is nullified/deleted.

{
  "id" : "",
  "objectVersionNumber" : "<object version number of the claim>",
  "<propertyName>": {
    "flexCodeSystem": {
       "code" : "<new code of the flex code definition>"
    },
    "value": "<new flex code>"
  }
}

It is possible to leave out "flexCodeDefinitionCode" if "value" uniquely identifies the flex code:

{
  "id" : "",
  "objectVersionNumber" : "<object version number of the claim>",
  "<propertyName>": {
    "value": "<new flex code>"
  }
}

If no single matching flex code is found, the same error is returned as for a "normal" reference property:

Linked resource not uniquely identified for {0}

Flex Code based Properties (Single Value)

Everything described in the previous section Flex Code based Properties Diagnosis, Procedure and Provider (Single Value) applies to flex code based properties as well.

Dynamic Record (Single Value)

Single value dynamic records can be sent in with the new values in the format of the dynamic record and its properties.

A single dynamic record can be cleared by sending in the empty value:

{
  "id" : "",
  "objectVersionNumber" : "<object version number of the claim>",
  "<dynamic record usage name>": ""
}

Multi Value Properties

Multi value properties are just an array of single value properties. See the next sections for examples.

Basic Properties (Multi Value)

Clients can just send in the new values like this:

"extractedTeeth" : [3,1,9],
"visitedStates" : ["AZ", "AR"]

The new values completely replace the existing values.

A multi value property can be cleared by sending an empty array:

"extractedTeeth" : [],
"visitedStates" : []

Flex Code based Properties Flex Code Set, Diagnosis, Procedure and Provider

(Multi Value)

The new values can be sent in in an array:

"<multi value propertyName>":
  [{
    "flexCodeDefinitionCode": "<new code of the first flex code definition>",
    "value": "<new first flex code>"
  }, {
    "flexCodeDefinitionCode": "<new code of the second flex code definition>",
    "value": "<new second flex code>"
  ]
}]

The new values completely replace the existing values.

A multi value reference property can also be cleared by sending an empty array:

Flex Code based Properties (Multi Value)

Everything of the previous section applies here as well.

Dynamic Record (Multi Value)

The new dynamic records can be sent in as an array. The new values will completely replace the existing values if the operation is PUT. If the new values are exactly same as old values, nothing will be replaced

For PATCH, only records present in the workload are processed, identical to a PATCH operation on a sub resource. See HTTP API PATCH for an example.

Time Valid Properties

Time valid properties have to be send in as an array. This applies to both single value time valid and multi value time valid properties. The new values completely replace the existing values. If the new values are exactly same as old values, nothing will be replaced. Every array element includes properties "startDate" (mandatory) and "endDate".

Some examples are given:

"<time valid flexCode>":
  [{
    "startDate": "2015-12-05",
    "endDate": "2015-12-21",
    "flexCodeDefinitionCode": "<code of the flex code definition>",
    "value": "<flex code>"
  }, {
    "startDate": "2016-12-05",
    "flexCodeDefinitionCode": "<code of the flex code definition>",
    "value": "<flex code>"
  ]
}]

"<property name of time valid string>": [
  {
    "startDate": "2016-11-05",
    "endDate": "2016-11-21",
    "value": "B"
  },
  {
    "startDate": "2016-12-05",
    "endDate": "2016-12-21",
    "value": "C"
 }
]

PUT/PATCH: SubResources

As explained above matching will be performed on id and object version number, if these are not present, that is a match could not be found, then the details are deleted by omission. So if they are not present in the request, they will be deleted and what is present will be inserted.