Add Product Service Definitions

The Add Product Service Definitions integration point is a long-running operation that enables users to add service definitions, services, and service options to a single or multiple products. There are two ways to add service definitions to products through this integration point:

• By passing a query filter

• By providing a specific list of products

Operations

This API supports the following operations

POST	/addproductservicedefinitions adds product service definition(s) to one or more products.

Rules

Required and Allowed Properties

The API requires the following properties in the payload:

• A product list that contains at least one product

• A product list or query parameter must contain a minimum of one product.

• Only one of the query parameters or the product list must be defined in the payload.

• The serviceDefinitionCode must be defined when the query parameter is defined in the payload.

• At least one of the properties serviceOptionCode or includeProductServicesOnly.

• The serviceCode property is not allowed if the payload specifies includeProductServicesOnly = true.

• The serviceCode property is only allowed if the payload also specifies a serviceOptionCode.

• The serviceDefinitionCode property is allowed only if the payload also specifies a serviceCode and a serviceOptionCode.

• The authorizationMissing property is allowed only if the payload also specifies a coverageRegimeCode.
  

• If the payload specifies a coverageRegimeCode but it does not specify the authorizationMissing property, the API defaults the value to false.

• A parameter alias list is allowed in the payload only if the payload also specifies a coverageRegimeCode.

  • Only Cover withhold categories that are included in the specified coverage regime can be part of the Parameter alias usage list.

  • The presence of an accumulation option in a product service definition influences whether adding a parameter alias for a limit to the Parameter alias usage list is possible.

• A selected accumulation option list is only allowed in the payload if the payload also specifies a coverageRegimeCode.

• A product list or query parameter must contain a minimum of one product.

• Only one of the query parameters or the product list must be defined in the payload.

• The serviceDefinitionCode must be defined when the query parameter is defined in the payload.

• The serviceDefinitionType property is only allowed if serviceDefinitionCode is defined.

  • serviceDefinitionType can be "A", "C", "W", "P" & "R". The meanings are:

    • A: Authorization

    • C: Coverage

    • P: Post Benefits

    • R: Reservation

    • W: Waiting Period

• When the serviceDefinitionCode property is defined in the payload, it is mandatory to specify the serviceDefinitionType property.

Rules for Product List and Query Parameter Specified

• If productList is specified:

  • Service definitions are added to the products that qualify products from the list.

  • No limitation as long as the request can be parsed.

• If the query filter is passed:

  • Service definitions are added to the products, that qualify as a result of the query.

  • The query parameters must be on generic product resources.

    • The system identifies the list of products based on query criteria as specified by the query element in the request.

• Generic Query Filter Rules:

  • The payload request can pass a query filter (like in generic APIs) to perform the DML operations on the records that qualify the query string.

  • Anything possible for the Query API is applicable to that filter string.

    • For parameters, only q (this query parameter holds the search criteria) is needed. For more information, see Query API.

    • One query is passed for one POST request.

Processing Depends on Payload

The results of processing the request depend on the values for includeProductServicesOnly, serviceOptionCode, serviceCode, and serviceDefinitionCode in the payload.

• If the request payload passes the query:

  • Only service definition can be defined i.e. payload specifies includeProductServicesOnly = false (or is not specified), query parameter along with the serviceOptionCode, serviceCode, and serviceDefinitionCode, the API adds service option, the given service, and service definitions of the product.

• If the request payload pass productList:

  • If the payload specifies includeProductServicesOnly = true along with the serviceOptionCode, the API adds only default and active service definitions linked to the product services for the given service option code.

  • If the payload specifies includeProductServicesOnly = true but no serviceOptionCode, the API adds default and active service definitions linked to all the product services.

  • If the payload specifies includeProductServicesOnly = false (or it is not specified) along with the serviceOptionCode, the API adds service options, its services, and all the default and active service definitions to the product.

  • If the payload specifies includeProductServicesOnly = false (or is not specified) along with the serviceOptionCode and a serviceCode, the API adds service options, the given service, and all the default and active service definitions to the product.

  • If the payload specifies includeProductServicesOnly = false (or is not specified) along with the serviceOptionCode, serviceCode, and serviceDefinitionCode, the API adds service option, the given service, and service definitions of the product.

• There is a generic check on service definition - Included by default and Active. This check is applicable only when serviceDefinitionCode is not specified.

• For the products with the status Review, Test , and Approved in the product list, the API sets the product status back to Edit (PRD-IP-PSVD-041 is returned for products with Queued status).

The system adds the service options and services to the product only if they are not already part of the product.

Setting the Product Service Definition Properties

• If the payload specifies a value for a property of a product service definition, for example "ageFrom": "10", then the API sets this value for every added product service definition.

