SAP Logistics Business Network, Global Track and Trace Option - Basic Modeling Tutorial - SAP Help Portal
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
SAP Logistics Business Network, Global Track and Trace Option
Basic Modeling Tutorial
Document Version: LBN 2.0 – 2020-04-28
Tutorial
PUBLIC
TABLE OF CONTENTS
1 BASIC MODELING – A STEP BY STEP TUTORIAL ....................................................................3
1.1 About this Document .....................................................................................................................3
1.2 Target Audience ............................................................................................................................3
1.3 Documentation References ...........................................................................................................3
1.4 Supplied Models ............................................................................................................................3
2 OVERVIEW ...................................................................................................................................4
3 PREREQUISITES .........................................................................................................................5
4 LESSON 1: PARCEL TRACKING .................................................................................................6
4.1 Step 1: Create a GTT Model ..........................................................................................................6
4.2 Step 2: Define a Basic Model .........................................................................................................9
4.3 Step 3: Deploy Your Model .......................................................................................................... 18
4.4 Step 4: Create and Assign a Business Role ................................................................................. 20
4.5 Step 5: Provide the Data.............................................................................................................. 25
4.6 Step 6: Track Parcel Deliveries in the GTT App ........................................................................... 27
4.7 Step 7: Add Information Blocks to the Object Page ...................................................................... 31
4.8 Step 8: Add Parcel Items to the Object Page ............................................................................... 34
4.9 Step 9: Add Event Entities ........................................................................................................... 40
4.10 Step 10: Track Events in the GTT App ......................................................................................... 45
4.11 Step 11: Report a Planned Event from the GTT App .................................................................... 50
4.12 Step 12: Create a Business Rule ................................................................................................. 53
4.13 Step 13: Report an Unplanned Event from the GTT App .............................................................. 62
4.14 Summary..................................................................................................................................... 66
5 CREATE A GTT MODEL BASED ON A TEMPLATE MODEL ....................................................67
2
1 BASIC MODELING – A STEP BY STEP TUTORIAL
1.1 About this Document
This document guides you through the process of creating a basic Global Track and Trace (GTT) model from
scratch, in a step-by-step manner.
Before you start working through this document, ensure that you have the most recent version of this
document that is available from the SAP Help Portal at:
https://help.sap.com/gtt
1.2 Target Audience
A Modeling Expert or Solution Administrator who needs to create, define, deploy, and maintain GTT models
in the global track and trace option for SAP Logistics Business Network.
1.3 Documentation References
Throughout this tutorial, references are made to other GTT documentation, such as the GTT Administration
Guide and Onboarding Guide. The latest versions of all GTT documentation are available from the SAP Help
Portal at:
https://help.sap.com/gtt
1.4 Supplied Models
Various steps in Lesson 1 mention supplied models, for example:
• Model_1_base
• Model_2_details
• Model_3_items
• Model_4_events
The Create a GTT Model Based on a Template Model section also mentions an example GTT model that is
created from a shipment template model.
All these models are provided for reference only and are available from:
https://github.com/SAP-samples/gtt-tutorial-models/
3
2 OVERVIEW
The global track and trace option for SAP Logistics Business Network is a solution used to capture, process,
and store tracking information about business processes. It provides real-time transparency of the execution
of those processes. You can query a tracked process and display its retrieved data from end to end.
Before you can track and trace with the solution, a GTT model must be created to define the metadata of a
tracked process.
In this tutorial, you'll create a basic GTT model based on a parcel tracking application. The business process
of the application is as follows:
• A parcel is delivered from a shipper to a receiver, which involves:
o A courier picking up the parcel at the shipper location and delivering it to a distribution hub.
o Another courier picking up the same parcel from the distribution hub, and delivering it to a receiver
location.
After completing this tutorial, you'll learn the following:
• How to define a GTT model to track process and event data, such as parcel ID, shipper/receiver name
and location, as well as shipping statuses like "picked up from sender."
• How to monitor the business process information tracked by the GTT model.
• How to create a business rule for a GTT model to automatically trigger an action upon a certain
condition, for example, sending an email to a recipient when an unplanned event occurs.
4
3 PREREQUISITES
To perform the tasks outlined in this tutorial, you must have fulfilled the following:
• You must have access to a running GTT solution.
For detailed onboarding procedures, refer to the Onboarding Guide.
• In your GTT solution, you must have the Solution Administrator business role for accessing the
following apps: Metadata Modeling (MM), GTT Model Management (GMM), Manage Business Roles
(MBR), and Manage GTT Users (MGU).
Note
The MM and GMM apps can also be accessed by the Modeling Expert role.
The MGU app can also be accessed by the User Administrator role.
The MBR app can only be accessed by the Solution Administrator role.
Information on configuring business roles can be found in the Onboarding Guide: Configure Identity
Authentication Service.
• Some steps use an external sender system such as Postman. To use any external sender system, you
need the credentials for a technical user to enable the connection between systems.
For more information on how to maintain a technical user, see the Onboarding Guide: Create a
Technical User and Maintain the Technical User for Your Company.
• Some steps describe tasks involving business rules. To perform these tasks, the relevant configuration
must be made in the Onboarding Assistance app à System Integration tab à SAP Cloud Platform
Business Rules and Email Notification – Rule Action.
Detailed configuration steps are described in the Onboarding Guide: Maintain System Integration
Information in Onboarding Assistance App.
5
4 LESSON 1: PARCEL TRACKING
4.1 Step 1: Create a GTT Model
Before you can track a parcel delivery process in the GTT app, you must first create a GTT model to define
the process and events that you want to track. This is done in the Metadata Modeling (MM) app, also known
as the Global Track and Trace plugin for SAP Web IDE.
A GTT model is in a specific GTT project associated with a specific namespace. In this tutorial, you'll create
a GTT project with the namespace: com.sap.gtt.app.tutorial.parceltracking
Concepts
The first decision in any modeling work is which mode to use, standard (the default) or simple.
• Standard mode defines your GTT model with complete model and UI layout information. A standard-
mode GTT model consists of several model files to define the model itself, the services, and the UI
annotations, separately.
• Simple mode simplifies modeling by defining your GTT model with basic layout information in only one
model file. Simple mode does not support all modeling functionality. For more information, see the
Creating and Deploying GTT Models guide: Creating and Deploying Models à Simple and Standard
Modes.
Throughout this tutorial, we use standard mode.
Procedure
To create a GTT model from scratch, proceed as follows:
1. Log in to the SAP Web IDE for Full-Stack Development application.
2. If you haven't already done so, enable the Global Track and Trace plugin on the Features page as
follows:
a) In the Tools menu, choose Preferences.
b) In the left-hand pane, select Features.
c) In the Features view displayed in the right pane, scroll down, switch on Global Track and Trace and
choose Save.
6
d) Reload the SAP Web IDE Full-Stack application by refreshing the browser.
3. Choose File à New à Project from Template.
A wizard appears as follows:
4. On the Template Selection page, choose Global Track and Trace in the Category list, and choose Next.
5. On the Basic Information page, type tutor1 as the project name for your GTT project and choose Next.
7
6. On the Project Customization page, make the following entries:
o Mode: Standard
o Template: None
We'll create the parcel tracking model from scratch, so don't use any template.
o Namespace: com.sap.gtt.app.tutorial.parceltracking
The namespace must be unique in a GTT tenant.
Note
If you specify a different namespace here, then in all the model CDS files that you will edit in proceeding steps, you
must replace the occurrences of com.sap.gtt.app.tutorial.parceltracking with the namespace you
specify.
o Version: 1.0.0
o Process Name: Parcel Tracking
o Dependency: None
o Description: Parcel Tracking Tutorial Model
7. Choose Finish.
Result
A GTT project that has a parcel tracking model in it. Your screen should look like the following:
8
4.2 Step 2: Define a Basic Model
Previously, you created a GTT project that has a GTT model in it.
In this step, you'll start defining your model by specifying the type of business process and the fields that you
want to track.
Concepts
• CDS Definition Language
The language used in GTT modeling is the CDS Definition Language. CDS defines entity-relationship
models with annotations. Such models can be easily interpreted by compilers and thus transferred to
other formats.
Note
For more information on the CDS Definition Language, see the Creating and Deploying GTT Models guide:
Modeling Language Guide à Introduction to CDS.
• GTT Model Files
A standard-mode GTT model consists of several CDS model files. Each CDS model file is a readable
text file so you can use a text editor to view its contents.
To define your parcel tracking model in this tutorial, you need to edit the following model files that were
automatically created for you:
File Purpose
tutor1Model.cds Defines the metadata model (tracked process and events) for the
parcel tracking application.
tutor1Service.cds Exposes the necessary entities as a service.
tutor1UI.cds Provides the UI annotations for SAP Fiori elements for the parcel
tracking application.
tutor1WriteService.cds Exposes the necessary entities as a service for processes and
events ingestion, which allows you to use model-specific rest
APIs.
A swagger file will be generated based on the definitions in this
file. You can then view the swagger file in the GTT Model
Management app.
Note
This tutorial does not involve tasks to use model-specific rest APIs, so you don't need to edit the
tutor1WriteService.cds file. You can leave the file as is. The steps for editing this file are provided for reference only.
9
• GTT Core Model and Application Model
A GTT core model includes generic fields that are not relevant to specific business, for example, tracking
ID, tenant, event status, etc. The core model is predefined and you are not able to modify it.
The model you are defining is called a GTT application model. An application model extends the core
model with user-defined entities and fields. If you want to use some entities and fields that are already
defined in the core model, you have to inherit them in your application model.
When you deploy your application model, the inherited core model entities and fields are automatically
appended to your run-time GTT model.
Note
For more information on core model details and different types of application models, see the Creating and
Deploying GTT Models guide: Modeling Language Guide à GTT Metadata Model with CDS.
• Entities and Fields
A GTT model contains multiple entities. For example, within your process you can have:
o an entity for a tracked process type, and
o several entities for the planned or unplanned event types that you want to track.
For each entity, you can add fields to define the type of data that you want to track.
10Procedure
To define your GTT application model, proceed as follows:
1. In the SAP Web IDE for Full-Stack Development application, also called the Metadata Modeling app
(MM app) for GTT, choose Development ( ).
2. In the left-hand pane, navigate to the Workspace folder.
3. Under Workspace à tutor1 à model, double-click the tutor1Model.cds file.
As shown in the following screenshot, the file is opened in a text editor in the right-hand pane. Note that
the first line, also known as a script, is the namespace you specified when creating your GTT project.
114. In the right-hand text editor, copy and paste the following scripts after the first line of the tutor1Model.cds
file:
using com.sap.gtt.core.CoreModel;
context ParcelTrackingModel {
//Tracked process "Parcel Tracking"
entity BaseParcelTrackingProcess {
parcelId : String(10) @title:'Parcel ID';
shipper : String(20) @title: 'Shipper';
shipperlocation : String(255) @title: 'Shipper Location';
receiver : String(20) @title: 'Receiver';
receiverlocation : String(255) @title: 'Receiver Location';
@CoreModel.KeepStatusSequence: true
shippingStatus : String(50) @title:'Shipping Status' enum {
notStarted='01' @title: 'Not Started'; //Parcel process not started
pickingCompleted='02' @title: 'Picking Completed'; //Goods picked up
received='03' @title: 'Received'; //Goods received
} default '01';
};
@CoreModel.StatusProperties : ['shippingStatus']
@CoreModel.Indexable : true
entity ParcelTrackingProcess : CoreModel.TrackedProcess,
BaseParcelTrackingProcess{};
entity ParcelTrackingProcessForWrite : CoreModel.TrackedProcessForWrite,
BaseParcelTrackingProcess{};
entity AllTrackedProcessForParcelTrackingProcess : CoreModel.AllTrackedProcess,
BaseParcelTrackingProcess{};
//Data provision from SAP ERP or other external sender systems
@CoreModel.UsageType: #inboundMessage
@SAP_EM.applicationObjectType: 'OB_PT_00'
@SAP_EM.primaryTrackingIdType: 'PAR_00'
entity ParcelTrackingProcessInbound as projection on ParcelTrackingProcess {
@SAP_EM.fieldName : 'PAL_ID'
parcelId,
@SAP_EM.fieldName : 'SHIPPER'
shipper,
@SAP_EM.fieldName : 'SHIP_LOC'
shipperlocation,
@SAP_EM.fieldName : 'RECEIVER'
receiver,
@SAP_EM.fieldName : 'REC_LOC'
receiverlocation,
@SAP_EM.fieldName : 'SHIP_STAT'
shippingStatus
};
};
Note
You can ignore red errors which appear typically on using and service statements. The editor cannot interpret
these specific GTT statements so it shows them as errors.
12o The using statement in the first line is used to reference the GTT core model.
o The context ParcelTrackingModel statement prefixes names of nested definitions with
ParcelTrackingModel.
o The entity BaseParcelTrackingProcess section defines a tracked process entity
BaseParcelTrackingProcess and its properties.
For example, the first property
parcelId : String(10) @title:'Parcel ID';
defines a field parcelId. Its data type is string. The field length is at most 10 characters. On the
track and trace user interface, the field title is Parcel ID.
o entity ParcelTrackingProcess : CoreModel.TrackedProcess,
BaseParcelTrackingProcess{};
defines a tracked process entity ParcelTrackingProcess, which inherits fields from the
CoreModel.TrackedProcess and BaseParcelTrackingProcess entities.
o entity ParcelTrackingProcessForWrite : CoreModel.TrackedProcessForWrite,
BaseParcelTrackingProcess{};
defines a tracked process entity ParcelTrackingProcessForWrite, which is used by rest API write
service. It inherits fields from the CoreModel.TrackedProcessForWrite and
BaseParcelTrackingProcess entities.
o entity AllTrackedProcessForParcelTrackingProcess : CoreModel.AllTrackedProcess,
BaseParcelTrackingProcess{};
defines an entity for including different process types. This entity can be used to achieve some
advanced features such as tracking packing hierarchy, etc.
Note
For detailed information on how to define entities, see the Creating and Deploying GTT Models guide: Modeling
Language Guide à Language Elements à Entity Definitions.
Note
The process and field names defined in the GTT model can be displayed in different supported languages in the
track and trace apps. To make that possible, you need to adjust your model. For example, in the tutor1Model.cds
file, instead of using @title:'Parcel ID', write @title:'{@i18n>Parcel_ID}'. Then in the i18n files for
specific languages, provide the exact values for {@i18n>Parcel_ID}.
In this tutorial, we do not explain the i18n files, used to support languages on the UI. If you need information on this,
see the Creating and Deploying GTT Models guide: Creating and Deploying Models à Multi-Language Support.
o The //Data provision part is used for receiving tracking data from a connected ERP system or an
external sender system. This is needed if standard iFlows are used. For more information, see:
https://api.sap.com/package/SAPGlobalTrackTraceInterfaceTrackedProcessesandEventMessages?
section=Overview
Note
The values of @SAP_EM.applicationObjectType and @SAP_EM.primaryTrackingIdType must be unique in
a GTT tenant.
135. Under Workspace à tutor1 à service, open the tutor1Service.cds file, and add the following scripts to it:
using com.sap.gtt.app.tutorial.parceltracking.ParcelTrackingModel;
using com.sap.gtt.core.CoreServices.TrackedProcessService;
using com.sap.gtt.core.CoreModel;
service ParcelTrackingService @extends: TrackedProcessService {
@CoreModel.UsageType: #userInterface
@CoreModel.MainEntity: true
entity ParcelTrackingProcess as projection on
ParcelTrackingModel.ParcelTrackingProcess excluding {
tenant, name, trackedProcessType,
lastProcessedEvent,
CreatedByUser, CreationDateTime,
LastChangedByUser, LastChangeDateTime
};
entity AllTrackedProcessForParcelTrackingProcess as projection on
ParcelTrackingModel.AllTrackedProcessForParcelTrackingProcess;
};
o If used, the using statements must be written in the following order from top to bottom:
• Service, e.g. ParcelTrackingService
• Model, e.g. ParcelTrackingModel
• CoreServices
• CoreModel
• CoreType
o The @extends: statement is used to extend your application service from the core service.
o The entity … as projection on statement defines the association or composition in the service
the same way as they are defined in the model.
Note
For more information on how to define services, see the following sections in the Creating and Deploying GTT
Models guide:
• Modeling Language Guide à GTT Metadata Model with CDS à Core Model Details à Core Model
• Modeling Language Guide à GTT Metadata Model with CDS à Application Model Details à Delivery
Application Model à Delivery Application Service
146. Under Workspace à tutor1 à service, open the tutor1UI.cds file, and add the following scripts to it:
using com.sap.gtt.app.tutorial.parceltracking.ParcelTrackingService;
//Annotations for Parcel Tracking
annotate ParcelTrackingService.ParcelTrackingProcess with @(
Common: {
Label: 'Parcel Tracking',
SemanticKey: [ parcelId ],
FilterExpressionRestrictions: [],
},
UI: {
Identification: [
{Value: parcelId},
],
HeaderInfo: {
TypeName: 'Parcel Delivery',
TypeNamePlural: 'Parcel Deliveries',
Title: {
Label: 'Parcel Tracking',
Value: parcelId
},
Description: {
Label: 'Parcel Tracking',
Value: description
}
},
SelectionFields: [
parcelId
],
PresentationVariant: {
SortOrder: [
{Property: parcelId, Descending: true}
]
},
},
Capabilities: {
Insertable: false, Updatable: false, Deletable: false,
FilterRestrictions: {
NonFilterableProperties: [
shipper,
description,
sender,
receiver,
shippingstatus,
shipperlocation,
shipperlocation
]
},
SortRestrictions: {
NonSortableProperties: [
shipper,
description,
sender,
receiver,
shippingstatus,
shipperlocation,
shipperlocation
]
},
15SearchRestrictions: {
Searchable: false
}
},
) {};
//Line items for lists on Overview page
annotate ParcelTrackingService.ParcelTrackingProcess with @UI.LineItem: [
{Value: parcelId},
{Value: shipper},
{Value: receiver},
{Value: shippingStatus}
];
UI annotations are used to display the tracked process and events data in the GTT app UI. The GTT app
has an Overview page to show a list of tracked process instances in a tabular format, and an Object
page to show details of each tracked process instance. The above scripts mainly define the UI layout on
the Overview page. You will define more UI annotations for the Object page later.
The UI annotations used in the above scripts are described below:
o annotate with @ defines the UI layout.
o The common block defines the overall behavior for the Overview page:
• Label is the process title shown on the page.
• SemanticKey is an array of field names that will be displayed in bold font in the processes list.
o The UI block defines what the Overview page looks like:
• Identification is a list of field names that uniquely identify the tracked process.
• HeaderInfo defines the header of the processes list table on the Overview page.
• SelectionFields define a list of field names that are initially visible as search filters on the
Overview page.
• PresentationVariant defines how the result is displayed in the processes list table. A GTT
model only allows SortOrder, which is a list of sort criteria for the default sorting.
o In the capabilities block:
• Insertable, Updatable, and Deletable define whether a process instance can be inserted,
updated, or deleted from the UI. In a GTT model these values must be false.
• FilterRestrictions defines restrictions on the filter capabilities of the processes list. A GTT
model only allows NonFilterableProperties, which is a list of field names that cannot be used
as filter criteria.
• SortRestrictions defines restrictions on the sort capabilities of the processes list. A GTT
model only allows NonSortableProperties, which is a list of field names that cannot be used
as sort criteria.
o annotate with @UI.LineItem: [] defines the appearance
of the processes list table on the Overview page. Value is the field name that appears in the list
table.
Note
For more information on UI annotations, see the Creating and Deploying GTT Models guide: Modeling Language
Guide à GTT Metadata Model with CDS à UI Annotations.
167. (This step is optional. If you don't want to use model-specific rest APIs, you can skip this step.)
Under Workspace à tutor1 à service, open the tutor1WriteService.cds file, and add the following scripts
to it:
using com.sap.gtt.app.tutorial.parceltracking.ParcelTrackingModel;
using com.sap.gtt.core.CoreServices.TrackedProcessWriteService;
using com.sap.gtt.core.CoreModel;
service ParcelTrackingWriteService @extends: TrackedProcessWriteService {
entity ParcelTrackingProcess as projection on
ParcelTrackingModel.ParcelTrackingProcessForWrite excluding {
shippingStatus
}
actions {
@Swagger.POST
action parcelTrackingProcess(@Swagger.parameter: 'requestBody'
parcelTrackingProcess: ParcelTrackingProcess) returns String;
};
};
The settings in this file expose the entities as a service for post and event ingestion, which allows you to
use the model-specific rest APIs. You can use rest APIs to provide data to the model.
8. Choose File à Save All.
Result
Now in your parcel tracking application, you have defined the basic entities, exposed the required services,
and defined the UI layout.
For reference, you can see and compare your model with the supplied model: Model_1_base.
174.3 Step 3: Deploy Your Model
Previously, you defined a basic parcel tracking model. The model is still in design time.
In this step, you'll deploy your model to the run time repository and activate it. When a GTT model is
activated, it starts tracking the defined processes and events.
Concepts
The deployment of a GTT model includes the following three successive steps.
1. Compile checks the model definition for errors. A model with compilation errors cannot be deployed.
You must fix the errors before deploying it.
2. Deploy sends the model metadata, together with the core model metadata it references, from design
time to run time.
3. Activate sets the model status to Active, which means the model now starts tracking process and
events.
Optionally, you can Preview a compiled model in the MM app. The preview imitates what the model looks in
the GTT app, thus helping you debug your model before it is deployed. Note that the preview uses mock
data so you don't need to provide data for it.
Procedure
To deploy your model, proceed as follows:
1. In the left-hand pane, right-click the tutor1 project folder and choose Deploy à Compile GTT Model.
This starts the compilation. You see a message "Model compiled" when it completes.
If errors are found, a message box pops up showing error details. To continue, your model must contain
no errors.
2. Right-click the tutor1 project folder and choose Deploy à Preview GTT Model.
This opens a preview window in a web browser window, which allows you to see how your GTT model
looks and feels like in the GTT app. Note that the preview shows mock data only. For more information
on the GTT app see the Tracking and Tracing Guide.
183. Now you are satisfied with your model, you can deploy it to the runtime repository. To deploy the model,
right-click the tutor1 project folder and choose Deploy à Activate GTT Model.
This starts the deployment process. Successive messages pop up in the upper-right corner of the MM
app window. When the deployment completes, you see a message "Model … has been deployed". You
can also choose the (Console) icon on the right edge of the window to open the Console to observe
the deployment progress, as shown below:
Note
You can also skip the previous steps and directly choose Activate GTT Model. The system then runs compilation,
deployment, and activation in a single step.
Result
When the deployment completes, the Console displays the message "Model … has been deployed". The
status of your deployed model is now Active. This means that your model is now available in your tenant for
tracking.
As we’ll see later, any messages it receives in the appropriate format will be tracked (stored) and then can
be queried.
194.4 Step 4: Create and Assign a Business Role
Previously, you deployed and activated your parcel tracking model to start tracking.
To monitor the business process data tracked by the model, you must be assigned to a specific business
role that is authorized to track models that have a namespace starting with a particular pattern.
In this step, you'll first use the Manage Business Roles (MBR) app to create a Parcel Tracking Specialist
role, which is authorized to track models with a namespace com.sap.gtt.app.tutorial*. Then you'll assign the
role to yourself in the Manage GTT Users (MGU) app.
Procedure
To create and assign a Parcel Tracking Specialist role, proceed as follows:
1. Log on to your GTT solution.
2. On the SAP Fiori Launchpad, click the Manage Business Roles app tile.
Note
The above screenshot is for reference. Depending on your user authorization, your Fiori Launchpad may contain
fewer app tiles. The Manage Business Roles app is visible to a user with the Solution Administrator role.
203. In the left-hand Business Roles pane, choose the + icon.
214. In the Add a new business role pane, specify the following and choose Save.
o Business Role: Parcel Tracking Specialist
o User By: Solution Owner
o Role Identifier: tutorial
After the role is saved, the system automatically generates the value of the field Accessible Tracked
Process Type(s) for you with the following pattern:
Accessible Tracked Process Types = com.sap.gtt.app.*
This enables users with this business role to access tracked processes with a namespace of
com.sap.gtt.app.*, with the above setting, com.sap.gtt.app.tutorial*.
Remember the namespace of your parcel tracking model is com.sap.gtt.app.tutorial.parceltracking,
so the user with this role can then access the data tracked by the parcel tracking model.
o Description: A user responsible for tracking parcel deliveries based on tutorial
model
5. If business users from invited solution participants shall as well be able to track instances of this tracked
process type, a separate business role needs to be created with “used By: Solution participants”. To do
that, just repeat steps 3 and 4 but select Solution Participants for Used By.
226. On the title bar of the window, choose the (Home) icon to go to the SAP Fiori Launchpad.
7. On the Fiori Launchpad, click the Manage GTT Users app tile.
8. In Users list, find your user. You may use the Search box to narrow down the list.
9. In the row for your user, choose the (Edit) icon.
2310. In the Edit User dialog box, under Business Role, select Parcel Tracking Specialist, and choose Save.
11. On the title bar of the window, choose the icon and sign out.
The new business role assignment takes effect the next time you logon.
Result
The Parcel Tracking Specialist role has been created and assigned to you, which means you are now able to
track models with a namespace of com.sap.gtt.app.tutorial* in the GTT app.
For more information on how to create and maintain GTT business roles, see the Administration Guide: User
Management by Solution Administrator.
244.5 Step 5: Provide the Data
Previously, you have deployed and activated your parcel tracking model to start the tracking and been
assigned with the appropriate role for tracking the model in the GTT app.
GTT checks the content of all messages it receives, such as the business information that an actual event
has occurred, and routes the messages appropriately. The first time that GTT routes a tracked process
message to an activated model, it creates a tracked process instance in the unique namespace in the tenant.
In this step, you'll provide the first data to your model so that a corresponding tracked process instance is
created. In productive usage, the data for a tracked process often is sent to GTT from other systems such as
SAP ERP. In this tutorial, you'll send the data directly to your GTT system using an external sender tool,
such as Postman. However, you can use any tool that supports the sending of HTTP requests.
Concepts
The following methods can be used to provide data from an external sender tool:
• API: Global Track and Trace Interface: Tracked Processes and Event Messages
(https://api.sap.com/package/SAPGlobalTrackTraceInterfaceTrackedProcessesandEventMessages?sec
tion=Overview)
Throughout this tutorial, we use this method to provide the data.
• Model-specific rest API: uses the rest APIs exposed by the tutor1WriteService.cds file in your model.
Procedure
1. Start the external sender tool, such as Postman.
2. For security reasons, you need to provide proper authorization for your message including a technical
user for your GTT system. For this, you may need to contact your system administrator.
Note that the email ID used by your technical user must be different to that used by your business role.
Note
For information on technical users, see the Onboarding Guide: Create a Technical User and Maintain the Technical
User for Your Company.
3. Send the following HTTP request to your GTT system.
o HTTP Method: POST
o URL: Ask your system administrator for the URL to send a request.
For example: https://[:port]//v1/process
o Request Body: The following code represents a message for your tracked process containing the
business data of a parcel delivery process specified using the attributes you defined earlier in your
basic model.
In this case, the process is for shipper “John Brown” to send receiver “Fred Smith” parcel ID
“0000001” from shipper location "No.88 XXX Avenue" to receiver location “No. 66 YYY Road” using
tracking ID "1234567890" between “11Dec2018” and “30Dec2019”. The shipping status is "01” (not
started).
Note that the value of the applicationObjectType identifies this message as being for your tracked
process instance. This must be the same as the @SAP_EM.applicationObjectType value in your
tutor1Model.cds file.
25Copy and paste the following JSON scripts but replace with the actual system ID
set up by your system administrator.
{
"applicationObjects": {
"applicationSystem": "",
"applicationObjectType": "OB_PT_00",
"applicationObjectId": "PT_NO_1",
"parameters": [{
"parameterName": "PAL_ID",
"parameterIndex": "0000000000",
"parameterValue": "0000001"
}, {
"parameterName": "SHIPPER",
"parameterIndex": "0000000000",
"parameterValue": "John Brown"
}, {
"parameterName": "SHIP_LOC",
"parameterIndex": "0000000000",
"parameterValue": "No.88 XXX Avenue"
}, {
"parameterName": "RECEIVER",
"parameterIndex": "0000000000",
"parameterValue": "Fred Smith"
}, {
"parameterName": "REC_LOC",
"parameterIndex": "0000000000",
"parameterValue": "No.66 YYY Road"
}, {
"parameterName": "SHIP_STAT",
"parameterIndex": "0000000000",
"parameterValue": "01"
}],
"trackingIds": [{
"trackingIdType": "PAR_01",
"trackingId": "0000001"
},{
"trackingIdType": "PO_NO",
"trackingId": "1234567890",
"validFrom": "2018-12-11T12:00:00+01:00",
"validTo": "2019-12-30T12:00:00+01:00",
"timeZone": "CET"
}]
}
}
Result
Based on the tracked process message you sent, the first data for your tracked process, GTT has used your
activated model to create an instance of your tracked process in your unique namespace in your tenant.
For reference, you can see and compare your JSON scripts with the supplied model_1_data.json file in
Model_1_base.
264.6 Step 6: Track Parcel Deliveries in the GTT App
Previously, you have deployed a parcel tracking model and provided data to it. The first time the model
receives the business data it is defined to track, it creates a tracked process instance. From then on, you can
find your tracked process instance in the GTT app.
In this step, you'll use the GTT app to monitor the process instance that has been tracked by your model.
Remember that you were already assigned the role, Parcel Tracking Specialist. Otherwise, you are not able
to track this model in the GTT app.
Procedure
1. Log on to your GTT solution.
2. On the SAP Fiori Launchpad, click the Track Processes and Objects tile to start the GTT app.
Note
The above screenshot is for reference. Depending on your actual user authorization, your Fiori Launchpad may
contain fewer app tiles.
273. In the Processes and Objects list, select Parcel Tracking that has the namespace
com.sap.gtt.app.tutorial.parceltracking.
4. In the upper-right corner of the Overview page, choose Go.
Optionally, you can use the Parcel ID search filter to narrow down your search and then choose Go.
28The parcel delivery that has been tracked by your model is listed on the Overview page, as shown
below:
On the filter bar, you see only one search filter: Parcel ID. This was defined by the UI.SelectionFields
statement in tutor1UI.cds.
In the list table, you see 4 fields for each parcel delivery: Parcel ID, Shipper, Receiver, and Shipping
Status. These fields were defined in the process entity in your model.
By clicking the (Settings) icon above the table, you see more fields for the process, including the
fields that were defined in the GTT core model and referenced by your parcel tracking model.
295. In the search result, select the parcel delivery process.
You are directed to the process' Object page that includes a header 0000001 only, which is the value of
the parcelId field and connected to the 'PAL_ID' SAP EM field in the tutor1Model.cds file. In the
tutor1UI.cds file, parcelId is included in the UI.HeaderInfo block, which indicates that its value should
be shown as a header in the Object page.
Your screen looks like the following:
304.7 Step 7: Add Information Blocks to the Object Page
Previously, you saw your parcel delivery process instance displayed on the Overview and Object pages in
the GTT app. The Object page only shows a header.
In this step, you'll enhance your model to show more data on the Object page, by adding two new blocks, for
a header and detailed information. The blocks are controlled in the code by what are called facets.
Procedure
1. In the MM app, choose Development ( ) in the left-hand pane and navigate to the tutor1 folder under
Workspace.
2. In the tutor1UI.cds file, add the following scripts above //Line items for lists on Overview page,
and save the file:
annotate ParcelTrackingService.ParcelTrackingProcess with @(
UI.HeaderFacets: [
{$Type: 'UI.ReferenceFacet', Target: '@UI.FieldGroup#SenderInfo'}
],
UI.FieldGroup#SenderInfo: {
Label: 'Sender',
Data: [
{Value: logicalSenderSystem},
{Value: trackingId},
{Value: trackingIdType}
]
},
UI.FieldGroup#Locations: {
Label: 'Location',
Data: [
{Value: shipperlocation},
{Value: receiverlocation}
]
},
UI.Facets: [
{
$Type: 'UI.CollectionFacet',
ID: 'BusinessProcess',
Label: 'Business Process',
Facets: [
{
$Type: 'UI.CollectionFacet',
ID: 'DetailInfo',
Label: 'Detailed Information',
Facets: [
{$Type: 'UI.ReferenceFacet', Target:
'@UI.FieldGroup#Locations'},
]
},
]
},
]
);
The above scripts define the structure of the Object page, including
o In the header facet: Sender System, Tracking ID, Tracking ID Type
o Under Detailed Information section: Shipper Location, Receiver Location
31The UI annotations are described below:
o annotate with @ defines the UI layout.
o The UI.HeaderFacets block contains field groups to be displayed in the header of the Object page.
$Type is always UI.ReferenceFacet, and Target is a reference to the field group.
o The UI.FieldGroup block defines an ordered collection of data fields with a label for the group.
o The UI.Facets block defines the structure of the Object page, and the field groups included in the
structure.
Note
For more information, see the Creating and Deploying GTT Models guide: Modeling Language Guide à GTT
Metadata Model with CDS à UI Annotations.
3. As before, in the left-hand pane, right-click the tutor1 project folder and choose Deploy à Compile GTT
Model.
To proceed, your model must contain no errors.
4. You can immediately test your updates by, again as before, right-clicking the tutor1 project folder and
choosing Deploy à Preview GTT Model.
This opens a browser window that previews the Overview page of the GTT app with mock data. The
Preview window looks like the following:
5. On the Overview page, select any of the parcel IDs.
32Result
In the Preview window, you are directed to the process' Object page that displays the process details that
you have just defined, as shown below:
In a later step, you'll deploy the model and track parcel deliveries in the GTT app with real data.
For reference, you can see and compare your model with the supplied model: Model_2_details.
334.8 Step 8: Add Parcel Items to the Object Page
Previously, you added some process information to the Object page.
In this step, you'll add a table to the Object page to list the parcel items that are delivered in the target
process.
Procedure
1. In the MM app, choose Development ( ) in the left-hand pane and navigate to the tutor1 folder under
Workspace.
2. Modify the tutor1Model.cds file as follows:
o Add the lines highlighted in red to the context ParcelTrackingModel {} block, as shown below:
context ParcelTrackingModel {
//Parcel items data
entity ParcelTrackingItem {
key parcel : Association to one ParcelTrackingProcess;
key parcelTrackingItem : String(6) @title:'Parcel Tracking Number';
productId : String(50) @title:'Product ID';
descritption : String(255) @title: 'Description';
producttype : String(50) @title: 'Product Type';
quantity : Integer @title: 'Quantity';
uom : String(20) @title: 'UoM';
sourcesystem : String(20) @title: 'Source System';
sender : String(20) @title: 'Sender';
};
This block defines the data fields to be tracked for the parcel items.
o Add the lines highlighted in red to the entity BaseParcelTrackingProcess {} block, as shown
below:
entity BaseParcelTrackingProcess {
parcelId : String(10) @title:'Parcel ID';
shipper : String(20) @title: 'Shipper';
shipperlocation : String(255) @title: 'Shipper Location';
receiver : String(20) @title: 'Receiver';
receiverlocation : String(255) @title: 'Receiver Location';
@CoreModel.KeepStatusSequence: true
shippingStatus : String(50) @title:'Shipping Status' enum {
notStarted='01' @title: 'Not Start'; //Parcel process not started
pickingCompleted='02' @title: 'Picking Completed'; //Goods picked up
received='03' @title: 'Received'; //Goods received
} default '01';
items : Composition of many ParcelTrackingItem on
items.parcel = $self;
};
This associates the parcel items entity to the process entity.
34o Add the data provisioning part for parcel items, as highlighted in red below (don't forget the comma
after shippingStatus):
//Data provision from SAP ERP or other external sender systems
@CoreModel.UsageType: #inboundMessage
@SAP_EM.applicationObjectType: 'OB_PT_00'
@SAP_EM.primaryTrackingIdType: 'PAR_00'
entity ParcelTrackingProcessInbound as projection on ParcelTrackingProcess {
@SAP_EM.fieldName : 'PAL_ID'
parcelId,
@SAP_EM.fieldName : 'SHIPPER'
shipper,
@SAP_EM.fieldName : 'SHIP_LOC'
shipperlocation,
@SAP_EM.fieldName : 'RECEIVER'
receiver,
@SAP_EM.fieldName : 'REC_LOC'
receiverlocation,
@SAP_EM.fieldName : 'SHIP_STAT'
shippingStatus,
@SAP_EM.itemizedEntity: 'ParcelTrackingItemInbound'
items : redirected to ParcelTrackingItemInbound
};
@CoreModel.UsageType: #inboundMessage
@SAP_EM.itemized: true
entity ParcelTrackingItemInbound as projection on ParcelTrackingItem {
@SAP_EM.fieldName : 'PARCEL_ITEM'
parcelTrackingItem,
@SAP_EM.fieldName : 'PROD_ID'
productId,
@SAP_EM.fieldName : 'DESC'
descritption,
@SAP_EM.fieldName : 'PROD_TYPE'
producttype,
@SAP_EM.fieldName : 'QUANTITY'
quantity,
@SAP_EM.fieldName : 'UOM'
uom,
@SAP_EM.fieldName : 'SOUR_SYS'
sourcesystem,
@SAP_EM.fieldName : 'SENDER'
sender
};
};
Note
For detailed information on how to define entities, see the Creating and Deploying GTT Models guide: Modeling
Language Guide à Language Elements à Entity Definitions.
353. In the tutor1Service.cds file, add the lines highlighted in red to the service ParcelTrackingService
block, as shown below, to expose the ParcelTrackingItem entity as a service:
entity AllTrackedProcessForParcelTrackingProcess as projection on
ParcelTrackingModel.AllTrackedProcessForParcelTrackingProcess;
//expose parcel items in service layer
entity ParcelTrackingItem as projection on
ParcelTrackingModel.ParcelTrackingItem;
Note
For more information on defining services, see the following sections in the Creating and Deploying GTT Models
guide:
• Modeling Language Guide à GTT Metadata Model with CDS à Core Model Details à Core Model
• Modeling Language Guide à GTT Metadata Model with CDS à Application Model Details à Delivery
Application Model à Delivery Application Service
4. Modify the tutor1UI.cds file as follows:
o Add the lines highlighted in red to the UI.Facets: block, as shown below:
UI.Facets: [
{
$Type: 'UI.CollectionFacet',
ID: 'BusinessProcess',
Label: 'Business Process',
Facets: [
{
$Type: 'UI.CollectionFacet',
ID: 'DetailInfo',
Label: 'Detailed Information',
Facets: [
{$Type: 'UI.ReferenceFacet', Target:
'@UI.FieldGroup#Locations'},
]
},
{
$Type: 'UI.CollectionFacet',
ID: 'ParcelItems',
Label: 'Parcel Items',
Facets: [
{$Type: 'UI.ReferenceFacet', Target:
'items/@UI.LineItem'},
]
},
]
},
]
);
This adds the parcel items table to the Detailed Information section on the Object page.
36o Add the following lines at the end of the file:
annotate ParcelTrackingService.ParcelTrackingItem with @(
Capabilities: {
Insertable:false, Updatable:false, Deletable:false,
FilterRestrictions: {
NonFilterableProperties: [
quantity,
uom,
sourcesystem,
sender
]
},
SortRestrictions: {
NonSortableProperties: [
quantity,
uom,
sourcesystem,
sender
]
},
SearchRestrictions: {
Searchable: false
}
},
) {
};
// Line Item for Parcel Items on Object page
annotate ParcelTrackingService.ParcelTrackingItem with @UI.LineItem: [
{Value: productId},
{Value: descritption},
{Value: producttype},
{Value: quantity},
{Value: uom},
{Value: sourcesystem},
{Value: sender}
];
• The Capabilities lines define the overall behavior for parcel items.
• annotate with @UI.LineItem: [] defines the appearance of the
list table on the Object page. Value is the field name that appears in the list table.
Note
For more information on UI annotations, see the Creating and Deploying GTT Models guide: Modeling Language
Guide à GTT Metadata Model with CDS à UI Annotations.
375. (This step is optional. If you don't want to use model-specific rest APIs, you can skip this step.)
In the tutor1WriteService.cds file, add the lines highlighted in red to the service
ParcelTrackingWriteService block, as shown below, to expose the ParcelTrackingItem entity as a
write service:
service ParcelTrackingWriteService @extends: TrackedProcessWriteService {
entity ParcelTrackingProcess as projection on
ParcelTrackingModel.ParcelTrackingProcessForWrite excluding {
shippingStatus
}
actions {
@Swagger.POST
action parcelTrackingProcess(@Swagger.parameter: 'requestBody'
parcelTrackingProcess: ParcelTrackingProcess) returns String;
};
entity ParcelTrackingItem as projection on ParcelTrackingModel.ParcelTrackingItem
excluding {
parcel
};
};
This exposes the parcel items entity as a write service, which allows you to use the model-specific rest
APIs.
6. Choose File à Save All.
7. In the left-hand pane, right-click the tutor1 project folder and choose Deploy à Compile GTT Model.
To proceed, your model must contain no errors.
8. As before, right-click the tutor1 project folder and choose Deploy à Preview GTT Model.
This opens a browser window that previews the Overview page of the GTT app with mock data.
9. On the Object page, select any of the parcel IDs.
38Result
In the Preview window, you are directed to the process' Object page. Your page now includes a Parcel Items
list table, as shown below:
You'll deploy the model in a later step and track parcel deliveries in the GTT app with real data.
For reference, you can see and compare your model with the supplied model: Model_3_items.
394.9 Step 9: Add Event Entities
Previously, you have enabled the display of various process information on the Object page.
In this step, you'll add event entities to your model to define the event types and data that the model will
track.
You'll define the entities for the following events:
• Picked up from shipper (planned event)
• Arrived at distribution hub (planned event)
• Delayed (unplanned event)
Concepts
• Planned Event
an incident that corresponds to a step in a tracked process that typically occurs in the future with a
foreseen date and time, and if applicable, a foreseen location.
• Unplanned Event
an incident that corresponds to a step in a tracked process that is not planned upfront.
Procedure
1. In the MM app, choose Development ( ) in the left-hand pane and navigate to the tutor1 folder under
Workspace.
2. Modify the tutor1Model.cds file as follows:
o Add the following scripts above the @CoreModel.StatusProperties : ['shippingStatus'] line:
@CoreModel.PlannedEvents: [
{eventType: PickedUpFromShipperEvent, matchLocation: false},
{eventType: ArrivedAtDistributionHubEvent, matchLocation: false},
]
@CoreModel.AdmissibleUnplannedEvents: [
{eventType: DelayedEvent}
]
These lines define the event types for planned and unplanned events, respectively.
40o Add the entities for the 3 events above the //Data provision from SAP ERP or other external
sender systems line, as shown below:
//Event for "Picked Up from Shipper"
entity BasePickedUpFromShipperEvent {
courier : String(50);
};
@UI.HeaderInfo.Title.Label: 'Picked Up From Shipper Event'
@SAP_EM.eventCode: {Code: 'PICK_UP', Text: 'Picked Up From Shipper Event', Type:
'PLANNED'}
@CoreModel.UpdateStatus: [
{pathToStatus: 'ParcelTrackingProcess.shippingStatus', newValue: '02'}
]
@CoreModel.Indexable: false
entity PickedUpFromShipperEvent: CoreModel.Event, BasePickedUpFromShipperEvent{};
entity PickedUpFromShipperEventForWrite: CoreModel.EventForWrite,
BasePickedUpFromShipperEvent{};
annotate PickedUpFromShipperEvent with {
location @CoreModel.ObjectIdentifierType: #customerLocation;
};
//Event for "Arrived at Distribution Hub"
entity BaseArrivedAtDistributionHubEvent {
courier : String(50);
};
@UI.HeaderInfo.Title.Label: 'Arrived At Distribution Hub Event'
@SAP_EM.eventCode: {Code: 'ARRI_AT', Text: 'Arrived At Distribution Hub Event',
Type: 'PLANNED'}
@CoreModel.UpdateStatus: [
{pathToStatus: 'ParcelTrackingProcess.shippingStatus', newValue: '03'}
]
@CoreModel.Indexable: false
entity ArrivedAtDistributionHubEvent: CoreModel.Event,
BaseArrivedAtDistributionHubEvent{};
entity ArrivedAtDistributionHubEventForWrite: CoreModel.EventForWrite,
BaseArrivedAtDistributionHubEvent{};
annotate ArrivedAtDistributionHubEvent with {
location @CoreModel.ObjectIdentifierType: #customerLocation;
};
//Event for "Delayed" - unplanned event
entity BaseDelayedEvent {
// empty here
};
@UI.HeaderInfo.Title.Label: 'Delayed'
@SAP_EM.eventCode: {Code: 'DELAY', Text: 'Delayed', Type: 'UNPLANNED'}
@CoreModel.Indexable: false
entity DelayedEvent: CoreModel.Event, BaseDelayedEvent{};
entity DelayedEventForWrite: CoreModel.EventForWrite, BaseDelayedEvent{};
annotate DelayedEvent with {
location @CoreModel.ObjectIdentifierType: #customerLocation;
};
• In the above scripts, the annotation
@CoreModel.UpdateStatus: [
{pathToStatus: 'ParcelTrackingProcess.shippingStatus', newValue: '02'}
]
Defines that after the tracked event is reported, the shipping status will be automatically updated
to the specified newValue '02' (Goods picked up).
Note
For detailed information on how to define entities, see the Creating and Deploying GTT Models guide: Modeling
Language Guide à Language Elements à Entity Definitions.
413. In the tutor1Service.cds file, add the lines highlighted in red inside the service
ParcelTrackingService block, as shown below, to expose the newly-added event entities as a service:
entity AllTrackedProcessForParcelTrackingProcess as projection on
ParcelTrackingModel.AllTrackedProcessForParcelTrackingProcess;
//expose parcel items in service layer
entity ParcelTrackingItem as projection on
ParcelTrackingModel.ParcelTrackingItem;
//expose events in service layer
entity PickedUpFromShipperEvent as projection on
ParcelTrackingModel.PickedUpFromShipperEvent;
entity ArrivedAtDistributionHubEvent as projection on
ParcelTrackingModel.ArrivedAtDistributionHubEvent;
entity DelayedEvent as projection on ParcelTrackingModel.DelayedEvent;
Note
For more information on defining services, see the following sections in the Creating and Deploying GTT Models
guide:
• Modeling Language Guide à GTT Metadata Model with CDS à Core Model Details à Core Model
• Modeling Language Guide à GTT Metadata Model with CDS à Application Model Details à Delivery
Application Model à Delivery Application Service
424. In the tutor1UI.cds file, add the lines highlighted in red to the UI.Facets: block, as shown below:
UI.Facets: [
{
$Type: 'UI.CollectionFacet',
ID: 'BusinessProcess',
Label: 'Business Process',
Facets: [
{
$Type: 'UI.CollectionFacet',
ID: 'DetailInfo',
Label: 'Detailed Information',
Facets: [
{$Type: 'UI.ReferenceFacet', Target:
'@UI.FieldGroup#Locations'},
]
},
{
$Type: 'UI.CollectionFacet',
ID: 'ParcelItems',
Label: 'Parcel Items',
Facets: [
{$Type: 'UI.ReferenceFacet', Target:
'items/@UI.LineItem'},
]
},
{
$Type: 'UI.CollectionFacet',
ID: 'Events',
Label: 'Event Messages',
Facets: [
{$Type: 'UI.ReferenceFacet', Target:
'processEvents/@UI.LineItem#GenericEvents'},
]
},
]
},
]
);
This adds the event messages table to the Detailed Information section on the Object page. The table
lists planned and unplanned events tracked by the target process instance.
Note
For more information on UI annotations, see the Creating and Deploying GTT Models guide: Modeling Language
Guide à GTT Metadata Model with CDS à UI Annotations.
43You can also read
