Submit a Policy for Processing

Once a policy is stored in Policies, it can be processed. HTTP API supports the starting of the policies processing with the operation Submit a Policy for Processing.

For details about the policies processing refer to "Process Policy" chapter of the Policies Operations Guide.

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

Resource representation of a policy that can be submitted:

{
  ... policy properties ...
  "links": [
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/policies/<id>",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/policies/<id>/submit",
      "rel": "policy:submit"
      "httpMethod": "POST"

    }
  ]
}

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

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

With regards to submitting a policy, three use cases can be distinguished:

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

  • Use Case 2: The policy is being processed right now, or the last processing has resulted in an error. Submitting the policy 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 policy has reached a valid end status. Submitting the policy is not possible. Example: policies in status 'Approved'

The table below gives an overview:

Table 1. Submit a Policy for Processing
Status of the policy Eligible for Submit Link Status Resource Available

Edit

Yes

No

In Process

No

Yes

Pended

Yes

No

Approved

No

Yes

Canceled

No

No

Pending File Approval

No

No

When a Policy is not in a Submittable status, system returns ' POL-IP-POLI-028 : Policy in status {0} cannot be submitted' where {0} = status and when Policy is in status Pended and user does have access rights to resolve pend reason, system returns 'POL-IP-POLI-027 : Unresolved pend reasons exist and you don’t have the privileges to resolve them' .

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

{
  ... policy properties ...
  "links": [
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/policies/<id>",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/policies/<id>/status",
      "rel": "policy:status"
    }
  ]
}

Policy in status Pended

The system checks the access restrictions on the 'Process Steps' for the user submitting the policy; 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 policy has pended or for at least one step when policy is in the status Edit; the system returns '403 - Not Authorized'.

For details on Pend resolution refer to section "Evaluate Pend Rules" of the Process Policy page in the Operations 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 policy 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

Policy Resource

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

Status Resource

These resources provide the basic elements with which submitting a policy for processing can be fulfilled - including tracking progress and the ability to show processing errors. As these are individual states of the application, we have to 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 a policy for processing, the following link relations are defined.

rel="policy:submit"

To eventually have a policy - in the context of this link relation - processed by the system.

rel="policy:status"

To request the status of the current or last policies 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 (policy) 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 policy is in valid end status, no operation can be triggered. Those use cases are described in the next sections.

Use Case 1: Policy can be Submitted

The policy 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 -Operation-submit

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

  2. The server has embedded the link relation for policy: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 a policy. The policy is returned like this:

{
  ... policy properties ...
  "links": [
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/policies/<id>",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/policies/<id>/submit",
      "rel": "policy:submit"
      "httpMethod": "POST"

    }
  ]
}

The client submits the policy by calling POST on "api-context-root/policies/<id>/submit". The policy 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://<host>:<port>/[api-context-root]/policies/<id>/status

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

{
  "progress": "processing",
  "completed": false,
  "links": [
    {
      "href": "http://<host>:<port>/[api-context-root]/policies/<id>/status",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/policies/<id>",
      "rel": "related"
    }
  ]
}

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

{
  "progress": "succeeded",
  "completed": true,
  "links": [
    {
      "href": "http://<host>:<port>/[api-context-root]/policies/<id>/status",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/policies/<id>",
      "rel": "related"
    }
  ]
}

When the processing ends unsuccessfully, the status resource returns:

{
  "progress": "failed",
  "completed": true,
  "o:errorDetails": [
    {
      "detail": "<detailed activity message 1>",
      "o:errorCode": ""

    },
    {
      "detail": "<detailed activity message 2>",
      "o:errorCode": ""
    }
  ],
 "links": [
    {
      "href": "http://<host>:<port>/[api-context-root]/policies/<id>/status",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/policies/<id>",
      "rel": "related"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/activities/<id>/recover",
      "rel": "oi:reprocess"
    }
  ]
}

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

The policy 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 policy is not submitted.

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

Authorization

The operation "Submit a Policy for Processing" is protected by access restriction "policies.submit IP".

Submit and Apply Registrations (AU Specific)

It is possible to trigger the process and apply registrations immediately after the submit by enabling "process and apply registrations" request header parameter on the submit policy request.

When a policy is in the edit status the user can select from any of the following:

  • Submit the policy for processing without setting the "process and apply registrations " header parameter (false by default).

  • Submit the policy by setting the request header parameter "process and apply registrations" to "true"

A POST request initiates the request to submit the policy with the URI /policies/submit with the option of setting the following parameter:

header - processandapplyregistrations: true

The process and apply registration requires the following three additional request header parameters to be processed once its set to true:

header - finTransDynLogic: "...",
header - comFinTransDynLogic: "...",
header - disableRevGrouping: true
The registrations get applied only if the policy reaches the approved status, the system processes and applies registrations for that policy. If the policy does not reach the approved status, i.e., if it pends, then no registrations get applied.

Response

This operation will provide HTTP status codes as defined in Response Messages. If successful,HTTP Status 201 is returned together with a resource representation of the policy. If an error occurs, appropriate HTTP status code is returned along with the error details.

This functionality is specific to Australian environment only.