• If the payload does not specify a start date, the API uses the product start date for the product service definition start date.

• If the payload does not specify the Marked for Selection indicator, the API sets it to true by default for every added product service definition.

Creating Parameter Aliases

Cover Withhold Categories

When the API creates a product service definition with a regime of type coverage, it also creates a parameter alias usage for each cover withhold category that:

• Has an intersection with the specified regime

• Has the type not been set to null

• Is not already part of the parameter alias usage list in the request payload.

Limits

The API additionally includes parameter alias usages with the limit related to the accumulation option when:

• The accumulation option is part of a product service definition’s selected accumulation option list.

• The parameter alias is not already part of the parameter alias usage list in the request payload.

• If only one parameter alias is configurable on the new limit, and a parameter alias usage is not specified in the request payload, then the parameter alias is added by default along with the limit (this applies only to limits where display in UI is False).

If the limit is linked to multiple accumulation options, only one parameter alias usage is created for the limit.

Dynamic Fields

• When implementing the Oracle Health Insurance application, there might be dynamic fields with the product service definition that must be interfaced. For more details on how external interfaces can provide values for dynamic fields in request messages and how the application handles them, see the Property Representation and Handling section in the HTTP API/IP Concepts part in the Developer Guide.

Processing

• The system starts a long-running operation when a POST request is performed. For more details, see Long-Running Operation Through REST.

• The request payload must pass a query filter that returns at least one known product or the request payload, product list must contain at least one known product otherwise error PRD-IP-PSVD-042 is returned.

• If any service definition cannot be added to a product by the long-running operations, the entire operation is rolled back, and the status of the long-running operations process is set to fail. The system must be able to add the service definition on all the products or to none.

Request Message

The system accepts the product service definitions request message in the following JSON format:

Add Product Service Definitions through productList

Details

{
	"productList": [
		{
			"productCode": "<code>"
		}
	],
        "includeProductServicesOnly" : false
        "serviceOptionCode": "<code>",
	"serviceCode": "<code>",
	"serviceDefinitionCode": "<code>",
        "serviceDefinitionType": "<code>"
	"startDate": "",
	"coverageRegimeCode": "<code>",
	"authorizationRegimeCode": "",
	"postBenefitsRegimeCode": "<code>",
	"reservationRegimeCode": "<code>",
	"waitingPeriodRegimeCode": "",
	"ageFrom": "",
	"ageTo": "",
	"authorizationMissing": true,
	"conditionDynamicLogicCode": "<code>",
	"countryRegionEmployerCode": "<code>",
	"countryRegionGroupEmployerCode": "<code>",
	"personCountryRegionUsage": "",
	"countryRegionGroupPersonCode": "<code>",
	"providerCountryRegionUsage": "",
	"countryRegionGroupProviderCode": "<code>",
	"countryRegionPersonCode": "<code>",
	"productProviderGroupUsage": "",
	"countryRegionProviderCode": "<code>",
	"employerCountryRegionUsage": "",
	"endDate": "",
	"gender": "",
	"markedForSelection": true,
	"newProductServiceDefinition": true,
	"productServiceDefinitionPriorityCode": "",
	"specificProviderGroupUsage": "",
	"<dynamicField>": "",
	"productServiceDefProviderGroupList": [
		{
			"providerGroupCode": "<code>",
			"assignedProviderGroupLabelCode": "<code>"
		}
	],
	"parameterAliasUsageList": [
		{
			"parameterAliasCode": "<code>",
			"coverWithholdCategoryCode": "<code>",
			"limitCode": "<code>"
		}
	],
	"selectedAccumulationOptionList": [
       {
             "accumulationOption":
                {
			        "coverWithholdCategoryCode": "<code>",
			        "limitCode": "<code>"
                    "reachedAction" : ""
                }
        }
	]
}

Product Service Definitions through Query

Details

