Submit a Policy for Processing

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

Note: For details about the policies processing refer to section 'Policy Processing' in the Policies 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/",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/policies//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/",
    "rel": "self"
    },
  ]
}

Warning: 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 OHI 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:

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

Status of the policy

Eligible for Submit

Link Status Resource Available

Edit

Yes

In Process

Yes

Pended

Yes

Approved

Yes

Canceled

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/",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/policies//status",
      "rel": "policy:status"
    }
  ]
}

Policy with Pends

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 Guide.

API Conversation & 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

This shows an initial stage of a Policy resource that was returned from some prior interaction at 0.
The server has embedded the link relation for policy:submit, with which a consumer of the API can interact with at 1.
The server acknowledges this submission with a HTTP 201 (Created) message and sets a HTTP Location header to the Status resource at 2.
The Status resource can subsequently be refreshed (i.e. 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.
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.
In case of processing errors - i.e. "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/",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/policies//submit",
      "rel": "policy:submit"
      "httpMethod": "POST"

    }
  ]
}

The client submits the policy by calling POST on "http://<host>:<port>/[api-context-root]/policies//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//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//status",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/policies/",
      "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//status",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/policies/",
      "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//status",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/policies/",
      "rel": "related"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/activities//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".