Provisioning Integration Point

This chapter describes the Provisioning Integration Point messages and how external interfaces can use it to initially load user data copies into the Oracle Health Insurance applications and keep the copies up-to-date.

Before Oracle Health Insurance applications can be accessed and data can be manipulated using any published interfaces (like the user interface or web services), an authenticated subject (or user) must be identifiable on the request. Users can be authenticated using common mechanisms like Basic Authentication or OAuth2 or by using the application’s login page (that is authentication by using a valid combination of username and password).

The data available for authorization is stored internally in Oracle Health Insurance applications. This data is maintained by external (not part of Oracle Health Insurance applications) interfaces using provisioning integration point messages. This data consists of user data and user role data. The password of a user is not stored in Oracle Health Insurance applications.

The external interfaces initially load details of all users from the source systems into the Oracle Health Insurance application through provisioning integration point message calls. Thereafter, the external systems monitor the source systems for changes and make appropriate message calls to synchronize the authorization data stored in the Oracle Health Insurance application. Different types of changes in the source systems can be handled by this integration point:

• a user is added

• a user is changed

• a user is deleted

• a user is activated

• a user is de-activated

See the use cases below for messages to be sent for each type of change in the source systems.

Request Messages

Each request message may contain the details of one user. The external interfaces create request messages for the initial data load and in response to entry of new users and updates to previously sent users.

The details of exactly what information should be in a given request message varies based on factors such as whether details have been sent before and the category of details that have been added or updated. For details on how values in the request messages are handled, refer to the "Property Representation and Handling" section in the HTTP API/IP Concepts part of the Developer Guide.

The attribute loginName is used for an Oracle Health Insurance application to be able to recognize when an update to user details are being sent (as opposed to the details of a new user) and to know which user in an Oracle Health Insurance application is to be updated (or deleted). When the details of a user are received in a PUT message, the Oracle Health Insurance application considers the details to be a new user if there is not already a user stored with the same loginName, and it considers the details to be an update to an existing user if there is one with the same loginName.

User request messages have the following structure:

{
   "loginName" : ""
  ,"alternateUserIdentifier" : ""
  ,"displayName" : ""
  ,"countryCode" : ""
  ,"languageCode" : ""
  ,"active" : ""
  ,"userRoleList" : [ "accessRoleCode1", "accessRoleCode2" ]
}

The loginName is the primary, unique way to identify a user. Its value may be displayed in user interface pages.

The alternateUserIdentifier attribute provides an alternative way to uniquely identify a user. Its main use case is to support OAuth2 or JWT tokens in which users are identified by non-functional or technical unique identifiers.

Response Messages

Response messages are created by the Oracle Health Insurance application in response to request messages received from external interfaces. Refer to the "Response Messages" section in the HTTP API/IP Concepts part of the Developer Guide for more details.

The following error messages that are specific to this integration point can be returned in the response messages:

Code	Severity	Message
OHI-IP-USER-002	Fatal	Country code {code} is unknown
OHI-IP-USER-003	Fatal	Language code {code} is unknown
OHI-IP-USER-005	Fatal	Access role code {code} is unknown
OHI-IP-USER-006	Fatal	Login name must be specified
OHI-IP-USER-007	Fatal	Login name cannot hold leading or trailing spaces

Request Message Handling

For detailed examples and use cases related to the messages that can be created by external interfaces and how they are handled by Oracle Health Insurance applications, refer to the "Property Representation and Handling" section in the HTTP API/IP Concepts part of the Developer Guide.

Use Cases

This section illustrates some example use cases.

In these use cases:

• the source system has timestamps indicating when users are created and updated and when roles are granted or revoked;

• the source system uses logical delete for users and user roles;

• not every interim update of the source system needs to be copied to the Oracle Health Insurance application (for example, if a non 'time value' attribute of a user was updated twice between two 'runs' of the interface, only the second value would be communicated to the Oracle Health Insurance application);

• historic details are not to be copied to the Oracle Health Insurance application.

Initial Load of Users

This use case is a possible scenario for the initial load of users from a source system to an Oracle Health Insurance application.

In this scenario:

• The external interface selects each active user in the source system that was created or last updated before the date or time that the interface starts running. For each of these users:

  • It creates and sends a PUT 'user request' message. Each message may include the user roles for this user.

  • The Oracle Health Insurance application processes the request message and stores the user completely or not at all.

  • The Oracle Health Insurance application returns a response message with a result code indicating if the user has been stored or not.

• Users that were not successfully stored (that is, where the response message contained an error) are corrected in the source system and will be picked up by the next 'run' of the interface.

Create or Update Users

This use case is a possible scenario for creation and update of users in a source system following the initial load.

In this scenario:

1. New users are created in the source system. Previously sent users are updated.

2. The external interface is 'run' to select new records and updates made between the last run date/time and current run date/time. For each new and updated user:

   1. The interface creates and sends a PUT user request message.

      When a user is updated, the user role details in the request message are matched with the existing user role details based on the access role code. User roles in the request that do not match with an existing user role are inserted. Existing user roles that do not match with a user role in the request are deleted. If the user role list element is not included, no changes to existing user roles are made. If an empty user role list element is included, all current user roles are removed. This applies to the following lists of details:

   2. The Oracle Health Insurance application processes the request message and stores or updates the user completely or not at all.

   3. The Oracle Health Insurance application creates a response message for each request message with a result code indicating if the user has been stored/updated or not.

3. Users that were not successfully stored (that is where the response message contained an error) are corrected in the source system and will be picked up by the next 'run' of the interface.

Add a Role to an Existing User

A role can be added to an existing user by sending a PUT user request message with loginName and all userRoles, including the new role.

Revoke a Role from an Existing User

A role can be revoked from an existing user by sending a PUT user request message with loginName and all userRoles, excluding the one to be deleted.

Delete User

A user can be deleted by sending a DELETE user request message with the loginName specified in the URI. The user and his roles are physically deleted from the Oracle Health Insurance application.

If a user with the specified loginName does not exist, a 'HTTP 404 Not Found' status code is returned (please refer to the "Response Messages" section in the HTTP API/IP Concepts part of the Developer Guide for more details).

De-activate User

A user can be de-activated by sending a PUT user request message with loginName and active set to "false". User and UserRole data are retained in the Oracle Health Insurance application, but the user account is de-activated. The user cannot login anymore.

Re-activate User

A user can be re-activated by sending a PUT user request message with loginName and active set to "true".

Auditing

The system audits creation, deletion, activating and de-activating of the user and changes to the user roles. It writes audit records to the user role history. The userRoleHistory list is part of the response message. The userRoleHistory can not be set as part of a PUT request. Deleting a user does not delete the userRoleHistory for that user.