Project Organization

When starting a new project, it is worth considering a few things about project organization. To establish a change-friendly, clear project organization, you should consider the following topics:

1. When to use a single service, when to split into multiple services?

2. When to outsource recurring functions to basic services or libraries?

3. How to version services?

4. How to structure a service in the Designer?

5. Where to log changes?

How to Organize a (Micro)Service

How you manage your service in the Designer is a matter of taste. However, we would like to share some important points from our many years of project experience with you and give you some tips for effective service management in the Designer.

Service Size

There are basically two different ways to approach a microservice:

• You can create it based on business logic.

• You can create it based on technical/functional logic.

With both approaches, you should consider whether you want to structure your project in a modular way - and how you can implement this.

Some practical tips:

• Try to build small services with clearly defined tasks.

  • If the contents of the service stray too far from the core logic, split the service.

  • If a process is so large that you cannot see at a glance what functions it provides, it is probably too large (this also applies to Action Script or JavaScript code).

  • For integration projects, we recommend to follow the integration path concept.

• Organize independent service functions into different services.

• If several services have a common part, extract this part into a library.

• If tasks have certain dependencies, you can still create separate services, with one service calling the other.

  • Another solution is to create a single service and organize the model using packages.

• In cases of strong dependency, e.g., many calls and/or exchange of large amounts of data, a single service is well suited.

• Try to consider possible service enhancements right from the start.

  • Don't be afraid to put in the effort to move constants, settings, etc. into separate packages (see below). This makes it easier to adapt and expand them later on.

  • If you realize later in the project that a service is too large, don't be afraid to split it up at a later date.

The Main Goals

Clarity. Maintainability. Expandability.

Don't pack too many processes into one service. Instead, design it according to the rule of thumb “as small as possible, as large as necessary.”
The more modular a project is structured, the easier it is to maintain and to expand later in its lifetime.

Libraries and Base Services

You don't have to build recurring functionality multiple times. Consider whether it would make sense to build a base service or create a library instead. Give some thought to the organization of your library and base services and how you organize them in your folder structure.

Implementation Type	Use when?	Advantages
Base Service	A third party wants to use the functionality, too, via web service. Complex interfaces need to be simplified.	Base services can be developed and deployed separately. If the backend interface changes, the interface of a basic service does not necessarily have to be changed. Drawback: If the base service interface changes, all consumers must change, too.
Library	You need an implementation in more than one service. Instead of copying the same implementation into several services, create reusable libraries. You want to encapsulate a special functionality of an operation. Ideal for shared forms, business logic, utility functions, or data models. Expert Advice Create a separate service for each new library. Refer to Library Development for more details.	Better version control through logic version within library model. Better control, when a changed library is deployed within a service.

Versioning

Versioning is an important topic to consider when you develop services and libraries in the Designer. It describes the process of assigning a unique version number to a unique state of your service or library.

When to Set a New Logical Service Version Number

If you deploy a service in the Designer, you must enter a version number in the deployment controls. The version number must be compliant with SemVer format (major.minor.patch). You should create a new version at least after every milestone reached. Don't forget to document the change as described in Where to Log Changes further below. Refer to Versioning of Services for more details.

When to Set a New Logical Library Version Number

Create a separate Designer service for each library that you develop. The library version number is set in the deployment controls. The version number must be compliant with SemVer format (major.minor.patch). Change the library version number after implementing a new requirement, that will be deployed and don't forget to document the change as described in Where to Log Changes further below.

If you have made changes to a library, you should not upload it again under the same version name. This can lead to problems in the Designer. Therefore, we recommend to work with pre-release tags during the development phase. For example, you can add a suffix to the release version like 1.1.0-alpha. When the library development is finished, delete the tag and use the version as the official library version number: 1.1.0.

Refer to Versioning of Libraries for more details.

Service Structuring

Expert Advice

Apply the same naming conventions and organization of the Implementation folder to all your Designer projects. This makes reading a model much easier.

Refer to Naming Conventions for our recommendations for naming Service panel content.

The Service panel in the Designer gives you access to all contents of your service such as your BPMN models, your forms, connectors and APIs. The panel provides a content structure, e.g. BPMN models are saved in folder Process, forms in the Forms folder etc. You can create subfolders to further structure the contents.

In the Service panel, you can also find the folder Implementation. This is the only folder, where you can apply your own content structure. Think carefully about how you want to structure this folder. Using the same naming conventions and content organization…

• … makes reading a model much easier.

• … helps you find the same content faster across all services.

• … is particularly helpful in large projects, as other developers can find their way around more quickly.

To keep the contents of the Implementation folder clear, do not create too many packages on the first hierarchy level, use subpackages instead.

Some examples for packages that we create in projects:

The package names listed in the table are frequently used in small to medium-sized services.

For larger services that cover different areas, we recommend placing the modules at the top levels:

• SAP

  • Sales

  • Purchasing

• Salesforce

• …

Package	Description	Hierarchy
API	used in services with API interface contains all API-related elements (if additional elements are required in addition to the content included in the standard API folder)	subpackage of Data Model
Constants	mainly used in integration services contains all constants used in the service Constants are values that are used in multiple places within the service. The more often a value is used in a service, the more sensible it is to create a separate constant for it.	main package
DataModel Other names used: Classes Operations Processes Services	Variant: packages named after the various processes, e.g., Approval, Review... contains all classes required for the service is further structured with subpackages e.g. Interfaces, Types…	main package
ExternalSystems	create one subpackage for each external system or database, e.g. MongoDB, MySQL, Salesforce… contains all elements related to the external system	main package
FormsImpl	used in services with UI package contains everything needed to implement a form (if additional elements are required in addition to the content included in the standard Forms package)	main package
Helpers Other names used: Utils	contains helper classes that provide central functionality used in several places in the implementation basically, the contents of this package are similar to a library, but are only used in this one service use subpackages to further structure the content, e.g. MappingHelpers, SalesforceHelpers…	main package
Logging	used in services with implemented logging contains all logging-related elements Refer to Logging for more information.	main package
Mapping	used to summarize all mapping classes / mapping operations of the service Refer to Mappings for more information.	subpackage of Data Model or Helpers
Settings	used in most of the services contains all settings classes used in the service use subpackages to further structure the content, e.g. MailSettings, SAPSettings… Refer to Settings for more information.	main package
Translation	possibl used in services with UI, where different languages are supported contains all translation-related elements	main package or subpackage of Data Model
Types	used to summarize all types used in the service	subpackage of Data Model

Where to log changes?

A change log is a useful companion. We recommend to create a change log for each version of a service in which you summarize the most important changes. For services, we recommend to add the change log in the service description (refer to Designer Guide > Service Configuration Details).

Create a table with at least:

• the date

• the version number

• a description what has been done

• the name of the author

• Optional, but recommended: A comment, if a new version of a library is used.

Expert Advice

If you use a ticket system for development, also add the ticket number(s) or link directly to the ticket comment that relates to the last changes.

Using Source Code Management Systems

A source code management system (SCMS) like git can help you to store the Designer services and to create a change log.

We recommend that you check in at least the following content in your SCMS:

• an export of your Designer service (.zip file)

• an export of the compiled service (.rep file)

• exports of your libraries

In the case of git, you use tags to mark commits that relate to a specific version and commit messages to document your changes.

We recommend to also check in all specification sources (e.g. XSD, DDL, WSDL, CSV) to your source code management system.