Submit an Authorization for Processing

Once an authorization is stored in Oracle Health Insurance Authorizations, it can be processed. HTTP API supports the starting of the authorizations processing with the operation Submit an Authorization for Processing.

For details about the authorizations processing refer section "Submit an Authorization for Processing" in the Developer Guide.

Not all authorizations are eligible for being processed, for example authorizations in the status 'Approved' are not. Whether an authorization can be processed or not, can be derived by the presence or absence of the "submit" link.

Resource representation of an authorization that can be submitted:

{
  ...  authorization properties ...
  "links": [
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/authorizations/",
      "rel": "self"
    },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/authorizations/{id}/submit",
      "rel": " authorization:submit"
      "httpMethod": "POST"
    }
  ]
}

In the resource representation of an authorization that can’t be submitted, the submit link is missing:

{
  ...  authorization properties ...
  "links": [
    {
    "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/authorizations/",
    "rel": "self"
    },
  ]
}
It is strongly recommended for clients to use the presence of the link for determining whether an authorization can be submitted or not. Clients should not "hard code" assumptions about authorizations being submittable. Clients that do make those assumptions may break when Oracle Health Insurance changes the implementation.

In regard to submitting an authorization, three use cases can be distinguished:

  • Use Case 1: The authorization is in a status where manual changes are possible. Submitting the authorization will bring it to the next status. Example: authorizations in status 'Entry'.

  • Use Case 2: The authorization is being processed right now, or the last processing has resulted in an error. Submitting the authorization is not possible. There is an additional link to the "status" resource which clients can use to monitor the processing or analyze the last error.

  • Use Case 3: The authorization has reached a valid end status. Submitting the authorization is not possible. Example: authorizations in status 'Approved'

The table below gives an overview:

Table 1. Submit an Authorization for Processing
Status of the authorization Eligible for Submit Link Status Resource Available

Entry

Yes

No

In Process

No

Yes

Pended

Yes

No

Changed

Yes

No

Approved

No

Yes

Denied

No

No

When an Authorization is not in Submittable(Entry, Change, Pended) Status, system returns ' AUT-IP-AUTI-020 : Authorizations in status {0} cannot be submitted' where {0} = status and when Authorization is in status Pended and user does have access rights to Resolve Pend Reason, system returns 'AUT-IP-AUTI-021 : Unresolved pend reasons exist and you need access rights to resolve them' .

When an authorization is currently being processed, or the last processing did not end in a valid end status, a status link is included:

{
  ...  authorization properties ...
  "links": [
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/authorizations/",
      "rel": "self"
    },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/authorizations/{id}/status",
      "rel": " authorization:status"
    }
  ]
}

Authorization with Pends

The system checks the access restrictions on the 'Process Steps' for the user submitting the authorization. The pends are marked resolved if the user has the required access. In case if the user does not have an access to resolve pends for the step in which the authorization has pended or for at least one process step when authorization is in the status Changed; the system returns '403 - Not Authorized'.

For details on "Pend resolution" refer section Evaluate Pend Rules of the Configuration Guide.

API Conversation and Interaction

The conversational and interaction style of this API is based on its asynchronous nature. The client of this API will become detached from the actual background process. The client can use the "status" resource (explained later) to monitor that background process. So the client of the API is not blocked, but rather is provided with the means to track progress in an asynchronous fashion.

When this process completes this means that either the authorization has been processed or that there were errors during processing. Both of these outcomes are made available/accessible for the consumer of this API.

Resources Used in this API

Authorization Resource

This is a singular resource representing an authorization. For more details about the representation, see Default Resource Representation (GET). The authorization resource contains the "submit" link or the link to the "status" resource.

Status Resource

These resources provide the basic elements with which submitting an authorization for processing can be fulfilled - including tracking progress and the ability to show processing errors. As these are individual states of the application, define the various link relations to allow a consumer to have a conversation with the system.

Link Relations Used in this API

In the case of submitting an authorization for processing, the following link relations are defined.

