docs: case study from HDI Global SE #3010
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,229 @@ | ||
| id: hdiglobal | ||
| company: | ||
| name: HDI Global SE | ||
| description: The HDI brand operates in Germany and internationally, offering life and property/casualty insurance services. They cater to both private individuals and corporate clients, and have been providing industrial insurance since 2016. | ||
| customers: "5000" | ||
| industry: Insurance | ||
| revenue: 9.1 Mrd. EUR | ||
| website: https://www.hdi.global/ | ||
| logo: /img/casestudies/hdi/hdi_logo.svg | ||
| contact: | ||
| - name: Vladislav Zwenihorodski | ||
| link: https://www.linkedin.com/in/vladislav-zwenihorodski-9680a1209/ | ||
| challenges: | | ||
| The HDI has various platform teams, among them the Integration Platform Team, which offers three products: Azure API Management, Azure Event Hub, and the Azure Service Bus. | ||
| For synchronous communication, we already use OpenAPI, as such we want to ensure the same level of transparency and discoverability for asynchronous scenarios as well. | ||
| Our central platform team offers the Azure Service Bus with self-service capabilities. | ||
| Customers are able to manage their own topics and subscriptions by simply modifying the according values in their repositories. | ||
| This means that most of the data required to document asynchronous communication is already available, although distributed between different repositories. | ||
| This necessitated the creation of a comprehensive catalog of existing topics, allowing potential subscribers easy access to messages from any topics of their choosing. | ||
|
|
||
|
|
||
| solution: | | ||
| The solution was to create an an AsyncAPI document where each topic owned by the customer is represented as a channel. | ||
| This document is automatically generated by a pipeline whenever there's a change in the topic configuration. | ||
| The necessary information is read from the customer repositories and then passed to a bash script as input. | ||
| After successful creation, this file, along with a generated markdown for it, is saved within a documentation repository. | ||
| This documentation repository serves as the basis for our Azure DevOps wiki, ensuring that all project documentation is centralized and easily accessible. | ||
| This ensures that the information is readily accessible to every developer, allowing easy access to messages from any topics of their choosing. | ||
| This approach makes our asynchronous communication is as transparent and discoverable as our synchronous communication. | ||
| technical: #We need some more technical information related to case study. | ||
| languages: | ||
| - java, .net, bash | ||
| frameworks: | ||
| - Spring Boot | ||
| protocols: | ||
| - AMQP | ||
| brokers: Azure Service Bus | ||
| testing: n/a | ||
| architecture: | | ||
| The following [enterprise integration patterns](https://www.enterpriseintegrationpatterns.com/patterns/messaging) are applied : | ||
| - [Message Channel](https://www.enterpriseintegrationpatterns.com/patterns/messaging/MessageChannel.html) | ||
| Each channel in the AsyncAPI document corresponds to an existing Service Bus topic that can be subscribed to. | ||
| ``` | ||
| channels: | ||
| claimStatus-emea: | ||
| servers: | ||
| - $ref: '#/servers/box-emea' | ||
| address: https://namespace.servicebus.windows.net/topic/example/claimStatus | ||
| ``` | ||
| - [Message](https://www.enterpriseintegrationpatterns.com/patterns/messaging/Message.html) | ||
| The 'messages' section under each channel in the AsyncAPI document adheres to this pattern. | ||
| Each message is identified by a name and contains a payload, which represents the data transferred between applications. | ||
| ``` | ||
| messages: | ||
| claimStatus: | ||
| name: claimStatus-Message | ||
| contentType: application/json | ||
| ``` | ||
| - [Document Message](https://www.enterpriseintegrationpatterns.com/patterns/messaging/DocumentMessage.html) | ||
| The 'payload' under each message in the AsyncAPI document adheres to this pattern. | ||
| The payload is a self-contained document that describes the message and is comprehensible to the message receiver. | ||
| ``` | ||
| payload: | ||
| $ref: '#/components/schemas/claimStatus-example.json' | ||
| ``` | ||
| In our repository structure, the message-schema file is stored separately and just referenced in the Topic configs. | ||
| To make sure that all information is accessible in one place, the schema is directly copied to the AsyncAPI document. | ||
| ``` | ||
| components: | ||
| schemas: | ||
| claimStatus-example.json: { | ||
| "$schema": "http://json-schema.org/draft-06/schema#", | ||
| "type": "object", | ||
| "properties": { | ||
| "message": { | ||
| "type": "object", | ||
| "properties": { | ||
| "version": { | ||
| "type": "string" | ||
| }, | ||
| "header": { | ||
| "type": "object", | ||
| "properties": { | ||
| "messageId": { | ||
| "type": "string" | ||
| }, | ||
| "entityType": { | ||
| "type": "string" | ||
| }, | ||
| "eventType": { | ||
| "type": "object", | ||
| "enum": [ | ||
| "create", | ||
| "update" | ||
| ] | ||
| } | ||
| }, | ||
| "required": [ | ||
| "messageId", | ||
| "entityType", | ||
| "eventType" | ||
| ] | ||
| }, | ||
| "data": { | ||
| "type": "object", | ||
| "properties": { | ||
| "par": { | ||
| "type": "object", | ||
| "properties": { | ||
| "tenantNumber": { | ||
| "type": "string" | ||
| }, | ||
| "policyNumber": { | ||
| "type": "number" | ||
| }, | ||
| "contractNumber": { | ||
| "type": "number" | ||
| }, | ||
| "sourceSystem": { | ||
| "type": "string" | ||
| }, | ||
| "claimStatus": { | ||
| "type": "string" | ||
| }, | ||
| "currencyCode": { | ||
| "type": "string" | ||
| }, | ||
| "registrYear": { | ||
| "type": "number" | ||
| }, | ||
| "broker": { | ||
| "type": "string" | ||
| }, | ||
| "insured": { | ||
| "type": "string" | ||
| }, | ||
| "lineOfBusiness": { | ||
| "type": "number" | ||
| }, | ||
| "claimCountry": { | ||
| "type": "string" | ||
| }, | ||
| "isNewClaim": { | ||
| "type": "boolean" | ||
| }, | ||
| "dateOfLoss": { | ||
| "type": "string", | ||
| "format": "date" | ||
| }, | ||
| "creationDate": { | ||
| "type": "string", | ||
| "format": "date" | ||
| }, | ||
| "notificationDate": { | ||
| "type": "string", | ||
| "format": "date" | ||
| }, | ||
| "businessDate": { | ||
| "type": "string", | ||
| "format": "date" | ||
| } | ||
| }, | ||
| "required": [ | ||
| "tenantNumber" | ||
| ] | ||
| } | ||
| }, | ||
| "required": [ | ||
| "par" | ||
| ] | ||
| } | ||
| }, | ||
| "required": [ | ||
| "version", | ||
| "header", | ||
| "data" | ||
| ] | ||
| } | ||
| }, | ||
| "required": [ | ||
| "message" | ||
| ] | ||
| } | ||
|
|
||
| ``` | ||
| codegen: | | ||
| Our team currently does not use or ofer a code generation tool. | ||
| However, our customers are free to use any tool they prefer to generate DTOs from the AsyncAPI document. | ||
| schemas: #It is useful and interesting to learn how teams handle messages schemas. | ||
| description: JSON Schema | ||
| storage: A Git repository functions as a self-service portal where customers can manage their own configurations for the Azure Service Bus. | ||
| This includes defining their own message schemas for any topics they own. | ||
| registry: none | ||
| versioning: The customer has the freedom to choose the versioning for their own message-schema files. | ||
| validation: Validation using [Ajv](https://ajv.js.org/) is used solely for the purpose of ensuring that the JSON data adheres to the expected schema. This validation is performed for each customer by the Pull Request pipeline we provide. | ||
| It does not perform any other form of validation or processing on the data. | ||
| asyncapi: #More specific details about AsyncAPI itself and how is it used. | ||
| usecase: | | ||
| - The AsyncAPI documents are used for documentation purposes by the platform team. | ||
| It provides a comprehensive overview of the asynchronous communication in our system, including the available topics and the structure of the messages. | ||
| - (Future Plans) The AsyncAPI document will be used to generate Java DTOs using the AsyncAPI Java generator, ensuring type safety and clear data structure understanding. | ||
| versions: | ||
| - '3.0.0' | ||
| storage: | | ||
| A seperate Git repository functions as a "customer Wiki", serving as a central location for all relevant documents about the existing infrastructure. | ||
| This includes the AsyncAPI document, which provides a comprehensive overview of the asynchronous communication in our system. | ||
| editing: | | ||
| If changes for any topic are applied by a customer, the documentation pipeline is triggered. | ||
| This pipeline uses a bash script to read the updated configuration from the customer's repository. | ||
| It then generates a new AsyncAPI document reflecting these changes. | ||
|
|
||
| The AsyncAPI document is validated using the AsyncAPI CLI to confirm that the document is correctly formatted and adheres to the AsyncAPI specification right after creation and befor being commited to the documentation repository. | ||
| maintainers: | | ||
| Customers maintain this document automatically by maintaining their own topic configurations. | ||
| audience: #Specify if AsyncAPI audience is internal or external or both. | ||
| internal: true | ||
| external: false | ||
| extensions: | | ||
| none | ||
| documentation: | | ||
| Documentation is generated via AsyncAPI CLI and published to the Azure DevOps wiki right after the AsyncAPI file is generated. | ||
| bindings: | | ||
| none | ||
| tools: | | ||
|
There was a problem hiding this comment. can you add CLI to the list please? and also code generators that you use, which ones |
||
| * [AsyncAPI CLI](https://github.com/asyncapi/cli) | ||
| * [AsyncAPI Generator](https://github.com/asyncapi/generator): | ||
| * [markdown-template](https://github.com/asyncapi/markdown-template). | ||
| fullExample: resources/casestudies/hdi/asyncapi.yaml | ||
| additionalResources: ' ' | ||
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
so AMQP is main protocol, and HTTPS is just a transport?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes exactly the primary protocol for Service Bus is AMQP