Provisioning Integration Point

This chapter describes the Provisioning Integration Point messages and how they are used by external interfaces to initially load user data copies into OHI applications and to keep the copies up-to-date.

Before Oracle Health Insurance applications can be accessed and data can be manipulated using any of the published interfaces (like the user interface or web services), an authenticated subject (or user) must be identifiable on the request. Users can authenticate using common mechanisms like Basic Authentication or OAuth2 or by using the application’s login page (i.e. authenticating 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. Note that the password of a user is not stored in Oracle Health Insurance applications.

The external interfaces will initially load details of all users from the source system(s) into the Oracle Health Insurance application through provisioning integration point message calls. Thereafter, they will monitor the source system(s) 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 system(s) can be handled by this integration point:

a new user is added
an existing user is changed
an existing user is deleted
an existing user is deactivated
a deactivated user is reactivated

See the use cases below for messages to be sent for each type of change in the source system(s).

Request Messages

Each request message may contain the details of one user. The external interfaces will 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 needs to 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 integration guide.

In order for an Oracle Health Insurance application to be able to recognize when an update to user details is 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), the attribute loginName is used. When the details of a user are received in a PUT message, the Oracle Health Insurance application will consider the details to be a new user if there is not already a user stored with the same loginName and it will consider 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. Please refer to the 'Response Messages' section in the HTTP API/IP Concepts part of the integration 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

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

Use Cases

Request Message Handling

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

Example End-to-End Scenario

This section includes several use cases that illustrate a possible end-to-end scenario for using the messages. This is only one of the possible scenarios that could be chosen. It is up to the developers of each external interface to determine how the messages will actually be used in their situation. The scenario that has been chosen here has the following characteristics:

the source system has timestamps indicating when users are created and updated and 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 / time that the interface starts running. For each of these users:
- 2. It creates and sends a PUT 'user request' message. Each message may include the user roles for this user.
- 3. The Oracle Health Insurance application processes the request message and stores the user completely or not at all.
- 4. 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 (i.e.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 / Update Users

This use case is a possible scenario for creation and update of users in a source system (following initial load). In this scenario:

New users are created in the source system. Previously sent users are updated.
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. All current details of each new user and changed details of updated users are included. The user request should always contain the complete list of the user roles. The existing list is replaced by the new list. If the list is not included at all no changes are made to the existing user roles.
- 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.
Users that were not successfully stored (i.e.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. Note: for auditing purposes it is not possible to delete a user that accessed the system. These users can be deactivated.

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 integration guide for more details).

Deactivate User

A user can be deactivated 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 deactivated. The user cannot login anymore.

Reactivate User

A user can be reactivated by sending a PUT user request message with loginName and active set to "true". All userRoles should be included also.