Policy Account Integration Point
Three integration points allow external systems to create, modify or retrieve information related to policy accounts and policy account transactions.
The Policy Account integration point supports
-
Create a policy account
-
Update dynamic fields of a policy account
-
Fetch a policy account
The Policy Account Transaction integration point supports
-
Create a policy account transaction for an existing policy account
-
Fetch policy account transactions of a policy account
The Policy Account Transaction List integration point supports
-
Create policy account transactions for a list of existing policy accounts
Note that it is not possible to delete a policy account or a policy account transaction through these integration points.
Create or Update Policy Accounts and Policy Account Transactions?
The external system can send a request to create or modify policy accounts and/or policy account transactions to a URL. For details on how values in the request messages are handled when a policy account is created or updated, refer to the concepts in the Developer Guide.
The external system also can send a file to create policy account transactions using the data file interface. Please refer to the 'File Based Import' section in the HTTP API Integration Points part of the Common Features book for more details.
Matching
Policy Accounts
The policy account number and the combination of policy, account definition and person drive whether a policy account is created or an existing policy account is updated.
-
If the account number and the combination of policy, account definition and person do not exist then a new policy account with the provided account number is added to the system.
-
If the account number already exists or the combination of policy, account definition and person already exists then the policy account’s details are updated as per the data provided in the request. Note that only the dynamic fields of the policy account can be updated.
Policy Account Transactions
The policy account transaction code drives whether only a new transaction needs to be created or that also an older transaction needs to be reversed. If the policy account transaction code does not exist, a new policy account transaction with the provided code is added to the system. If the account transaction code exists then the new account transaction is created and the existing transaction is reversed.
Policy account transactions are not updated by the integration point.
Policy Account
Create Policy Account
The external system can send a PUT request to create or modify a policy account to the URL: http://{base URL}/api/policyaccounts. The system accepts the request in the following format:
<policyAccount accountNumber="" policyAccountDefinitionCode="" policyCode="" personCode="" />
If the policy account does not exist it is created. If the PolicyAccountDefinitionCode or policyCode is empty, fatal message POL-IP-POLA-004 is raised.
The following values are set by default:
-
If the account number is empty, a new account number is generated by using the dynamic logic function defined for this purpose on the account definition.
The following rules apply:
-
A policy account can only be created if the policy (enrollment) has at least one enrollment product that specifies the account definition
-
A policy account with the period definition Group Account can only be created if (any version of) the policy is for a group account
-
A policy account can only refer to a person if the account definition is of level Person.
-
A policy account can only refer to a person that is enrolled on (any version of) on the policy account’s policy
-
If the message holds a policy account with an account number, policy code, account definition and person and in the system a policy account exists with either the same account number or the same combination of policy code, account definition and person but not in this combination, fatal message POL-IP-POLA-003 is raised.
For every policy account that is successfully created or updated, the system sends a response message in the same format as the request message.
Fetch a Policy Account
The external system can fetch a policy account and its balance by posting a request to the URL:http://{base URL}/api/policyaccounts.
Example:
GET http://{__contextroot__}/api/policyaccounts?accountNumber
="<accountNumber>"&policyCode="<policyCode>"&personCode=<personCode>&accountDefinitionCode=<accountDefinitionCode>&startDate=<startDate>&asOfDate=<asOfDate>&accountTransactionType=<accountTransactionType>
??
Either the account number or the combination policy code / account definition or the combination of policy code / account definition / person code are used to find the policy account.
-
If the account number is specified, only the account number is used to find the policy account.
-
If the account number is not specified, the combination of the policy, account definition and person code is used to find the policy account.
-
If the account definition’s level is Policy, then only the policy and account definition codes are used to find a matching policy account.
-
If the account definition’s level is Person, then the policy, account definition and person codes are used to find a matching policy account.
-
If account number and the combination of policy, account definition and person are filled, the system does not check the correctness of the combination. |
If the accountTransactionType is provided in the request, the system will return the balance based only on the transactions of that transaction type. If no accountTransactionType is provided, all transaction types are included in calculating the account balance.
The startDate specifies the start date of a timeframe for selecting transactions in policy accounts with no time periods. This parameter is ignored for accounts with other time period definitions. For those accounts, the start date of the returned balance is always based on the applicable time period defined on the policy account.
The asOfDate specifies, in combination with the policy account definition period, the time period for which the transactions are included in the calculation of the account balance. If the asOfDate is omitted, the account balance for the system date is returned. All not-reversed transactions in a specific time period are included in the balance, not only the ones that have a transaction date that lays before the as-of date.
If no policy account transaction is found, the returned balance is 0.
Example
If time period CY2015 is from 01-Jan-2015 to 31-Dec-2015 and time period CY2016 is from 01-Jan-2015 to 31-Dec-2016 and the following transactions exist in the system:
Transaction Date |
Transaction Amount |
Transaction Type |
Time Period |
1-Jul-2015 |
400 |
PREM |
CY2015 |
8-Sep-2015 |
-380 |
CLA |
|
1-Oct-2015 |
400 |
PREM |
|
1-Jan-2016 |
500 |
PREM |
CY2016 |
15-Feb-2016 |
-450 |
CLA |
If the request holds no transaction type the balance for any as-of date if is in 2015 is 420; the balance for any as-of date in 2016 is 50.
If the request is for the 'PREM' transaction type the balance for any as-of date if is in 2015 is 800; the balance for any as-of date in 2016 is 500.
See the Accounts section of the View and Edit Policy documentation for a description of how the account balance and the start- and end date of a policy balance are derived.
Once the request is acknowledged, the system processes the request and generates the response in the following format.
<policyAccountBalance accountNumber="" accountBalance="" balancePeriodStartDate="" balancePeriodEndDate="" />
Policy Account Transaction
Create Policy Account Transaction for an Existing Policy Account
An external system can create a policy account transaction for an existing policy account by posting a request to the URL: http://{base URL}/api//policyaccounttransactions.
The system accepts the request in the following format:
<policyAccountTransaction code="" descr="" policyAccountTransactionTypeCode="" personCode=""> <amount/> <transactionDateTime>YYYY-MM-DDTHH:MM:SS</transactionDateTime> <policyAccount/> </policyAccountTransaction>
Each element that represents an amount holds a fixed set of attributes. Consider the element below to clarify:
... <amount currency="USD">50</amount> ..
If the policy account transaction does not exist it is created.
-
If the account transaction code is empty, a new account transaction code is generated by dynamic logic function that is referenced by the policy account definition.
-
The transaction is by default created as not reversed, the reversal transaction date is empty
-
The currency of the amount must be the same as the currency of the policy account definition. If they are not the same the fatal message POL-IP-POLT-004 is raised.
-
The <policyAccount> element must contain attributes for either the account number or a combination of policy, account definition and person or both.
-
If the policy account is not found the fatal message POL-IP-POLT-003 is raised.
-
If the account number is not specified, the combination of the policy, account definition and person code is used to find the policy account instead.
-
If the account definition’s level is Policy, then the only policy and account definition codes are used to find a matching policy account.
-
If the account definition’s level is Person, then the policy, account definition and person codes are used to find a matching policy account. If the person code is empty, fatal message POL-IP-POLT-005 is raised.
If the policy account is not found the fatal message POL-IP-POLT-003 is raised.
-
-
If account number and the combination of policy, account definition and person are filled, the system does not check the correctness of the combination.
-
The following rules apply:
-
A policy account transaction can only refer to a person that is enrolled on (any version of) the policy account’s policy. A policy account transaction can only refer to a person if the account definition is of level Policy
-
The integration point only supports sending in transactions for an account transaction type that has the Manual indicator set to No. Fatal message POL-IP-POLT-002 is raised if the transaction references an account transaction type with Manual indicator set to Yes.
The following follow-up actions are executed:
-
If the policy account transaction’s type requires creating a general ledger event, this is generated by the dynamic logic function that is referenced by the policy account definition
-
If a policy account transaction with the same code already exists, the new transaction is saved to the system and the existing policy account transaction is reversed.
On successful creation of policy account transaction, the system responds with status 201 message.
Fetch Policy Account Transactions
Fetch Policy Account Transaction Lists for a Policy Account
The external system can fetch a list of policy account transactions for one policy account by posting a request to the URL: http://{base URL}/api/policyaccounttransactions.
Example:
GET http://{__contextroot__}/api/policyaccounttransactions?accountNumber="<accountNumber>"&policyCode="<policyCode>"&personCode=<personCode>&accountDefinitionCode=<accountDefinitionCode>&asOfDate=<asOfDate>&accountTransactionType=<accountTransactionType> ??
For the usage of the parameters see the 'Fetch a Policy Account' section in this document.
Once the request is acknowledged, the system processes the request and generates the response.
<items> <policyAccountTransaction code="" policyAccountTransactionTypeCode="" personCode=""> <transactionDateTime/> <amount/> <policyAccount/> </policyAccountTransaction> </items>
The list of policy account transactions also includes the reversed transactions.
Policy Account Transaction Lists
Create Policy Account Transactions for Existing Policy Accounts
An external system can send in lists of policy account transactions for existing policy accounts. Because the volume of data can become quite extensive, these are file based requests. Please refer to the 'File Based Import' section in the HTTP API Integration Points part of the Common Features book for more details.
The system accepts the request in the following format:
<policyAccountTransactionList>
<policyAccountTransaction
code=""
descr=""
policyAccountTransactionTypeCode=""
personCode="">
<amount/>
<transactionDateTime/>
<policyAccount/>
</policyAccountTransaction>
</policyAccountTransactionList>
The values to be set, the rules that apply and the follow-up actions are the same as in the policy account transaction IP.
This file based import needs as seed data:
Activity Types
Code | Description | Type Level | Top Level? | UI? | Dynamic Record Definition |
---|---|---|---|---|---|
LOAD_POL_ACC_TRANSACTIONS |
Load policy account transactions |
GL |
Y |
Y |
FILE_IMPORT |
Dynamic Fields
A given implementation of the Oracle Health Insurance application could have dynamic fields added to the policy account and policy account transactions that need to be interfaced. For details on how external interfaces can provide values for dynamic fields in request messages and how they are handled by the Oracle Health Insurance application, refer to the concepts in the Developer Guide.
Messages
The following error messages that are specific to the policy accounts interface may be returned in the response messages:
Code | Severity | Message |
---|---|---|
POL-IP-POLA-001 |
Fatal |
Policy account definition code {code} is unknown |
POL-IP-POLA-002 |
Fatal |
Policy code {code} is unknown |
POL-IP-POLA-003 |
Fatal |
The combination of account number {account number}, policy code {code}, account definition {code} and person {code} is unknown |
POL-IP-POLA-004 |
Fatal |
Not enough information to create the policy account |
POL-IP-POLA-005 |
Fatal |
Start date must be before or on the as of date |
POL-IP-POLT-001 |
Fatal |
Policy account transaction type {code} is unknown |
POL-IP-POLT-002 |
Fatal |
Policy account transaction type {code} must not be of type Manual |
POL-IP-POLT-003 |
Fatal |
Policy account with {account number} {policy code} {account definition code} {person code} is unknown |
POL-IP-POLT-004 |
Fatal |
Currency code of the account transaction {code} must be the same as the currency code of the account definition {code} |
POL-IP-POLT-005 |
Fatal |
If the account number is omitted a person code is required to find the correct policy account at person level |
In addition, functional business rule messages may be returned as well as the standard messages related to dynamic fields and dynamic records (refer to the 'Response Messages' section in the HTTP API Integration Points part of the Common Features book).