{
	"query": { "status.in('Approved')" (to be applied to products resource)

         Rest parameters are the same defined for Product Service Definitions through productList

}

Authorization

This integration point requires a grant for access restriction addproductservicedefinitions IP.

Response

• The integration responds with HTTP 201 (created) and a location header for the long-running operation.

• The long-running operation resource offers additional details about the process operator, which users can use to check the process status.

• The operator also provides links to processing messages (error or informative).

Response Message

A successful operation returns the HTTP status code 200 OK.

Batches

This integration point supports adding service definitions to a list of products. The list of service definitions can be restricted by adding a service option code, service code, or service definition code to the payload. This IP does not support restricting the list of service definitions by specifying lists of service option codes, service, or service definition codes in the payload.

Error Messages

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

Table 1. Error Messages

Code	Severity	Message Text
PRD-IP-PSVD-001	Fatal	Product code {code} is unknown
PRD-IP-PSVD-002	Fatal	Service option code {code} is unknown
PRD-IP-PSVD-003	Fatal	Service code {code} is unknown or is not part of the services associated with the service option
PRD-IP-PSVD-004	Fatal	Service definition code {code} is unknown or is not part of the service definitions associated with the service
PRD-IP-PSVD-005	Fatal	Coverage regime code {code} is unknown
PRD-IP-PSVD-006	Fatal	Authorization regime code {code} is unknown
PRD-IP-PSVD-007	Fatal	Post benefits regime code {code} is unknown
PRD-IP-PSVD-008	Fatal	Reservation regime code {code} is unknown
PRD-IP-PSVD-009	Fatal	Waiting period regime code {code} is unknown
PRD-IP-PSVD-010	Fatal	Condition dynamic logic code {code} is unknown
PRD-IP-PSVD-011	Fatal	Country region employer code {code} is unknown
PRD-IP-PSVD-012	Fatal	Country region group employer code {code} is unknown
PRD-IP-PSVD-013	Fatal	Country region group person code {code} is unknown
PRD-IP-PSVD-014	Fatal	Country region group provider code {code} is unknown
PRD-IP-PSVD-015	Fatal	Country region person code {code} is unknown
PRD-IP-PSVD-016	Fatal	Country region provider code {code} is unknown
PRD-IP-PSVD-017	Fatal	Provider group code {code} is unknown
PRD-IP-PSVD-018	Fatal	Assigned provider group label code {code} is unknown
PRD-IP-PSVD-019	Fatal	Parameter alias code {code} is unknown
PRD-IP-PSVD-020	Fatal	Parameter alias cover withhold category code {code} is unknown
PRD-IP-PSVD-021	Fatal	Parameter alias limit code {code} is unknown
PRD-IP-PSVD-022	Fatal	Accumulation option with cover withhold category {code}, limit {code} and reached action {action} is unknown
PRD-IP-PSVD-023	Fatal	Accumulation option with cover withhold category {code} and limit {code} cannot be added for coverage regime {code}
PRD-IP-PSVD-024	Fatal	Authorization missing can only be defined when the regime of type coverage
PRD-IP-PSVD-025	Fatal	Parameter alias usages cannot be defined without a coverage regime
PRD-IP-PSVD-026	Fatal	Cover withhold category {code} cannot be parameterized for the {code} regime
PRD-IP-PSVD-027	Fatal	Accumulation options not defined, or the limit {code} cannot be parameterized for the selected accumulation options
PRD-IP-PSVD-028	Fatal	Empty product list or product list not part of the request
PRD-IP-PSVD-029	Fatal	Service option code is required when indicator include product services only is not provided or set to false
PRD-IP-PSVD-030	Fatal	Service code is required when defining a service definition
PRD-IP-PSVD-031	Fatal	Multiple regimes cannot be defined for the same service definition
PRD-IP-PSVD-032	Fatal	Regime {code} of type {type} cannot be configured for the service definition {code}
PRD-IP-PSVD-033	Fatal	Cover withhold category {code} cannot be parameterized with the Parameter alias {code}
PRD-IP-PSVD-034	Fatal	Limit {code} cannot be parameterized with the parameter alias {code}
PRD-IP-PSVD-035	Fatal	Regime {code} of type {type} cannot be configured for all the service definitions associated with the Service option {code}
PRD-IP-PSVD-036	Fatal	Regime {code} of type {type} cannot be configured for all the service definitions associated with the Service option {code} and service {code}
PRD-IP-PSVD-037	Fatal	Product Service definition priority code {code} is unknown
PRD-IP-PSVD-038	Fatal	Coverage regime code is mandatory when defining the accumulation options for a product service definition
PRD-IP-PSVD-039	Fatal	Cover withhold category code, limit code and reached action are required when defining an accumulation option
PRD-IP-PSVD-040	Fatal	Service code cannot be defined with include product services only indicator set to true
PRD-IP-PSVD-041	Fatal	Cannot add product service definitions as \{product code} is in queued status
PRD-IP-PSVD-042	Fatal	No product found that matches the provided query criteria
PRD-IP-PSVD-043	Fatal	Service definition Code is required when query parameter is defined
PRD-IP-PSVD-044	Fatal	Query parameter cannot be defined with product list
PRD-IP-PSVD-045	Fatal	Service definition type is required when defining a service definition
PRD-IP-PSVD-046	Fatal	Service definition type {type} is unknown
PRD-IP-PSVD-047	Fatal	Service definition type cannot be defined without service definition
PRD-IP-PSVD-048	Fatal	Service definition type {type} mentioned is not associated with the service definition {code}

In addition, this integration point can return functional business rule messages as well as the standard messages related to dynamic fields and records.

See Response Messages for more information.