Message Definitions

Last modified: February 12, 2024

1 Introduction

Message definitions define the structure of the messages that are sent from and to your app. Defining your messages allows you to create import and export mappings for them.

A message definition can be used for both JSON and XML and can be used for both single objects and lists of objects.

2 Adding a Message Definitions Document

Message Definitions is a type of document you can add to modules in your app.

To add a message definitions document, do the following:

  1. Right-click your module or a folder within a module.
  2. Choose Add other > Message definitions.
  3. Give your message definitions a name and click OK.

3 Managing Message Definitions

The message definition document shows a list of message definitions.

Here you can do the following:

  • Add a new message definition
  • Edit an existing message definition
  • Delete an unwanted message definition
  • Find usages of a message definition
  • Generate mapping(s)… from a message definition (see below)

3.1 Generate Mapping(s)…

The Generate mapping(s)… button allows you to generate import and/or export mapping documents from the selected message definition. The mappings are added to your module.

To generate mappings, do the following:

  1. Select the message definition you want to use.

  2. Click Generate mapping(s)….

  3. Ensure that the required mapping (or mappings) is selected.

  4. Click OK.

    General mappings dialog

4 Defining a Message Definition

In the message definitions document, click Add to create a new message definition or Edit to edit an existing message definition.

4.1 General

The message definition is defined in the General tab.

The Message Definition General tab

4.1.1 Name

The name of the message definition.

4.1.2 Entity

An entity in your app domain model (or models) on which to base the message definition. Using this message definition, you can export and import individual objects and lists of objects of this entity type.Ω

4.1.3 Structure

The structure tree shows the attributes and some of the associations of the entity. Use the Filter to find specific attributes.

Column Description Can edit? Notes
Checkbox Check if the attribute or association is part of the message. y
Name The name of the item in the domain model. n
Type The type of the item in the domain model. n
Occurrence How many times this item can occur for each parent item. n
External Name The name of the XML node or the JSON property. y By default, the name of the attribute or (for associations) entity.
For a 0..* occurrence, a letter s is added.
External Single Item Name The XML node that represents a single item. y Only relevant for XML when the occurrence is 0..*
By default, the entity name.
Example value A typical value for an attribute. y For a published REST service, this value shows up in the interactive documentation.
A date/time value is specified in the format year-month-day or year-month-day hour:minute:second.
Public Documentation Additional information to be displayed in the interactive documentation. y

4.2 Documentation

Use the Documentation tab to describe what the message definition is used for.