Users (Provisioning)

This API enables external interfaces 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 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.

Operations

PUT

/users creates or updates a person.

GET

/persons/{loginName} retrieves the user.

DELETE

/persons/{loginName} deletes the user

Rules

Create or Update Behavior

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.

Request Messages

The system accepts the user’s request message in the following format:

User Request Message (click to open) 
{
   "loginName" : ""
  ,"alternateUserIdentifier" : ""
  ,"displayName" : ""
  ,"countryCode" : ""
  ,"languageCode" : ""
  ,"active" : ""
  ,"userRoleList" : [ "accessRoleCode1", "accessRoleCode2" ]
}
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

Oracle Health Insurance creates a response message 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.

Error Messages

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

Table 1. Error 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

Use Cases

This section illustrates some example use cases.

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

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

Revoke a Role from an Existing User

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

Delete User

Delete a user by sending a DELETE 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

De-activate a user 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

Re-activate a user 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.

Batches

Each request message may contain the details of one user.

Authorization

The integration point is protected by the provisioning IP access restriction.