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

4

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.

Issue ID State Assigned Milestone Title

3

closed

2.1.0

API for deletion of Locations and LocationGroups

2

closed

2.1.0

Migrate to Java 21

1

closed

2.1.0

Split into lib, ui and wrapper

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

2. Architecture Constraints

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.

Business Context

Name Responsibility

Common Service

Base service of the COMMON domain responsible to manage TransportUnits, Locations and LocationGroups. Functionality if offered as a REST API over HTTP and an asynchronous command API

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 Location, represents a physical or virtual place in a warehouse. Could be something like a storage location in the stock or a conveyor location. Even error locations can be represented with the Location. Multiple Locations with same characteristics are grouped to a LocationGroup

LocationType

A LocationType is the type of Locations with same characteristics

LocationGroup

A LocationGroup is a logical group of Locations with same characteristics

Target

A Target is either a physical or a logical endpoint of any kind of warehouse order. A TransportOrder has a Target assigned where it has to be moved to

Account

An Account encapsulates identifying information about the actual cost center

TransportUnit

A TransportUnit is an item like a box, a toad, a bin or a pallet that is moved within a warehouse and can carry goods. It can be moved between `Location`s

TransportUnitType

A TransportUnitType is a type of a certain TransportUnit. Typically to store characteristic attributes of TransportUnits, such as the length, the height, or the weight of TransportUnits

TypeStackingRule

A TypeStackingRule is a Rule that defines what TransportUnitType can be stacked on other types

TypePlacingRule

A TypePlacingRule is a Rule that defines what types of TransportUnits can be put on what type of Location

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.

Technical Context

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 Locations and LocationGroups

common.tu

RabbitMQ Exchange

Outgoing exchange to send events according to changes on TransportUnits and TransportUnitTypes

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

4. Solution Strategy

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.

Whitebox View Level1

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

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.

Whitebox View: location management

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

5.1.2. Component: Transport Management

tbd

5.1.3. Component: Account Management

tbd

6. Runtime View

6.1. <Runtime Scenario 1>

  • <insert runtime diagram or textual description of the scenario>

  • <insert description of the notable aspects of the interactions between the building block instances depicted in this diagram.>

6.2. <Runtime Scenario 2>

6.3. …​

6.4. <Runtime Scenario n>

7. Deployment View

7.1. Infrastructure Level 1

<Overview Diagram>

Motivation

<explanation in text form>

Quality and/or Performance Features

<explanation in text form>

Mapping of Building Blocks to Infrastructure

<description of the mapping>

7.2. Infrastructure Level 2

7.2.1. <Infrastructure Element 1>

<diagram + explanation>

7.2.2. <Infrastructure Element 2>

<diagram + explanation>

…​

7.2.3. <Infrastructure Element n>

<diagram + explanation>

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.

9. Design Decisions

10. Quality Requirements

10.1. Quality Tree

10.2. Quality Scenarios

11. Risks and Technical Debts

12. Glossary

Term Definition

<Term-1>

<definition-1>

<Term-2>

<definition-2>