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
|
|
|
|
|
|
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:
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:
-
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:
-
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:
-
The Oracle Health Insurance application processes the request message and stores or updates the user completely or not at all.
-
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 (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).
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.