rel=" authorization:submit"

To eventually have an authorization - in the context of this link relation - processed by the system.

rel=" authorization:status"

To request the status of the current or last authorizations submit action.

rel="oi:reprocess"

To restart the processing of a failed task.

rel="self"

Link to the current resource. This for instance can be used on the status resource to periodically poll the resource for progress tracking.

rel="related"

This is a standard link relation to the related ( authorization) resource. This should be provided once the request is completed successfully.

Use Case

As said above, there are three different use cases. Two out of three support some operation to be triggered. In the third use case, the authorization is in valid end status, no operation can be triggered. Those use cases are described in the next sections.

Use Case 1: Authorization can be Submitted

The authorization is in a status where it freely can be submitted.

From a high level this use case can be visualized by the following diagram.

Http Api Long Operation Poll

  1. This shows an initial stage of an Authorization resource that was returned from some prior interaction at 0.

  2. The server has embedded the link relation for authorization:submit, with which a consumer of the API can interact with at 1.

  3. The server acknowledges this submission with a HTTP 201 (Created) message and sets a HTTP Location header to the Status resource at 2.

  4. The Status resource can subsequently be refreshed (that is, polled for) to track progress at 3 by a consumer of the API. A consumer can interrogate the Status resource’s mandatory "completed" attribute to find out whether it is (still) useful to refresh the Status resource.

  5. Note that the Status resource will have a link relation of rel="related" to identify the related resource that was affected by a completed process - see 4.

  6. In case of processing errors - that is, "progress" attribute failed - the Status resource contains an error property, which provides the detail of the issue(s).

Interaction Messages

The client requests an authorization. The authorization is returned like this:

{
  ...  authorization properties ...
  "links": [
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/authorizations/",
      "rel": "self"
    },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]authorizations/{id}/submit",
      "rel": " authorization:submit"
      "httpMethod": "POST"

    }
  ]
}

The client submits the authorization by calling POST on "http://[hostName]:[portNumber]/[api-context-root]authorizations/{id}/submit". The authorization processing is started, and the server responds with status 201. A link to the status resource is returned in the Location header like this:

Location: http://[hostName]:[portNumber]/[api-context-root]/authorizations/{id}/status

The clients can now track the progress by issuing a GET to the status URI returned in the Location header. While the authorization is being processed, the status resource will be returned like this:

{
  "progress": "processing",
  "completed": false,
  "links": [
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/authorizations/{id}/status",
      "rel": "self"
    },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/authorizations/",
      "rel": "related"
    }
  ]
}

When the processing ends successfully (no errors), the status resource will return:

{
  "progress": "succeeded",
  "completed": true,
  "links": [
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/authorizations/{id}/status",
      "rel": "self"
    },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/authorizations/",
      "rel": "related"
    }
  ]
}

When the processing ends unsuccessfully, the status resource returns:

{
  "progress": "failed",
  "completed": true,
  "o:errorDetails": [
    {
      "detail": "<detailed error message>",
      "instance": "http://[hostName]:[portNumber]/[api-context-root]/generic/tasks/"
      "links": [
        {
          "href": "http://[hostName]:[portNumber]/[api-context-root]/tasks/{id}/process",
          "rel": "oi:reprocess"
        }
      ]
    }
  ],
 "links": [
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/authorizations/{id}/status",
      "rel": "self"
    },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/authorizations/",
      "rel": "related"
    }
  ]
}

The "detailed error message" property shows the details of the technical error, identical to the "Details" field in in the View Technical Errors page.

Use Case 2: Authorization Cannot be Submitted, there is Status Information

The authorization resource representation will not include a "submit" link in this situation. Clients may however still send a payload against the submit URI (the client may hold a stale one, or construct the link themselves). When client does send a submit request, HTTP status code 409 is returned and the authorization is not submitted.

The authorization will include a status link that can be used to get the status information and restart the failed task(s).

Authorization

The operation in this section is protected by access restriction "authorizations.submit IP".