5.12. More message types within one structure

Based on the article ‘Meerdere berichtsoorten binnen één structuur’ (in SIVI AFS Magazine December 2023).

Within the SIVI AFS API framework, we distinguish between package policies and individual policies. Or rather, we differentiate between functions for package policies and functions for individual policies. For instance, the retrieve function has a separate endpoint for a policyStructure with a single policy and a separate endpoint for a masterAgreementStructure. This is logical from the API perspective, where functions always pertain to a delimited, specific dataset: package policies are simply different datasets than individual policies.

Example 1 – Communicating both individual policies and package policies simultaneously
However, there are parties that want to be able to retrieve all policy information of (for example) an insured person or company with a single API call. Whether it concerns package policies, individual policies, or a combination of both. In fact, in such situations, it’s about a customer file: for this, within SIVI AFS, we use the partyStructure. Under the party entity – whether the entityType is ‘company’, ‘policyHolder’, or something else – you then nest the relevant masterAgreement and policy entities. To indicate which policy entities are part of the masterAgreement, you refer from the relevant policy entities to the refKey of the masterAgreement using the masterAgreementRef attribute.

A (schematic) example with an insured person, who has both a package policy (with two policy components) and three individual policies in her file:

commonFunctional.default
commonTechnical.default
party.policyHolder
		masterAgreement.package
			refKey = ‘PK2309LJ8S’
		policy.policyDetails
			masterAgreementRef = ‘PK2309LJ8S’
		policy.policyDetails
			masterAgreementRef = ‘PK2309LJ8S’
		policy.policyDetails
		policy.policyDetails
		policy.policyDetails

Retrieving this partyStructure using the existing party functions from the SIVI AFS API framework through APIs is easy.

Example 2 – The ‘batchmessage’ in SIVI AFS
In example 1, all policies and package policies are linked to a party and thus part of a customer file. But there are several examples where a list of policies can appear in both request and response that are not linked to one specific party. In such cases, neither the masterAgreementStructure nor the policyStructure is sufficient: at the highest level, only a masterAgreement or a policy entity is allowed. (See also the explanation in 3.1 Introduction to AFD structures.)

The goal for such applications is to be able to use masterAgreement and policy side by side in a single message. Some parties in the industry have therefore requested to expand the existing structures and deviate from the principles around structures. In other words, to allow a masterAgreement alongside the policy within a policyStructure at the highest level. However, this would result in the masterAgreementStructure no longer technically differing from the policyStructure, even though both serve different purposes – namely modeling packages versus modeling policies.

Within AFD 1.0, the batch message exists for combining multiple message types within a single message. In AFD 2.0 the afsStructure serves this purpose. The afsStructure is a generic AFD structure in which parties are free to organize entities in any way they prefer. In the afsStructure you can therefore model multiple entities at the highest level without any problems. The principle is that you can model any message using the afsStructure. But SIVI has made a selection of which entities can and cannot be nested under other entities: for example, an address entity can be nested under a party, but not the other way around. And the use of the commonFunctional – for functional metadata – is mandatory, as is also the case with the other structures,

Note: the afsStructure does not have exactly the same structure as the batch message in AFD 1.0. While in the batch message you combine and can repeatedly include other message types, within the afsStructure, you do not combine other structures, but entities.

Another look at example 1 with a package policy containing two policy components, and additionally three individual policies, but now without a parent file, shows the possibility to model this in the afsStructure as follows (schematically). Similar to the first example, refer from the relevant policy entities to the refKey of the masterAgreement using the masterAgreementRef attribute.

commonFunctional.default
commonTechnical.default
masterAgreement.package
		refKey = ‘PK2309LJ8S’
policy.policyDetails
		masterAgreementRef = ‘PK2309LJ8S’
policy.policyDetails
		masterAgreementRef = ‘PK2309LJ8S’
policy.policyDetails
policy.policyDetails
policy.policyDetails

Functions on the afsStructure always on request
The afsStructure logically offers a lot of freedom in message modeling. Partly for this reason, we have not defined functions on this structure in the SIVI AFS API framework, yet: the possibilities are endless, and SIVI follows a demand-driven approach for the API framework as well. However, we have seen a realistic exception above: in the coming months, SIVI will define a function that – based on the afsStructure – can retrieve multiple policies and packages side by side.