1. Introduction and Goals
The OpenWMS.org Common Service provides essential functionality to deal with Locations, LocationGroups and TransportUnits. An example
often referred to is the ability to move a TransportUnit from a Location A to a Location B. Beside this also other secondary resources
like TransportUnitTypes or rulesets like the PlacingRule to define what kind of TransportUnit can be put on what type of Location
are managed by this service.
1.1. Requirements Overview
The required and demanded functionality of the Common Service is comprised by the issues tracked in GitHub issue tracker. All open issues that are assigned to an upcoming milestone are accepted for implementation and will likely be implemented and released.
Open pending issues
| Issue ID | Planned Milestone | Title |
|---|---|---|
3.0.0 |
Migrate to SpringBoot 3.2.5 |
All functionality that is currently included, has already been implemented have issues assigned that are closed. A list of all closed issues with their resolved milestone release is shown below. Notice that issues may be closed but the implementation has been rejected.
Closed issues, either implemented or rejected.
1.2. Quality Goals
| Priority | Characteristic | Scenario | Activity | Risk |
|---|---|---|---|---|
HIGH |
Interoperability |
The service must be operated in a service mesh of services of arbitrary technologies |
The service API is implemented with HTTP and JSON exchange format |
— |
HIGH |
Performance |
The service must respond in less than 100ms |
This needs to be considered with the choice of the persistency mechanism |
Scalability: Increasing datasets could have an impact |
MEDIUM |
Accessability |
The service may run in a multi-tenant environment and all functions must be aware of multi-tenancy |
All API functions, services and persistency mechanisms must be aware of the tenant |
Performance: With increasing tenants this could have a negative impact on the performance with regarding data isolation |
3. System Scope and Context
3.1. Business Context
The Common Service is a central service used by many other services of the Transport Management (TMS) domain and the Warehouse Management (WMS) domain. It does not depend or use other OpenWMS.org services, hence it can be seen as one of the essential base services of each system.
| Name | Responsibility |
|---|---|
Common Service |
Base service of the COMMON domain responsible to manage |
User Interface |
An user interface, ie. for operators, may interact with the Common Service |
Transport Management Services |
All services of the automatic and manual transport management may access the Common Service directly |
Warehouse Management Services |
All services of the warehouse management domain may interact with the Common Service directly |
Exposed resources to API clients
| Name | Responsibility |
|---|---|
Location |
A |
LocationType |
A |
LocationGroup |
A |
Target |
A |
Account |
An |
TransportUnit |
A |
TransportUnitType |
A |
TypeStackingRule |
A |
TypePlacingRule |
A |
3.2. Technical Context
The Technical Context illustrates interfaces (channels and transmission media) linking the system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation with I/O uses which channel.
The Common Service exposes several resources over HTTP REST. The current available and detailed interface description can be found here. In addition the service sends event notifications out to surrounding services about master data changes and actions that occur within the service.
It offers an asynchronous API to trigger actions via commands from the outer world.
| Name | Type | Responsibility |
|---|---|---|
REST API |
Synchronous API over HTTP |
API to retrieve data from and to trigger actions on the Common domain objects |
common.lg |
RabbitMQ Exchange |
Outgoing exchange to send events according to changes on |
common.tu |
RabbitMQ Exchange |
Outgoing exchange to send events according to changes on |
common.tu.commands |
RabbitMQ Exchange |
An exchange where the Common Service sends out commands and requests to other services |
common-tu-commands-queue |
RabbitMQ Queue |
A queue bound to the own exchange to receive incoming commands or responses to sent out requests |
5. Building Block View
5.1. Whitebox: Common Service
The white box view gives a rough overview on how the Common Service is built internally. The service basically consists of two major
functional components, one to manage Locations and LocationGroups and another one to manage TransportUnits.
Contained Building Blocks
| Component | Responsibility |
|---|---|
app |
A package that contains lifecycle components of the Common Service, without any business value |
Index Controller |
This service provides an HATEOAS REST API with index resources to navigate across the primary resources |
Location Management |
Functional building block to manage |
Transport Management |
Functional building block to manage |
Location Tables |
A set of database tables belong and accessed by the Location Management |
Transport Tables |
A set of database tables belong and accessed by the Transport Management |
Important Interfaces
| Interface | Description |
|---|---|
REST API |
The public REST API is comprised of the Location Management API, the Transport Management API and an Index that lists and delegated to those two |
Async Command API |
The asynchronous Command API is exposed to trigger actions on the Location- and Transport Management resources |
5.1.1. Component: Location Management
As mentioned the Location Management cares about the resources Location, LocationGroup and Target. The software design of all three
primary resources is almost the same, hence the management of Location resources is shown here by example for the others.
All types are located in the Java package .location with several sub-packages.
| Component | Type | Responsibility |
|---|---|---|
api |
Package |
Contains all types that are exposed and also exported to service clients |
impl |
Package |
Contains all types that are private and implement the solution |
spi |
Package |
Contains interfaces and classes that can be used to extend the service implementation |
LocationApi |
Class |
An exposed class that defines the |
LocationController |
Class |
Is a Spring |
LocationService |
Interface |
Used by the |
LocationServiceImpl |
Class |
Spring managed transactional service that is the implementation of the business logic and the transaction boundary. In a internal package and kept package-private |
LocationRepository |
Interface/Class |
Either a Spring Data JPA implementation or some other technology that acts as a DAO and accesses the persistency layer in order to save and fetch |
COM_LOCATION |
Database Table |
The database table accessed by the repository, either mapped or directly accessed |
Extension Point |
<abstract> |
This could be some interface that is used by the business logic to break out the standard processes and allow some kind of extensions |
7. Deployment View
8. Cross-cutting Concepts
8.1. Configuration
The default service configuration is provided internally with a multi-profile application.yml YAML file. The default values are meant to
be overridden on any development or production environment, either by system variables or by a centrally managed configuration server.
In a distributed microservice environment a configuration server (OpenWMS.org Configuration Server) is used to provide environment specific configuration to all services and manage this in a single place.
If the configuration of the service is being updated on the configuration server, the service needs to be restarted in order to fetch the
configuration at startup. A second and better approach is to update the configuration of the service at runtime without any service
downtime. This can either happen via Spring Actuator endpoints (in a SYNCHRONOUS environment) or via RabbitMQ events in an ASYNCHRONOUS
environment with a RabbitMQ message broker.