3.1. Introduction to AFD structures

Bridge between data catalog and API-framework functions

In SIVI AFS, the use of AFD structures occupies a prominent place. In thinking about API architectures, the starting point is that functions are defined on the basis of the specific data set to which the function applies. The AFD structures shape the framework for data exchange: not only as a structure for the messages, but also for the input and output of API functions within the API-framework. For these functions, the payload (both input and result message) must comply with one of the AFD structures. For example, the newPolicy function must always provide the response message in the policyStructure or masterAgreementStructure.

Design

A structure is designed for a specific high level business domain and comprises all entities which are relevant for that domain, without any restriction on the usage of specific entities or attributes. This means that a structure constitutes a subset of the full AFD catalog, which is dedicated to one specific high level domain like for instance policy, claim or party. Structures are the vessels for transporting and recording data with regard to business processes, and allow a maximum of flexibility with respect to available entities and attributes.

A structure does not have any proprietary attributes (only entities can contain attributes). A structure only serves to define a set of entities and their respective relationship(s). (The only exception allowing some structures to contain a refKey attribute to make it easy to refer to the top level of the structure, i.e. within a messageStructure.)

General composition of an AFD Structure

Every AFD structure is built in the same way: commonFunctional (mandatory), commonTechnical, main entity of the structure (e.g. policy in case of a policyStructure, mandatory), document, process and/or error. See table below:

No nested structures

Within SIVI AFS it is not allowed to nest structures under structures. A concrete example: under the policy entity in a policyStructure, nesting of an entire objectStructure (for (eg) data about a home) is not allowed. Just nest the objects (as entities) themselves under the main policy entity of the policyStructure. For more complex structures, use references (e.g. policyRef to the refKey of a policy entity).

Only one main entity on highest level

The highest level of each AFD structure consists of commonFunctional (mandatory), commonTechnical, main entity of the structure (e.g. policy in case of a policyStructure, mandatory), document, process and/or error enties. And nothing else! In other words, it is not allowed to have both a policy and an object entity at the highest level. Other entities need to be nested under the main entity of the structure.

Exception: superStructures

Still, with specific messages you may want to include multiple entities, while nesting is not an option. Consider, for example, data about customers in a mortgage application. You can register a couple applying for a mortgage as two parties in a partyStructure. But if their address details match (as they usually will), you don’t want to nest an identical address entity under both party entities twice. A top-level address entity, with references from the relevant party entities, is then desirable.

That is why SIVI offers – in specific cases – the possibility to deviate from the general rules regarding structures. This is possible for certain instances of certain structures. We call such structures superStructures, and they do not get the name of the main entity (as there can be several main entities) but of the application/domain. A superStructure uses entities from other structures, but doesn’t have entities by itself. More information can be found in the superStructure chapter.

Example of a policyStructure

See below the example of a policyStructure, in this case the result of a submitPolicy function. The system is the same as in AFD 1.0, only the details are different on certain points. For example, this AFD structure always contains one or more policy entities, but other entities such as party, object and coverage are optional. On the policy in the example, both a policyHolder (policyholder) and regularDriver (regular driver) are registered. thirdPartyLiability (legal liability) and hullVehicle (hull) are included as covers. The commonFunctional entity is a generic meta entity, similar to the AL entity from AFD 1.0.

{
	"commonFunctional": [
		{
			"entityType": "default",
			"dataCatalogVersion": "34F",
			"functionVariant": "new"
		}
	],
	"commonTechnical": [
       	{
			"entityType": "default",
			"messageVersion": "107",
			"creationDate": "2022-09-01",
			"creationTime": "08:05:19",
			"systemEnvironment": "P",
			"transactionReference": "0571109lka",
			"registrationDate": "20221001",
			"sendingMethod": "R"
		} 
	],
	"policy": [
		{
			"entityType": "policyDetails",
			"businessLine": "021",
			"porCompany": "A001",
			"afdDefinitionName": "Goed verzekerd op weg",
			"afdDefinitionVersion": "001.00",
			"effectiveDate": "2020-05-01",
			"paymentTermInMonths": 3,
			"party": [
				{
					"entityType": "policyHolder",
					"relationNumber": "11232",
					"surname": "Jansen"
				},
				{
					"entityType": "regularDriver",
					"birthDate": "1971-11-15",
					"surname": "Hobbema"
				}
			],
			"coverage": [
				{
					"entityType": "thirdPartyLiability",
					"coverageCode": "2001",
					"renewalCommissionPercentage": 1.5,
					"deductibleAmount": 500
				},
				{
					"entityType": "hullVehicle",
					"coverageCode": "2002",
					"renewalCommissionPercentage": 2.1,
					"insuredSum": 30000
				}
			]
		}
	],
	"document": [ 
		{
			"entityType": "default",
			"sequenceNumber": 1,
			"documentType": "35",
			"contentEncoding": "base64",
			"fileName": "afd001.xml",
			"fileExtension": "xml",
			"content": "VGhpcyBpcyBhbiBleGFtcGxlIG9mIGEgYmFzZTY0IGVuY29kZWQgdGV4dA==",
			"finalDestination": "VP",
			"reactionRequired": false,
			"priority": "00002"
		}
	 ],
	"process": [ 
		{
			"entityType": "transaction",
			"sequenceNumber": "1",
			"statusType": "5",
			"statusDescription": "voorlopige offerte mw. Janssen",
			"referenceDate": "2022-12-01",
			"processStartDate": "2022-12-15"
		} 
	]
}

Relation to AFD 1.0 messages

Within AFD 1.0, the structure of a message was based on the type of message. For example, the contract message (contractbericht) or damage report (schadebericht). Each message recorded which entities and attributes were mandatory and/or optional, and how they related to each other (see the image below for an excerpt).

Within AFD 1.0 you could, for example, submit an application for insurance or loan using the contract message. Within SIVI AFS this works differently and you use a policyStructure or loanStructure. SIVI AFS has the following AFD structures, with the corresponding message type in AFD 1.0 in brackets (if applicable):

• afsStructure (new)
• afsTableStructure (new)
• claimStructure (schadebericht)
• containerStructure (new)
• documentStructure (new)
• loanStructure (contractbericht, specified for loans/mortgages)
• masterAgreementStructure (pakketbericht)
• messageStructure (new)
• objectStructure (new)
• partyStructure (relatiebericht)
• pensionStructure (contractbericht, specified for pensions, under construction)
• policyStructure (contractbericht)
• taskStructure (new)
• ticketStructure (new)