Policy Update Requests Integration Point

This integration point creates a policy update request. An update request creates a new or maintains an existing policy. The integration point accepts an online request for a single update request or a data file with a set of policy update requests.

After the integration point creates an update request, it adds each update request to a processing queue to process in the order in which the integration point receives them. Each request in the queue either creates a new policy or updates an existing one.

See Policy Update Requests Process for more information on processing a queued update request.

The integration point does not remove or cancel a policy through a policy update request.

We recommend uploading files with sizes under 20 MB. Larger files impact the stability of the system.

Online Request Message

The following request enables an external system to create a new policy update request object and adds the update request to a queue for processing.

PUT http://[hostName]:[portNumber]/[api-context-root]/policyupdaterequests`

Each request message contains the details of a single policy.

The integration point accepts the same payload as the Policy In Integration Point.

Submit for Processing

This request enables an external system to save or save-and-submit a policy after picking up an update request from the queue.

The submit header is optional and is false by default. The header determines whether the integration point submits the policy after successfully applying the update.

header - submit: true

Creating a Policy Update Request

After the successful initial validation, the integration point creates a policy update request with the following information:

Table 1. Creating a Policy Update Request
Field name Value

Policy Gid

The integration point sets the value of this field to the matched policy gid if one exits. When unable to identify a matching policy in the application, the integration point sets the value of this field to empty when creating the update request.

Enrollment File

Reference to the enrollment file that is part of the request.

If the enrollment file is missing from the OHI policies the integration point creates a new enrollment file with the specified name.

Line Of Business

Reference to the line of business. The integration point sets the value of this field based on the value available in the request payload. For a missing value in the request payload, the integration point sets the value of this field to the value of the line of business of the matched policy.

Brand

Reference to the brand. The integration point sets the value of this field based on the value available in the request payload. For missing value in the payload, the integration point sets this field’s value to the matched policy’s brand.

Group Client

Reference to the group client. The integration point sets this value to the group client of the linked group account.

Group Account

Reference to the group account value available in the request payload.

Data Access Group

Reference to the data access group. The integration point sets the value of this field based on the value available in the request payload. For missing value in the request payload, the integration point sets the field value to the data access group value of the matched policy.

Payload

The request payload.

Mime Type

The payload of the mime type.

Submit Policy?

The integration point sets this value based on the value of the submit header.

Process Status

This value is Queued by default. See additional checks for more details.

Policy Identifier Type

Reference to policy identifier type. The integration point sets the value of this field based on the value of the request payload.

Matched Policy Code

This is the policy code of the matched policy. This field populates only when the integration point finds a matching policy in the application. The matched policy code is irrespective of the policy code in the payload.

Policy Matching

The Policy Matching process identifies a matching policy in the application and updates the policy gid in the update request. The policy Code and identifier determine whether the update request is for a new policy or an update to an existing one. If the integration point identifies a matching policy in the application, it updates the value of the policyGid field in the update request with the gid of the policy. See policy matching for more details.

If any error occurs during the matching process, the integration point sets the policy update request to a Failed status, the last update failed status to True, and the error details attached to the policy update request history.

Additional Validations

While creating the policy update request, the integration point performs the following validations:

Validate Reference Properties

If an unidentified group account, data access group, brand, or line of business is part of the payload:

  • The integration point marks the update request as Failed to prevent further processing.

  • The integration point links the error details to the policy update request history.

  • The integration point sets the last update failed status to true on the policy update request.

  • If the policy gid has a value present in the policy update request, the integration point sets the policy.attachedpolicydata.disableUpdateFromQueue? value to true for the matched policy.

Rejected Enrollment File

If a policy update request has reference to an already rejected enrollment file, the integration point sets the update request status as Rejected.

Authorization

A user authorization configuration protects access to this request. The relevant access restriction is Policy Update Request IP.

Response Message

The integration point returns appropriate response messages to the request it receives from external interfaces. See "Response Messages" in the HTTP API/IP Concepts section of the Developer Guide for more details.

File Request

This process request handles multiple policy update requests in the same request payload. The file request process relies on data file sets to import the significant volume of the policy update request payload into the application to read and process data. See Data File Set Integration Point for additional information on how to create a data file set.

All data files have <policies> as their root element. See Policy In Integration Point for the file structure. Both policies in and policy update request IP have the same file structure for file requests.

The following request starts the import process for policy update requests in a data file:

POST http://[hostName]:[portNumber]/[api-context-root]/writepolicyupdaterequests

The policy update batch request has the following structure:

{
 "dataFileSetCode" : "...",
 "submit" : "...",
 "groupClientCode" : "...",
 "enrollmentFileName" : "...",
 "responseDataFileSetCode" : "..."
}

The response data file set holds the results of the file payload.

The responseDataFileSetCode is an optional attribute. The optional submit flag in the payload determines the value of the submit flag on the new policy update request.

If there is no enrollment file with the specified enrollmentFileName, then the integration point creates a new enrollment file with the specified name and a reference to the group client with the groupClientCode.

  • The submit flag is false by default.

  • The groupClientCode is relevant only when creating a new enrollment file.

Creating Policy Update Requests from a Data File

The integration point creates individual policy update requests for each <policy> element within the data file. While the import process is running, the status for all the newly-created policy update requests is kept as Initial to prevent the update requests from being picked up for processing. After the import process has been completed, the status for the newly-created policy update requests is changed to Queued, that is ready to pick up for processing.

See Creating a Policy Update Request for additional details on the policy matching, validations, and how attribute values are set for the new policy update requests.

Authorization

A user authorization configuration protects access to this request. The relevant access restriction is Policy Update Request Batch IP.

File Response

There are different ways to track the progress of the import process. One of them is to subscribe to a notification event. A pre-configured endpoint receives a notification message.

The notification endpoint configures on ohi.activityprocessing.notification.endpoint.POLICY_UPDATE_REQUEST_IMPORT or to a more generic endpoint ohi.activityprocessing.notification.endpoint.

Configuring a notification endpoint on the specific POLICY_UPDATE_REQUEST_IMPORT fetches all the related properties like media type, authentication, etc., based on POLICY_UPDATE_REQUEST_IMPORT, or else uses defaults. Similarly, configuring an endpoint for the notification without the specific code fetches all other properties on a generic use case code ActivityNotificationClient. See "Outbound RESTful Service Invocations" in the Security Guide section for the process and more properties.

The chapter "Long Running Operations through REST" in the Developer Guide describes the common notification structure of the notification message.

The response notification includes a data file set link of the completed writepolicyupdaterequests request containing messages (fatal or info) for each Policy Update Request it imports.

The integration responds with HTTP 201 (created) and a location header for the long-running operation.