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.
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
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:
| Issue ID | State | Assigned Milestone | Title |
|---|---|---|---|
| 86 | closed | 2.0.0 | Upgrade to SpringBoot 2.7.0 |
| 83 | closed | 2.0.0 | Fix sonar build - cause of MapStruct and JaCoCo |
| 81 | closed | 1.7.0 | Add API to update a Location |
| 80 | closed | 1.7.0 | Add API to add a Location |
| 78 | closed | 1.7.0 | Add an arbitrary sort index field to the Location |
| 77 | closed | 1.7.0 | Provide async API to lock for empty Locations |
| 76 | closed | 1.7.0 | When a TU is moved the actualLocation of the children is not moved |
| 75 | closed | 1.7.0 | Extend API to search a Location by ERP Code |
| 74 | closed | 1.7.0 | Migrate to latest Dozer version (6.x) |
| 70 | closed | 1.7.0 | Migrate from TravisCI to Github Actions |
| 69 | closed | 1.7.0 | Offer simple API to read LocationTypes |
| 66 | closed | 1.7.0 | Entities LocationGroup and Location miss some setters |
| 65 | closed | n/a | Can UI display interface be provided ? |
| 64 | closed | 1.7.0 | Migrate to Spring Boot 2.3.7 |
| 63 | closed | 1.7.0 | Dead Letter Queue handling of poising messages |
| 62 | closed | n/a | Could you please give me a detailed document on openwms |
| 60 | closed | 1.7.0 | Extend Location about tags |
| 59 | closed | 1.7.0 | A Location should be able to hold Products directly |
| 58 | closed | 2.0.0 | Migrate to latest SpringBoot 2.6.x & Java 17 |
| 56 | closed | 1.6.0 | Move to SpringBoot 2.3 |
| 55 | closed | 1.6.0 | Location should groupable |
| 54 | closed | 1.7.0 | Configuration must be changeable without restarts |
| 50 | closed | 1.6.0 | Propagate updates on TransportUnitType changes |
| 49 | closed | 1.6.0 | Introduce Accounts |
| 47 | closed | 1.5.0 | Provide a request interface |
| 46 | closed | 1.5.0 | Remove all transitive dependencies from the client jar |
| 43 | closed | 1.5.0 | Static assigned query params cannot be accessed over Feign |
| 42 | closed | 1.5.0 | Make it an extendable service |
| 40 | closed | n/a | Implement API Security |
| 38 | closed | 1.5.0 | Improve API documentation |
| 37 | closed | 1.4.0 | Track changes on TransportUnits |
| 35 | closed | 1.4.0 | Replace Hystrix with resilience4j |
| 32 | closed | 1.4.0 | Generate DB schema within build |
| 27 | closed | 1.4.0 | Tests shall run in isolation |
| 26 | closed | 1.4.0 | Ensure software architecture in tests |
| 22 | closed | 1.4.0 | Expose Targets through an API |
| 19 | closed | 1.4.0 | Enable ability to run without config server |
| 18 | closed | 1.4.0 | Fix Jacoco code coverage |
| 17 | closed | 1.4.0 | Migrate to JUnit5 |
| 14 | closed | 1.4.0 | A LocationGroup can be locked by its own |
| 13 | closed | 1.3.0 | RemovalListener mechanism not working in a distributed environment |
| 12 | closed | n/a | Provide DI exporter |
| 7 | closed | 1.2.0 | Propagate at least Move events |
| 3 | closed | n/a | Implement simplest stock allocation strategy |
| 2 | closed | n/a | Get logstash running with Heroku |
| 1 | closed | 1.2.0 | Add demo data |
| 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 |
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 |
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 listens on commands and requests from other services |
common-tu-commands-queue |
RabbitMQ Queue |
A queue bound to the own exchange to receive incoming commands or requests |
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 Locations and LocationGroups
|
| Transport Management | Functional building block to manage TransportUnits and TransportUnitTypes
|
| 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 |
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 Location API and that can be used directly ba Java clients |
| LocationController | Class | Is a Spring RestController implementation of the LocationApi and resides in the main package |
| LocationService | Interface | Used by the LocationController within the same package to avoid package dependencies (An interface is always public) |
| 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 Locations
|
| 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 |
tbd
tbd
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.