Based on the article ‘SIVI AFS: Registratie van gegevens versus services’ (in SIVI AFS Magazine May 2022).
Users of SIVI AFS use AFD 2.0 for the performance of services (data exchange) and for registration (data storage). In this article, we show some examples of the use of AFD 2.0 messages for services and registration, as well as the differences between them.
SIVI developed three examples of messages for a motor vehicle:
- Premium calculation call: service
- Premium calculation result: service
- Registration of a policy: storage
Features of basic AFD 2.0 messages
Before getting deeper into the specific properties and differences between a service and a registration in case of an AFD 2.0 message, we look at the similarities, applying to each AFD 2.0 message.
Each AFD message is based on an AFD structure. Apart from specific structures (see chapter AFD structures), there is a generic afsStructure, that enables the user to compose any message. Every AFD structure, regardless whether it is used for services or registration, consists of three parts:
- commonFunctional: functional metadata
- commonTechnical: technical metadata
- Payload: the actual content of the message
All AFD 2.0 messages contain a commonFunctional entity with the functional metadata of the message. The attribute dataCatalogVersion is always present and shows the version of the data catalog (AFD 2.0) used for the composition of the message.
Examples of additional attributes in commonFunctional are:
- afdDefinitionName: the name of the AFD-definition for a service or a registration.
- afdDefinitionVersion: indicates which version of the AFD-definition is communicated.
- More identifying attributes, if applicable:
- businessLine: classification of the type of insurance contract – mandatory only in case of insurance contracts.
- porCompany: identification code of an insurance company or mortgage lender – mandatory only in case of insurance or mortgage contracts.
A message can contain a commonTechnical entity with the technical metadata of the message. This is optional. The attribute creationDateTime (creation date and time of the message, as a timestamp) is relevant for both services and registration. Most attributes in commonTechnical are meant for messages in case of services, like:
- senderId: identification of the calling party – to get access to the system he made a call to.
- accessCode: code that gives the calling party access to the system he made a call to.
- sessionId: session identification of the period between logging in and logging out of the user.
The third part is called the payload. The payload indicated the functional/actual content of the message. The payload depends on the goal of the message and the structure of the payload follows the structure of AFD structure used, in this paragraph the policyStructure.
{
"commonFunctional": [
{
"entityType": "default",
"afdDefinitionName": "Goed verzekerd op weg",
"afdDefinitionVersion": "001.00",
"businessLine": "020",
"porCompany": "A999"
"dataCatalogVersion": "38D",
}
],
"commonTechnical": [
{
"entityType": "default",
"creationDateTime": "2022-02-11 08:05:19",
"senderId": "S-HB350012",
"accessCode": "2005AB05342749432",
"sessionId": "SID:ANON:sivi.org:j6oAOxCWZhCD723LGeX1f-01:38",
}
],
"policy": [
{
"entityType": "policyDetails",
"contractNumber": "Polis-20220020512",
"externalIndicative": "TP-polis-245345",
"effectiveDate": "2022-06-01",
"renewalDate": "2023-06-01",
"paymentTermInMonths": 6
"grossPremiumInstallment": 235,45,
"numberOfClaimFreeYearsOnStatement": 5,
"standardCommission": true,
"statusType": 39,
"party": [
{
"entityType": "policyHolder",
"surname": "Verbeek"
"initials": "AA"
"birthDate": "1999-04-18"
"houseNumber": "15"
"houseNumberAdditioan": "a"
},
{
"entityType": "regularDriver",
"birthDate": "1999-04-18",
}
],
"coverage": [
{
"entityType": "hullVehicle",
"coverageCode": "2002",
"sumInsured": 60000,
"deductibleAmount": 500,
"grossPremiumInstallment": 500,
"renewalCommissionPercentage": 10,
"numberOfMonthsPurchaseValueGuarantee": 3
},
..... Features AFD 2.0 message in case of calling a service
Calling a service involves passing variables to perform a particular action or actions to perform. The example above contains the call of a premium calculation.
For the purpose of logging and sending workflows, it is recommended to include the attribute functionVariant (in commonFunctional), even though it can be deduced from the endpoint. This attribute is linked to the code list APIVAR, where all function variants within the API framework are included. After selection of the functionVariant, not just the selected function and underlying process conventions are known, but also the attributes and parameters required to perform the function.
{
"commonFunctional": [
{
"entityType": "default",
"afdDefinitionName": "Goed verzekerd op weg",
"afdDefinitionVersion": "001.00",
"businessLine": "020",
"porCompany": "A999",
"dataCatalogVersion": "38D",
"functionVariant": "A0010",
}
],
.....Features AFD 2.0 message for a result of a service
Within the SIVI API framework, the starting point is, that in the return message all supplied data is included. There are exceptions, for example the function variant ‘status’ where only a status returns, or the function variant ‘list’ where only a list of IDs (e.g. policyIds) returns. It depends on the function and the domain, which attributes are returned.
Data concerning the transaction process can be found in the entity process, entityType ‘transaction’. The most important attributes are:
- statusType: code showing the result of the request (e.g. code 0 = rejected)
- statusExplanation: additional information on the statusType code. In the case of rejection extra information is provided why the request was rejected.
In some cases a service call cannot be performed because of a technical issue (message error or error during handling of the service). The returned payload then only contains an error entity with the attributes that describe the error message. These attributes could possibly be displayed, including the http status code. By default, the http status code is visible in the response header, but it is also included in the payload to support processes to retrieve the error.
The following attributes are available for the entity error:
- httpStatus: the http status code from the response header, included here to make it easier to retrieve/define an error.
- errorCode: specification of the error message. Suppliers of the API can define their own code here (range 1000 – 9999).
- errorDescription: additional text to describe the error message.
Features of a message in case of registration of data
Registration of data involves the storage of data with a certain objective. In this example, it involves the registration of a car policy. In addition to vehicle data, you also see a set of insurance data. An AFD-structure is the starting point for data storage, as well. The example shows a policyStructure. For proprietary messages the generic afsStructure is available.
A message for registration does not contain any other entities and attributes, related to the execution of transactions. The attribute ‘statusTupe’ is particularly meant for storage. It indicates the status of the data stored: for example 1 (ongoing), 3 (canceled) or 39 (future policy). This entity statusType should usually be included within the entity policy, entityType ‘policyDetails’. In case of an advanced registration this attribute can also be included in all entities where a status code is important.
{
"commonFunctional": [
{
"entityType": "default",
"afdDefinitionName": "Goed verzekerd op weg",
"afdDefinitionVersion": "001.00",
"businessLine": "020",
"porCompany": "A999"
"dataCatalogVersion": "38D",
}
],
"commonTechnical": [
{
"entityType": "default",
"creationDateTime": "2022-02-11 08:05:19",
}
],
"policy": [
{
"entityType": "policyDetails",
"contractNumber": "Polis-20220020512",
"externalIndicative": "TP-polis-245345",
"effectiveDate": "2022-06-01",
"renewalDate": "2023-06-01",
"paymentTermInMonths": 6
"grossPremiumInstallment": 235.45,
"numberOfClaimFreeYearsOnStatement": 5,
"standardCommission": true,
"statusType": 39,
"party": [
{
"entityType": "policyHolder",
"surname": "Verbeek"
"initials": "AA"
"birthDate": "1999-04-18"
"houseNumber": "15"
"houseNumberAdditioan": "a"
},
{
"entityType": "regularDriver",
"birthDate": "1999-04-18",
}
],
"coverage": [
{
"entityType": "hullVehicle",
"coverageCode": "2002",
"sumInsured": 60000,
"deductibleAmount": 500,
"grossPremiumInstallment": 244.00,
"renewalCommissionPercentage": 10,
"numberOfMonthsPurchaseValueGuarantee": 3
},
..... Feedback
Powered by
Post your comment on this topic.