Notes and Minutes Management
Overview
To design Notes and Minute Management service Adam, Jack, Alexander and Ben in sales have spent all their days on the phone and in meetings with customers. And they want to be able to easily record what has been discussed with their contact at each touch point they have discussed. The two business analysts Jack and Alexander have decided to create a Notes and Minutes Management service, which outlines some business scenarios related to meetings. Jack and Alexander first addressed various questions about minutes. Issues included how meeting notes are recorded, who usually attends meetings. Based on the insights gained, the various artefacts around the Notes and Minutes Management service were designed.
Introduction
This document describes the Notes and Minutes Management service and the required artefact that were designed for the service. Reading this document you will learn about the different steps of designing the Notes and Minutes Management service.
What is the scope of the Notes and Minutes Management service
The Notes and Minutes Management service focuses on managing the different kinds of Notes data. Altogether, Notes collects general information about notes and the details about the meeting is stored in Minutes. Depending on the type, different information is managed in the service.
Here is an overview of the entities that have been created for the Notes and Minutes Management service.
By taking the reference from the above UML, Jack and Alexander have designed the service in the tool. The tool provides the three-layer functionality to make the service running functionally. Each service is classified into API Namespace, Domain Namespace, Integration Namespace. Each namespace in the service has its own purpose. Taking the findings from the above UML sketch, different artefacts around different namespaces have been designed. Since Ben and Julia are experienced Java developers, the service was created as a Java domain service project.
Designing of Notes and Minutes Management service
The design of the service has been classified into the following namespaces:
Domain Namespace
This section covers everything important around the domain namespace, along with the other sections explaining how detailed the service was developed. Domain namespaces are used to encapsulate the business logic and to define concepts and their relationships among themselves for a specific use case. The core business logic is modelled in the domain layer.
Entities
In the Notes and Minutes Management service, the central entity is the Notes which is a root entity.
The Notes root entity is the anchor point to all the commands. These commands encapsulate the business logic for the service. This service offers different commands like Create Notes, Release Notes etc. They are associated with the root entity and describe their behaviour.
The Minutes entity has slightly different properties and behaviour which need to be addressed. Jack and Alexander explained to the team that this can be easily modelled via inheritance which prevents duplication of common data and behavior. All the different specializations also hold the commands which define the business logic and are inherited from their parents, additionally they hold also those commands which apply only for their specific use cases.
Alexander added that we can use external entities in the service. An external entity can be seen as pointer to an entity, which is managed in another service. The external entity itself holds only the most crucial data which is necessary for the core functionality of this service. In our case, Contact and Employee can be used as external entities where we integrate these services to be able to read the necessary data needed.
In the discussion, Jack has suggested to create an abstract entity named Participants and have sub entities as InternalParticipants, ExternalParticipants, and OtherParticipants. You can not create an instance from Participant itself but instead create an instance of any of the sub entities.
Properties
We don't need to modify the properties, once Jack has created the entities, the corresponding properties are automatically updated and shown in the properties tab.
Services
Similar to commands, you can define an input and output and add business events and business errors to a service. In our service, Jack and Alexander created two services. In GetNotes, the output is a list of all notes matching the input provided. GetNotesById has the output of a single note that matches the input ID.
Events
To proceed, Jack suggested to create an event named NotesLifecycleEvent. The purpose of this event is to inform the status change of a note. The event mainly contains the name, label and topic binding. Jack has also defined the payload by selecting the schema from the schema registry.
For more details on the Schema Registry, please visit our How-To: Use Events with Schema Registry
Errors
In our service, we have agreed to create several business errors to validate the input and the operation flow. You can see all the created business errors below
API Namespace
After desigining the domain namespace, Jack and Alexander covered important artefacts around the API namespace. API Namespaces are usually modelled with paths and operations that are designed for the API. In this section you can see the functions that the Notes and Minutes Management service exposes to the outside world in a standardized format (Open API).
The Notes and Minutes Management service provides several path which can be performed as part of the API. Paths are typically provided as endpoints for APIs. For each path in the Notes and Minutes Management service, multiple operations can be created to perform the desired action based on the HTTP verb.
Integration Namespace
As a last step, Integration namespaces are used to consume other REST APIs. As displayed earlier in the UML sketch and based on our previous discussions, it can be seen that for the Notes and Minutes Management service, Customer and Employee service has been integrated as external APIs. In this layer, each external API is represented by one namespace in the integration layer. The Notes and Minutes service integrates with the Customer service and the Employee service as external APIs, where each contain an API Dependency and modelled entities. First, Jack has uploaded the YAML file with all the dependencies needed in the API dependency section of each integration service. Then he proceeded to model and implement the entities. The entities modelled in the Customer service are Contact and Party. Where in the Employee service, the entities modelled are Employee and Person. Furthermore, Jack also added the services in each of the integration services. In the Services section, GetContact service is modelled in the Customer service, and GetEmployee is modelled in the Employee service.
Additionally, Jack has modelled and implemented the errors for each of the integration services. For the Customer service, the error modelled and implemented was CustomerNotFound, and likely in the Employee service, EmployeeNotFound.
Building and Deploying of the service
The next step is to develop the Notes and Minutes Management service using Java Domain Service. Ben, Clara and Julia had a discussion on how the service should be developed in details and started the development. They also agreed on testing criteria for the service. Once the service is developed and tested, it can be easily explored in the CI/CD section, and the Open API (using Swagger) can be tried by finding the deployed service in the dashboard.
While implementing this service, the tool also supports developers through code generation by creating pipeline.
You have covered important artefacts about Notes and Minutes Management service.