Upload
others
View
10
Download
0
Embed Size (px)
Citation preview
Developer’s Guide
Persistent Retrieval Object Builder Document Version: 2.1– 2017-04-28
PUBLIC
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP Process Object Builder 2.0 FP1)
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder
(SAP Process Object Builder 2.0 FP1)
Typographic Conventions
PUBLIC
© 2017 SAP SE. All rights reserved. 1
Typographic Conventions
Type Style Description
Example Words or characters quoted from the screen. These include field names, screen titles,
pushbuttons labels, menu names, menu paths, and menu options.
Textual cross-references to other documents.
Example Emphasized words or expressions.
EXAMPLE Technical names of system objects. These include report names, program names,
transaction codes, table names, and key concepts of a programming language when
they are surrounded by body text, for example, SELECT and INCLUDE.
Example Output on the screen. This includes file and directory names and their paths, messages,
names of variables and parameters, source text, and names of installation, upgrade and
database tools.
Example Exact user entry. These are words or characters that you enter in the system exactly as
they appear in the documentation.
<Example> Variable user entry. Angle brackets indicate that you replace these words and
characters with appropriate entries to make entries in the system.
EXAMPLE Keys on the keyboard, for example, F2 or ENTER .
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Document History
PUBLIC
© 2017 SAP SE. All rights reserved. 2
Document History
Version Date Change
1.0 2016-03-21 Based on SAP Process Object Builder 1.0 SP5
First Public Version
2.0 2016-11-11 Based on SAP Process Object Builder 2.0 SP0
2.1 2017-04-28 Based on SAP Process Object Builder 2.0 FP1
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Table of Contents
PUBLIC
© 2017 SAP SE. All rights reserved. 3
Table of Contents
1 Preface ................................................................................................................................. 5 1.1 Target Audience ............................................................................................................................... 5 1.2 Prerequisites .................................................................................................................................... 5 1.3 References........................................................................................................................................ 7 1.4 Disclaimer ......................................................................................................................................... 7
2 Introduction .......................................................................................................................... 8 2.1 Context ............................................................................................................................................. 8 2.2 Structure of this Guide ................................................................................................................... 11 2.3 System Prerequisites for PROB and PROT ..................................................................................12
2.3.1 General Prerequisites ....................................................................................................12 2.3.2 Prerequisites for Back-End Services ............................................................................12
2.4 Deployment Options and PROT Shipment ...................................................................................13 2.5 Sample Use Case: Flight Search....................................................................................................13 2.6 How to Read this Document? ....................................................................................................... 14 2.7 Modeling Conventions and Generated Artifact Names ...............................................................15
3 PROT Definition ................................................................................................................... 17 3.1 Model-Driven Software Development (MDSD) ............................................................................ 17 3.2 Versioning of a PROT ..................................................................................................................... 18 3.3 Identification of a PROT ................................................................................................................ 18
3.3.1 Use Case Definition ....................................................................................................... 18 3.3.2 Investigation of Back-End Business Objects and Services ....................................... 19
3.4 Modeling a PROT ........................................................................................................................... 19 3.4.1 PROT Modeling using SAP SOA Modeling Methodology ........................................... 19 3.4.2 PROT Object Model ....................................................................................................... 22 3.4.3 ‘Beautified View’ Concept............................................................................................. 23 3.4.4 PROT Object Model Template ...................................................................................... 24 3.4.5 Predefined Nodes .......................................................................................................... 28 3.4.6 PROT Object Model in ESR ........................................................................................... 30 3.4.7 Separation of Modeling and Productive Entities .........................................................31
4 PROT Programming Model ................................................................................................. 33 4.1 Basic Principles .............................................................................................................................. 33
4.1.1 Separation of Concerns: Process vs. Business Logic ................................................ 33 4.1.2 Pattern for Processing Flow ......................................................................................... 33
4.2 Phase Model ................................................................................................................................... 34 4.3 Status Model .................................................................................................................................. 34 4.4 Status Transitions.......................................................................................................................... 36 4.5 Phase Implementation .................................................................................................................. 37
4.5.1 Fetch Phase ................................................................................................................... 37 4.5.2 Complete Phase ............................................................................................................ 38 4.5.3 Node Dependencies ...................................................................................................... 39
5 PROT High-Level Design ..................................................................................................... 41 5.1 Block Diagram ................................................................................................................................ 41
5.1.1 ESR Content................................................................................................................... 42
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Table of Contents
PUBLIC
© 2017 SAP SE. All rights reserved. 4
5.1.2 ABAP Artifacts ............................................................................................................... 43 5.1.3 Back-End Services ........................................................................................................ 43
5.2 Package Structure ......................................................................................................................... 43 5.2.1 PROT Core ..................................................................................................................... 44 5.2.2 Package Encapsulation ................................................................................................. 46
5.3 PROT Design & Specification Checklist ....................................................................................... 46
6 PROT Detailed Design ......................................................................................................... 53 6.1 Layer Concept ................................................................................................................................ 54 6.2 Application Logic Layer ................................................................................................................. 55
6.2.1 Database Tables ............................................................................................................ 56 6.2.2 API Design ...................................................................................................................... 58 6.2.3 Phase Handling .............................................................................................................. 65
6.3 Communication Layers .................................................................................................................. 71 6.3.1 Inbound Communication .............................................................................................. 72 6.3.2 Outbound Communication ........................................................................................... 77 6.3.3 Find Service ................................................................................................................... 80
6.4 General Concepts .......................................................................................................................... 82 6.4.1 Transaction Control ...................................................................................................... 82 6.4.2 Exceptions and Message Classes ................................................................................ 83 6.4.3 Instance Management .................................................................................................. 84 6.4.4 Status Handling ............................................................................................................. 84 6.4.5 Expiration ....................................................................................................................... 88 6.4.6 Event Handling ............................................................................................................... 94 6.4.7 Predecessor Relations .................................................................................................. 98 6.4.8 CNS, OAF, and Information Messages ........................................................................ 98 6.4.9 Deletion ........................................................................................................................ 100
7 PROT Implementation ...................................................................................................... 102 7.1 Custom Phase Implementation .................................................................................................. 102
7.1.1 Conventions and Disclaimers ..................................................................................... 102 7.1.2 Goals of Phase Implementation ................................................................................. 103 7.1.3 Basic Principles of Phase Implementation................................................................ 104 7.1.4 Helpers for Phase Implementation ............................................................................ 108 7.1.5 Fetch Phase – Custom Implementation .................................................................... 116 7.1.6 Complete Phase – Custom Implementation ............................................................ 123
7.2 Expiration of Node Instances ...................................................................................................... 126 7.2.1 Expiration Based on Back-End Information .............................................................. 126 7.2.2 Expiration Based on Time-Dependent Rules ............................................................ 128
7.3 Parallel Processing ...................................................................................................................... 129 7.4 Implementing Additional Authorization Checks ....................................................................... 130 7.5 Internal Types ............................................................................................................................... 131
Terms and Abbreviations ............................................................................................................. 133
Table of Figures ............................................................................................................................ 134
Table of Tables ............................................................................................................................. 136
Table of Listings ............................................................................................................................137
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Preface
PUBLIC
© 2017 SAP SE. All rights reserved. 5
1 Preface
This document is intended for developers who want to create persistent retrieval object types (PROTs) using
the persistent retrieval object builder (PROB) that is part of SAP Process Object Builder (POB). These
developers are called PROT developers. The guide aims to describe the capabilities of PROB and all the aspects
that should be considered in order to successfully design and develop PROTs. It also provides recommendations
and how-tos for leveraging the various features of PROB.
1.1 Target Audience
We assume that the following software development roles are involved in a PROT implementation project:
Developers:
Especially in the area of service implementation and PROT implementation
Development Architects:
Especially architects responsible for designing the PROT cut and also for related software logistics like
software component cut, package structure, namespace definitions etc.
Integration Experts / Integration Architects:
Responsible for enterprise service governance and all other aspects related to cross-component
integration
Implementation Consultants:
With primary experience of ABAP / PI implementations, responsible for PROT implementation in partner
and customer implementation projects
As the development of PROTs involves many aspects related to SAP enterprise services (web services with
semantics and governance of SAP), process integration, and orchestration, it is expected and desirable that the
roles mentioned above also have a general experience in the areas of process integration (SAP PI). PROTs are
often developed in the context and in combination with process object types (POTs). Therefore it is expected
that the roles mentioned above also have a general experience in the areas of POT development, architecture
and design.
The following section provides a detailed list of knowledge prerequisites.
1.2 Prerequisites
The target audience described in the previous section should have knowledge in the development-related
topics listed in the table below. The table is sorted according to whether knowledge about a given topic is
classified as "Mandatory", "Highly Recommended" or "Recommended". As you may see there are no further
exceptional knowledge required besides the ones recommended in an integration project.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Preface
PUBLIC
© 2017 SAP SE. All rights reserved. 6
Topic Know-how
Requirement
Comment
ABAP Objects Mandatory The ABAP artifacts generated for a PROT are primarily in
ABAP Objects. Know-how on the topic is required to gain a
basic understanding of how the generated coding handles
specific requirements.
SAP Process Object
Builder Product
Documentation
Mandatory The software component SAP Process Object Builder
combines both builders, the POB as well as the PROB. The
Installation Guide, Administrator’s Guide, and the
application help for SAP POB provide detailed information
about system prerequisites and the tools that are also used
for the PROB. Information about PROT modeling concepts
and the PROB wizards for creating a PROT is included.
SAP Enhancement
Concept (BAdIs)
Mandatory PROB generates BAdIs for custom enhancements, if
specified to do so.
SAP XI / PI Design time (PI
Integration Builder)
Mandatory PROB uses the Enterprise Services Repository (ESR, also
known as Integration Builder in SAP NetWeaver™ PI/XI) as
the modeling environment at design time. Some steps in
the PROT generation with PROB involve manual tasks in
ESR, like copying data types and activating the resulting
change lists and so on. PROB also generates all remote
interfaces of a PROT into ESR.
SAP XI / PI Configuration
time (PI Integration
Directory and SOA
Manager)
Mandatory At configuration time, the consumer proxies for the service
interfaces of a PROT must be configured against the
corresponding back-end provider services. To do so,
either a SOA Manager-based configuration or an XI/PI
configuration (also known as Integration Directory) can be
used.
Testing Environment for
SOA services (SPROXY,
WS Navigator, etc.)
Mandatory Enterprise services have a separate test environment. In
addition to SAP tools, some external tools (for example
SoapUI) might also be used. Basic working knowledge with
the chosen test tool is required.
Services Test Automation Highly
recommended
Automated service tests facilitate faster testing processes
and also a more comprehensive bug identification.
Object-Oriented Design
Patterns
Highly
recommended
Some of the generated ABAP classes and interfaces also
rely on and follow well-known design patterns like
Singleton, Façade and Adapter.
SAP SOA Modeling
Methodology
Highly
recommended
Modeling and implementation of a PROT follows the SAP
SOA Modeling Methodology, especially business object
modeling, service operation design and global data types
design.
Tools related to service
implementation
infrastructure at SAP
(SIW, CNS, OAF)
Highly
recommended
The generated artifacts of a PROT contain a built-in
integration to most of these tools. Working knowledge of
the tools would be helpful for testing / debugging a PROT.
SAP PI – Event Interfaces Recommended PROB generates service interfaces as event interfaces.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Preface
PUBLIC
© 2017 SAP SE. All rights reserved. 7
1.3 References
Product Documentation for SAP Process Object Builder
1.4 Disclaimer
The processes described in this guide are used as examples and merely serve to illustrate specific aspects of
persistent retrieval objects purely from a learning perspective. No claims are made as to the business validity
of these sample business processes. SAP assumes no responsibility for errors or omissions in this document.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Introduction
PUBLIC
© 2017 SAP SE. All rights reserved. 8
2 Introduction
SAP Persistent Retrieval Object Builder (PROB) is a tool that enables rapid development of software artifacts
that are needed for an effective consumption of enterprise services to provide query results in the most efficient
manner. To do so, you need to be familiar with the PROB as a development tool. However, it is also important to
understand the motivation for developing a new PROT before using the tool itself. PROTs belong to a different
logical architecture layer than the back-end applications. Therefore, PROTs must also address some of the
specific challenges that are typical of this layer. You need to be aware of these challenges in order to better
understand and leverage the features that PROB offers to address them. Therefore, this chapter briefly
discusses the background and the need for PROTs in general and the motivation for using PROB to develop a
PROT.
2.1 Context
Typically, real-world IT landscapes can broadly be classified into two major architectural layers: channel
applications and back-end applications (also known as platform applications). In many cases, there is a clear
separation between these two architectural layers, mainly driven by the fact that the architecture of the channel
applications layer often requires more agility and different innovation cycles. (The typical technology
turnaround time is approximately 2-3 years). A classic example of this was the introduction of online banking
(that is, using the web) in the mid-1990s. This did not require many new functions or products in the back-end
applications area, but existing functions had to be provided with new, unexplored channels, which bore new
challenges and performance issues.
A more recent example is mobile banking.
Figure 2-1: Typical IT Landscapes and Integration Challenges
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Introduction
PUBLIC
© 2017 SAP SE. All rights reserved. 9
From Figure 2-1 it can be seen that for any enterprise, there are two major approaches to differentiate from
competition: Adding new business functions to the business objects of the back-end platform and providing a
user-friendly, rich yet easy-to-use and responsive interface for customers, partners and employees.
Residing in between these two architectural layers is the third architecture layer (called integration layer), which
contains a multiplicity of components from different vendors built with different technologies that need to be
interfaced. The main task of these components is to address challenges in the following topic areas:
Technical Integration: First of all, there are multiple instances involved, which results in a network. Web services
have become a commonly accepted standard for communication over a network. Over the years, the means of
integration have changed from EAI (Enterprise Application Integration) to SOA principles. Today, there is no big
customer that does not need an integration infrastructure - based on web services technology.
Semantic Integration: Web services include a contract. A clarification of meanings is required to understand
the content of the contract. The semantics of applications (that is, the meaning of data) must be understood
correctly. (For example, an account number in a platform component might mean far more than just a number
for the account).
Mediation: Channel-specific requirements and back-end offerings usually do not fit together. It is not realistic
to expect that the platform can offer interfaces that completely match the channel-specific requirements. The
topics to be addressed in this area could be, for example, the orchestration of back-end services, mapping
between channel-specific views and back-end objects, buffering, state handling, event processing and so on.
Performance: response times become key in a distributed landscape where data have to be collected from
multiple components and provided to remote channels. If users have to wait seconds, sometimes minutes to
see the result of their request it becomes obvious that decoupling of data retrieval from the data provisioning is
needed. Persistent Retrieval Objects allow to already access partial results while still collecting information. This
allows to build user interfaces which inform the user with preliminary results before data collection is complete
or to collect data in background before the user navigates to the screen which requires such data.
In short, the components in the integration layer are intended to:
Simplify back-end interfaces by reduction/aggregation (also known as compound services)
Address generic cross-cutting concerns like faster response times by providing cached data, or providing
intermediate results while still collecting data
Provide faster development times for more agility on the channel applications architecture layer
This is valid enough motivation for a (semi-) automated application development tool like PROB.
Figure 2-2: Motivation for Process Object Types and Persistent Retrieval Object Types
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Introduction
PUBLIC
© 2017 SAP SE. All rights reserved. 10
In addition, even though the integration layer is primarily intended to ensure the separation of channel
applications from back-end applications, there is no clear standard or guideline available as to how process
knowledge and business functionality should ideally be distributed across the three architecture layers. Each
software application vendor in the market provides different offerings in that respect.
SAP offers the following features with regard to the three architectural layers:
A stable SOA-based application platform (in the back-end applications architecture layer) with fine-
granular business objects and corresponding enterprise services for homogenous provisioning and
consumption of the business functionality
SAP Persistent Retrieval Object Builder to build persistent retrieval object types (PROTs) using a tool-
based rapid application development (RAD) approach to close the gap for defining compound query
services and to address some of the integration and performance challenges described above.
SAP's strategy is to simplify the consumption of its back-end application layer components (application
platform). This completes the context for the positioning of PROTs that can be rapidly developed using PROB.
Using persistent retrieval objects has advantages in many areas:
Access to Data Using Standardized Interfaces
In business processes or for user interfaces it is often necessary to read and merge data from different
sources (business objects/services) without reducing performance, and to then further process this data.
Persistent retrieval objects enable data to be read and persisted from one or more back-end systems by
means of services. The result can then be provided to the user by means of services.
Parallel Data Retrieval
To ensure system performance, data retrieval runs in two phases:
In the Fetch phase, the individual node instances are determined. This is done by calling search services of
the back end, for example. The Fetch phase can be run in parallel for the individual node types. If
dependencies are modeled between node types, the dependent node types are processed after their
predecessors.
In the Complete phase, the data for each node instance can be completed. This can be done by calling read
services for the objects found in the Fetch phase, for example. The Complete phase can be run in parallel
for the node instances. If dependencies are modeled between node types, the instances of the predecessor
types are processed first and the instances of the successor types are processed in parallel afterwards.
Persistence and Data Versioning
All data that is read using back-end services and transferred to the persistent retrieval object instance is
persisted. This means that this data can be accessed at all times without requiring a renewed call of the
back-end services.
If the data for an instance is outdated, events are sent. Users of the instance can then react to this by
triggering an update of the data by means of the corresponding operations. With each change to the data
of an instance, a version of the old data is saved.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Introduction
PUBLIC
© 2017 SAP SE. All rights reserved. 11
The various features and options offered by PROB for generating PROTs, which are described in the rest of the
document, are best understood with this overall context in mind.
2.2 Structure of this Guide
The sequence in which the topics are described in this document follows the life cycle phases of a PROT. As the
document progresses into the later phases of the PROT life cycle, several topics are described in detail and refer
to other parts of the document.
The development life cycle of a PROT involves several high-level phases like modeling, wizard-based generation,
implementation of code slots as well as testing and refactoring: For a better orientation, the main chapters of
this guide are tagged with the corresponding phase of this life cycle perspective.
The following figure shows the phases as referred to in this guide:
Figure 2-3: PROT Development Life Cycle
Model – identification and modeling of the PROT in accordance with SAP SOA modeling methodology
Motivation for Persistent Retrieval Object Types
Persistent Retrieval Object Types (PROTs) address the gap for:
Compounding fine-granular services of back ends to a service required for agile development of UI
applications
An implementation that addresses typical integration layer challenges required for a successful
realization of cross-component queries.
Persistent Retrieval Object Builder (PROB) is the tool that enables the rapid development of PROTs.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Introduction
PUBLIC
© 2017 SAP SE. All rights reserved. 12
Build – building the PROT in a step-by-step approach, guided by the PROB wizards
Develop – developing the code slots that are provided in the generated PROT artifacts to complete the
implementation of the PROT
Test – testing the PROT
Testing a PROT could result in reworking a PROT in one or more phases in order to refine the functionality of
the PROT.
2.3 System Prerequisites for PROB and PROT
The prerequisites described in all the sections below apply to all versions of Persistent Retrieval Object Builder
2.0 (as part of SAP Process Object Builder 2.0).
2.3.1 General Prerequisites
A PROT primarily contains ABAP artifacts and runs in the ABAP server. The minimum required SAP NetWeaver™
release is SAP NetWeaver™ ABAP 7.50 (minimum SP-Level for NetWeaver™ 7.50 is SP04).
The Business Suite Foundation Layer (SWC BS_FND) is required for PROB itself as well as for running a PROT.
In the Service Implementation Workbench (SIW) component, a dedicated landscape for PROB must be specified
(see the "Tools Used" section in the POB Application Help). SIW is part of the SAP NetWeaverTM Platform.
A PROT can run independently of any other application platform component (in particular SWC FSAPPL).
A PROT is completely independent from PROB and does NOT require the PROB at runtime.
ESR Requirements:
PROB requires an ESR that contains active storage locations for services artifacts (SWCVs, namespaces,
folders). More information on the required releases can be found in the POB Installation and Upgrade
Information.
The PROT SWCV (Software Component Version) must not be locked.
Services of the back-end application SWCVs must also be present in ESR. On the corresponding ABAP back-
end system for a PROT, a connection to ESR must be set up and a matching landscape definition must exist in
SIW customizing.
Tools Used:
The following list names all the other tools that are required by a PROT.
Extensible Objects Framework (Package: XO_FRAMEWORK)
Outbound Agent Framework (Package: FS_OAF)
Change Notification Service (Package: FS_CNS)
Services Library (Package: FS_SERVICE_LIBRARY)
For more information on the tools and how they are used with a PROT see the "Tools Used" section of the POB
application help.
2.3.2 Prerequisites for Back-End Services
Generally, any interface accessible via ABAP can be used to access back-end components.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Introduction
PUBLIC
© 2017 SAP SE. All rights reserved. 13
PROB provides easy consumption of service operations that are defined in ESR.
Note that for custom data type enhancements done in ESR, the SPROXY structures must be generated
manually (outside PROB).
2.4 Deployment Options and PROT Shipment
As already mentioned in section 2.3, PROB generates artifacts of a PROT and these artifacts are completely
independent of PROB itself. Therefore, from a deployment perspective, a PROT can run completely independent
of PROB in a separate instance. The same applies for software shipment. The following artifacts are part of a
PROT at runtime:
ABAP content
ESR content
Therefore, SAP does not ship any productive PROTs along with the PROB itself.
2.5 Sample Use Case: Flight Search
To help you to better understand each individual aspect/concept of modeling, building and developing a PROT
implementation, this document follows one sample use case throughout.
The sample use case is called “Flight Search”. Throughout this guide, the phrase ‘sample use case’ always refers
to this flight search use case. The explanations and figures that relate to this process cover all the
aspects/concepts and artifacts that are explained in the guide. They always follow the more abstract
explanation of the corresponding aspect/concept or artifact.
Please note that the use case is only intended to explain the concepts described in this guide and therefore is in
no way complete.
The following section gives a brief explanation and overview of the use case. The details on how to implement
this use case using a PROT (from modeling to testing) are progressively illustrated in the subsequent chapters
of this guide.
Use Case Overview
A company employee needs to go on a business trip. To do so, the employee needs to book a flight and a
shuttle transfer.
The objective of the sample use case is to provide the employee with a list of flights (from airport, to airport,
flight time), the seat availability per flight time, and based on the selected flight time the shuttle availability.
PROT Shipment
There are no persistent retrieval object types (PROTs) included in the shipment of the Persistent Retrieval
Object Builder (PROB).
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Introduction
PUBLIC
© 2017 SAP SE. All rights reserved. 14
This simplified use case is shown in Figure 2-4:
Figure 2-4: Flight Search
For the sake of simplicity, reservations for hotels, rental cars and so on, are not part of this use case.
An instance of the sample use case could be as follows:
An employee residing near Frankfurt (Germany) needs to go on a business trip to Manhattan, New York (U.S.):
1. The employee gets a list of all available flights from Frankfurt airport (home airport) to JFK Airport, New
York (destination airport).
2. The employee selects a suitable flight from Frankfurt to New York.
3. The employee checks the availability of a shuttle based on the selected flight.
2.6 How to Read this Document?
Part I – High-Level Architecture & Design Concepts
For architects and integration architects/experts:
Modeling
High-level architecture
Deployment and shipment
High-level design considerations and their implications like SWCV cut
Separation of modeling and production
Namespaces
Package concept
Global Data Types (GDTs)
Detailed modeling aspects for PROT cut (nodes, details, private details)
Part II – Detailed Design & Implementation
For architects and developers:
Specification steps and their implications
Generation of services and consumed back-end services (roughly covering specification and generation
wizard, but NOT just step by step explanation)
Details of generated artifacts (tables, classes, helpers) and detailed information on code-slot
implementation.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Introduction
PUBLIC
© 2017 SAP SE. All rights reserved. 15
2.7 Modeling Conventions and Generated Artifact Names
This guide uses diagrams in accordance with several standard modeling techniques in order to explain the
various architecture and design concepts.
The following modeling conventions are used in the guide:
SAP SOA Modeling Methodology
Used for models in the SOA context
UML2.0
Pre-dominantly used as the methodology for detailed artifact modeling.
TAM
SAP Block Diagrams are sometimes used to explain high-level concepts (broadly corresponds to a Composite
Structure Diagram in UML)
<<Interface>> indicates that Interface is a stereotype of an artifact.
<IF_NAME> indicates that IF_NAME is a placeholder for the name of an artifact.
<MLB> is the generic placeholder for the abbreviated name of a PROT.
During generation of a PROT, <MLB> is derived with the following concatenation rule:
[/$ABAPNameSpace$/] + [$ABAPArtifactPrefix$] + [$ABAPAbbrev$]
$ABAPNameSpace$ = ABAP Namespace
$ABAPArtifactPrefix$ = Standardized prefix for ABAP artifacts wherever applicable (for
example, CL_ for ABAP class; no prefix for DDIC type and so on)
$ABAPAbbrev$ = Concatenation of the ABAP Abbreviation (Specification Wizard Step Define ABAP
Environment), the PROT ABAP short name (Specification Wizard Step Enter ABAP Short Names)
separated by underscore, and the PROT version.
For the sample scenario of this developer guide, this means:
$ABAPNameSpace$ = /PL9/
$ABAPAbbrev$ = GXX_FB01
Therefore:
<MLB> = /PL9/GXX_FB01 for DDIC type name
<MLB>CL = /PL9/CL_GXX_FB01 for ABAP class names and so on
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Introduction
PUBLIC
© 2017 SAP SE. All rights reserved. 16
Part I – High-level Architecture & Design Concepts
Before a PROT can be generated
using PROB, there are several
aspects that need to be addressed
and decided by development
architects to complete the high-level
architecture of the PROT. Such
decisions are often considered as
simple input parameters on the
PROB wizard screens. However,
these parameters must be
considered carefully with complete
understanding of their implications.
This part of the developer's guide
briefly describes the context and the
activities that must typically be
performed to identify and cut a
persistent retrieval object. It also
discusses in detail the options for
and the impact of several high-level
architecture-relevant parameters
that are specified as settings for the
PROT in the Builder.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 17
3 PROT Definition
SAP Persistent Retrieval Object Builder extensively incorporates a Model-Driven Software Development
(MDSD) approach. We therefore strongly recommend that you follow a robust modeling-based approach to
define a PROT before starting with the PROB and generating the PROT artifacts using the PROB wizards.
Detailed modeling and a constant review of the models avoids frequent re-work on the actual PROT.
3.1 Model-Driven Software Development (MDSD)
In the PROB context, the MDSD approach means that the model of a PROT is at the heart of the whole software
development life cycle:
First of all, the model is based on a well-defined metamodel that is defined by PROB. It does not only offer
wizards to construct the model of a PROT, but also uses this model to generate the corresponding software
artifacts. It maintains all the metadata related to a PROT in exact conformance to the PROT model. The
generated software artifacts also comply with a standard architecture and programming model.
Any changes to the model result in regeneration and/or deletion of the PROT software artifacts, according to
the changed metadata and processing instructions. The regeneration steps are robustly built so as not to touch
any non-PROT-specific artifacts and custom coding in the code slots that are generated for this purpose. The
generation and regeneration also takes care of special artifacts like database structures.
PROB also supports PROT versioning in order to manage changes across different releases of a PROT.
Figure 3-1: Model-Driven Software Development in the Context of PROB/PROT
“You can use an eraser on the drafting table or a sledge hammer on the construction site.”
- Frank Lloyd Wright
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 18
3.2 Versioning of a PROT
As already mentioned in the previous section, PROB maintains all the metadata related to a PROT. This
metadata is called the PROT configuration. The version concept defines two types of versions: The metadata
version and the configuration version:
Metadata Version
This version reflects the support package (SP) level of the PROB that has been used to create the PROT
configuration. The metadata version is required to support the migration of PROT configurations that have been
created with a lower PROB SP to a higher PROB SP.
Configuration Version
Each PROT configuration is assigned a configuration version, starting with version number 01. This enables you
to create multiple versions of the same PROT configuration. The version number is included in most of the
generated artifact names.
This versioning of PROT configurations is useful in cases where an existing PROT evolves over the time and
requires new features: Instead of changing and re-generating the existing PROT to reflect the new features, a
new configuration version can be drawn. This leads to a completely new set of artifacts, which are generated
based on the next higher version number. The existing PROT remains unchanged
Instead of drawing a new version for a PROT configuration, you can also copy an existing configuration. This
leads to a new PROT configuration, again starting with version number 01. In this case, the existing PROT also
remains unchanged.
3.3 Identification of a PROT
The detailed process of identifying a PROT can vary from one software development project to the other and is
therefore not part of this document. However, the sections give you an overview of the activities that should
always be part of the PROT definition process.
3.3.1 Use Case Definition
A valid use case driven by an outside-in approach must clearly identify the requirements for a PROT in the given
business context (see section 2.1 above). This means it must require functionality to buffer data and to provide
intermediate results before all data have been collected. The requirement definition has also to specify how
buffered data (or parts thereof) are expired.
Use Case Definition: Flight Search
The definition for the sample use case (see section 2.5 above) contains the following requirements:
Model Driven Software Development (MDSD) of a PROT
A PROT model is much more than just a documentation of software. It is, in fact, the central artifact that
drives the entire software development life cycle of the PROT.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 19
Basic information related to travel dates must be sufficient to trigger the query
The query should be accelerated by the system as far as possible and it should provide already
intermediate search results, before the search is fully completed
Search results should be buffered for other queries with the same selection criteria, buffered results have
to be invalidated if flight or shuttle availability changes
Shuttle bookings have to be selected in relation to the corresponding flight selected.
These requirements meet the demands for a persistent retrieval object in the following aspects:
The process steps require smaller beautified views of the actual back-end business objects involved (flight,
and shuttle) that suite the use case.
There is a requirement for intermediate access to data.
There is a sequence of steps that should execute services of different application components in a
consistent manner: The flight search will most differ from the shuttle search. However, the times for which
shuttles are provided must be consistent with the times of the corresponding flights.
Finally, there are requirements for expiration of buffered data.
The sample use case therefore qualifies for the introduction of a PROT to implement it.
3.3.2 Investigation of Back-End Business Objects and Services
The next activity for identifying a PROT is to identify all the fine-granular back-end services that the query use
case requires and to test these services for all required variants (input combinations). The general prerequisites
for building a PROT must also be tested. Any gap identified with respect to back-end services must be addressed
in the back end (for example, by creating new services or new service versions that meet the requirements of
the identified PROT) before proceeding with the PROT definition. The feasibility of compounding fine-granular
services for a specific use case can also be tested during this activity using well-prepared test suites in a web
services testing tool (like SoapUI).
3.4 Modeling a PROT
Once the requirements and prerequisites have been clarified, the PROT itself should be modeled at high level by
defining the process component to which it belongs, the deployment unit and software component etc. Then
the PROT object model should be modeled in detail with the persistent retrieval object root node and all the
persistent retrieval object nodes.
The overall methodology that is recommended for PROT modeling is SAP SOA Modeling Methodology (see
section 1.2, SAP SOA Modeling Methodology). All methodology and meta-model entities referred to in the
following sections use the terminology and methodology described in this document.
3.4.1 PROT Modeling using SAP SOA Modeling Methodology
SAP SOA modeling methodology follows a harmonized enterprise model approach that reduces redundancies
of SOA services by assigning services to a business object. The business object itself is assigned to exactly one
process component and process components are grouped into deployment units. A deployment unit is a
separately deployable entity in a shippable software component.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 20
Figure 3-2 below shows a meta-model for the SAP SOA modeling methodology:
Figure 3-2: SAP SOA Modeling Methodology Metamodel
PROB requires the process component that the PROT is assigned to as an input parameter at design time. The
process component must be unique for each PROT. This means that there is a 1:1 relationship between a PROT
and the metamodel entity process component in SAP SOA Modeling Methodology. Although theoretically, the
methodology allows for multiple business objects (in this case PROTs) to be present in a single process
component, a design decision has been made for PROB to limit this to a 1:1 relationship. (An exception is made
for the different PROT versions, which means that different versions of a PROT can still be in one process
component). The restriction is due to the fact that a process component in business suite applications is only a
metamodel entity and has no corresponding shippable entity in ESR. As the PROB metamodel heavily relies on
ESR entities, it is easier to handle generated artifacts that relate to concrete ESR entities. It is also an SAP
convention to use a short form of the process component name as an ABAP abbreviation for the artifacts
generated later by PROB. During PROT generation, this abbreviation is then used to derive the names of all the
generated ABAP artifacts. Changing the name of the process component (and, consequently, the ABAP
abbreviation) requires a regeneration of the PROT. This could become cumbersome as the regeneration might
lead to syntax errors in code slots that refer to older names of ABAP artifacts, which will require manual
corrections.
A deployment unit is another metamodel entity in SAP SOA Modeling Methodology that primarily does not
affect anything that PROB does at design time (during PROT generation). However, assigning process
components (and also PROTs, due to the 1:1 relationship) to a deployment unit is something that development
and integration architects need to consider right at the beginning of the PROT definition process.
The farthest boundary of a deployment unit is a software component (SWC) that belongs to a unit of shipment.
Therefore, common factors such as shipment cycles, landscape optimization and deployment options that
influence the cut of software component versions (SWCVs) must be considered when determining the right
SWC for a PROT (and, consequently, the appropriate modeling entities).
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 21
Figure 3-3 shows an overview of the various SAP SOA entities for the sample use case:
Figure 3-3: Business Object Map for Sample Use Case (SAP SOA Modeling Methodology)
(Remark: Flight Reservation and Shuttle Reservation are not relevant but are shown due to the fact that they
reside in the same process components as Flight resp. Shuttle.)
Other models that integration architects should define include the integration scenario model and the process
component interaction models. These models are necessary to provide a complete understanding of the
enterprise services that must be provided and used for the PROT.
Once process component and deployment unit have been defined and a decision on the SWC cut has been
made, PROB only requires the SWC to be assigned to an appropriate application component in SAP Application
Component Hierarchy. The SWCV must also be suitably reflected in ESR (via SLD) and an ESR Namespace must
be chosen and available in ESR.
The choice of the ESR namespace is also significant for PROT development. There are different conventions for
defining the ESR namespace. One such convention could be, for example, to choose a namespace that has a 1:1
relationship to the deployment unit of the PROT. Following this convention, the ESR namespace for the flight
search use case, could be as follows:
http://test.sap.com/xi/BusinessTripManagement
This is a generic way of naming the ESR namespace, because in the future there could be other POTs and PROTs
in the same SWC (in our example, this could include flight booking, rental car booking, hotel search, hotel
booking, and so on) that can share this ESR namespace. Choosing a single ESR namespace for multiple POTs
and PROTs of the same SWC will enable you to reuse back-end proxy objects like GDTs, which are generated
only once per ESR namespace in an ABAP back end. However, choosing one ESR namespace also means that
all the ESR objects of multiple PROTs exist in the same ESR namespace. In this case, you have to use the same
prefixes for SPROXY artifacts and the common internal types, while the ESR objects of several POTs and PROTs
can be separated logically by using ESR folders.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 22
Caution
If you use the same ESR namespace for multiple POTs/PROTs, make sure to use the same SPROXY
prefix and the same prefix for common internal types for all of them.
Another way of cutting ESR namespaces could be to have specific names that follow the scope of a PROT, such
as:
http://test.sap.com/xi/FlightSearchProcessing
http://test.sap.com/xi/HotelSearchProcessing
http://test.sap.com/xi/FlightBookingProcessing
This way of cutting ESR namespaces would explicitly rule out any reuse of common SPROXY artifacts. However,
it also means that only ESR objects related to one POT or PROT exist in one specific ESR namespace.
Based on these aspects, an informed decision must be made on whether to create multiple ESR namespaces in
one SWC for different PROTs as this decision, for all practical purposes, leads to a one-way path for all
subsequent development of PROTs within that SWC.
3.4.2 PROT Object Model
The next activity in modeling a PROT is the modeling of the PROT object model itself, which means that the
PROT is modeled in detail together with its node structure. This also includes node cardinalities. This model of
a PROT is later on entered in PROB and completed in ESR (to enable PROB to work with the model). However,
as ESR is not a tool intended for object modeling, we strongly recommend to model a PROT upfront in another
modeling tool with a suitable metamodel/method definition (SAP Sybase Power Designer, MS Visio, ARIS or
others) to be able to review and finalize the model before you start modeling in PROB.
Figure 3-4 shows the metamodel for a PROT model:
Figure 3-4: Metamodel of a PROT
A PROT consists of a root node with the same name as the PROT itself. This root node is also generally referred
to as the PRO (persistent retrieval object).
Architectural Decisions
Decisions on the process component, software component and the ESR namespace of a PROT have long-
lasting consequences. It is not recommended to change them again during the PROT development
process.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 23
Under the root node, the PROT contains one or more subnodes in a composition relationship. Each subnode is
also referred to as PRONT (persistent retrieval object node type).
Following this metamodel, Figure 3-5 shows the PROT object model for the sample process:
Figure 3-5: Preliminary Object Model for Sample PROT FlightSearch
3.4.3 ‘Beautified View’ Concept
One objective of a PROT is to compound fine-granular services of the back-end applications into coarse-granular
services that are cut according to the use case and the UIs that consume these services. It is therefore very
important to consider the structural details of the PRO and its nodes. Typically, the structures of the services
that a back-end business object exposes are use-case-agnostic. As a consequence, these structures can
become quite large as they must meet the requirements of several use cases and also expose the full functional
capabilities of the business object. On the other hand, a use case that a specific PROT is designed for has specific
requirements that relate to certain parts of the whole functionality of the business object. Therefore, a PROT
can build its own view of the back-end business object with a reduced structure that best suits the business
process. This reduced view is also called the ‘beautified view’.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 24
Typically, we recommend to have a beautified view on a single back-end business object in the corresponding
PRONT of the PROT. The reasons for such a 1:1 relationship will be introduced in later sections.
In addition to the PRONTs, the root node itself can also have selection parameters that are relevant for
processing multiple PRONTs.
As a rule, a beautified view must be designed to incorporate as few attributes as possible (those which are
required for the use case). In addition to this basic rule, the attribute structure of a PRONT will also influence
and is influenced by the following criteria:
Attributes that are required for the selection of other PRONTs in case several PRONTs exist in the model
Attributes that are needed for the execution of the query (called private details of a PRONT)
Attributes that are provided to a well-defined user role that executes the use case (also known as public
details of a PRONT)
Any attributes of the back-end service operation signature that are not required for the use case should be left
out of the PRONT structures. In order to structure the attributes described above, PROB inserts several
predefined nodes into a PRONT model that will be described in the next section.
Data structures that are used to model PRONT details can be flattened and re-structured for simplicity and need
not necessarily reflect their original structure as in the corresponding back-end business object model.
3.4.4 PROT Object Model Template
PROB follows a standardized business object model template for completing the PROT model. While the
designer of a PROT decides on the structure of PRO/PRONTs with the attributes that are required from a use
case perspective, PROB in addition adds some standardized nodes that later on address the generic processing
features of a PROT. Attributes that are related to the back-end business object and relevant for a PROT must
always be added to a predefined standard node called Details that is available for each node type of the PROT.
If data is relevant for a PROT but should not be exposed to the consumer via service, it must be added to a
predefined standard node called PrivateDetails.
The following nodes are added by PROB for all node types of a PROT in a defined hierarchy:
AdministrativeData (always added by PROB)
Selection (optional, to be specified in PROB if required)
Details (optional, to be specified in PROB if required)
PrivateDetails (optional, to be specified in PROB if required)
RefreshControlConstraints (transient, available in Refresh request)
Figure 3-6 shows the abstract PROT model template:
Beautified View
The node structure of a PRO/PRONT should have as few attributes as necessary for the use case and
as many as required for the successful execution of the use case.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 25
<Persistent Retrieval Object> <Version>
<Persistent
Retrieval
Object>
<Version>
Administrative
DataBusiness
Process
Chain
Assignment
Selection
Parameters
Response
<Node>s
<Node>
Administrative
Data
Provider Log
<Node>
Details
<Node>
Refresh
Control
Constraints
Node Type
Status
Refresh
Control
Constraints
<NodeType>s
Selection<NodeType>
Selection
Administrative
Data
<NodeType>
Selection
Parameters
Figure 3-6: Abstract PROT Object Model Template
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 26
The names for <Persistent Retrieval Object> and <Node> can be chosen following the guidelines and
naming conventions as specified by the SAP SOA Modeling Methodology (see section 1.2). <Node>s represents
the PRON types (there can be one or more in a PROT) and the indicated cardinality is the cardinality of the PRON
instance.
Following this abstract PROT model, Figure 3-7 shows the object model of PROT for the sample business
process:
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 27
Flight Search
Flight Search
Administrative
Data
Selection
Parameters
Response
Flight
Administrative
Data
Provider Log
Details
Refresh
Control
Constraints
Refresh
Control
Constraints
Flight
Selection
Administrative
Data
Parameters
Shuttle
Selection
Shuttle
...
...
Business
Process
Chain
Assignment
Node Type
Status
Figure 3-7: Detailed Object Model for Sample PROT FlightSearch
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 28
3.4.5 Predefined Nodes
This section describes in detail the attribute structure of the predefined nodes that are introduced into a PROT
model by PROB.
In general, PROB introduces the following elements into the service signatures of all the service operations that
are generated for PROT services:
MessageHeader
Typed with data type BusinessDocumentMessageHeader
Log
Typed with data type Log_V1
Each node of a PROT (including the root node) has a unique identifier:
Element UUID
Typed with data type UUID
For a detailed description of the data types, please refer to the SAP GDT Catalog.
3.4.5.1 Administrative Data
The node AdministrativeData of the PRO (root node) has the following structure:
Element Name: Data Type Remark
BusinessProcessChainAssignment:
OPTIONAL_BusProcChnAssgmtFSElmnts
BPCA: Contains elements for unique identification of
the process chain that the PROT instance is
assigned to together with a
BankingBusinessTransactionTypeCode (the
coded representation of the process type).
At runtime, if the element UUID is not assigned by
the consumer of a PROT service, it is automatically
assigned by the PROT implementation.
Once a BPCA is assigned to a PRO instance, the
BPCA cannot be changed anymore.
ReferenceID:
BusinessTransactionDocumentID
An identifier for a business transaction document
provided externally
ChangeStateID: ChangeStateID Represents the latest change state of the PROT
instance.
This element is used to implement the optimistic
locking feature in the stateless enterprise services
of a PROT.
ObjectNodeTypeCode: ObjectNodeTypeCode Coded representation of each PRONT including the
PRO (root node). Once the PROT design and
governance process has been finalized, the
integration architects assign the
ObjectNodeTypeCode and also ensure its
uniqueness. The context of ObjectTypeCode
(coded representation of the business object) is
encoded in the ObjectNodeTypeCode.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 29
The ObjectNodeTypeCode values that are
assigned to the PRONTs in PROB (at design time)
should not be changed afterwards. A change
requires regeneration.
AggregatedStatusCode:
PersistentRetrievalObjectNodeStatusCode
Each PRON instance has a status, which can be
changed by executing a PROT service operation.
This element represents the aggregated status of all
instances of a PRON type.
(More details follow in the Status Model section).
NodeTypeStatus:
<PersistentRetrievalObject><Version><Ap
plication>AdminvDataNodeTypeSts
Contains an AggregatedStatusCode for each
PRON type.
ProcessLog: Log_V1 It contains those messages related to the
processing of the PROT instance (see the Phase
Model section for details) that are relevant for the
root node.
The node AdministrativeData as used in the individual PRONTs has a slightly different structure:
Element Name: Data Type Remark
ProviderID: <ProviderID> Identifier of the related back-end business object for
a PRON. It has to be set to the actual GDT of the
back-end business object identifier during PROT
modeling in PROB.
The element must be filled on successful
confirmation of a back-end service call using a
custom code slot implementation.
ReferenceID:
BusinessTransactionDocumentID
An identifier for a business transaction document
provided externally
ObjectNodeTypeCode: ObjectNodeTypeCode Same as for PRO element ObjectNodeTypeCode
(see previous table)
StatusCode:
PersistentRetrievalObjectNodeStatusCode
Status of a PRON instance, which can be changed
by executing a PROT service operation
RetrievalDateTime: DateTime The time-point at which the node data was retrieved
from the back end
Predecessor:
<PersistentRetrievalObject><Version><Ap
plication>Response<Node>AdminvDataPrdcs
sr
ID of a node which is a predecessor to this node
instance
ProviderLog: Log_V1 Contains messages from the back-end system for
back-end calls made by the PROT during the Fetch
and Complete phase
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 30
3.4.6 PROT Object Model in ESR
PROB uses ESR as the modeling environment to capture the complete object model of a PROT with all its
elements and attributes. There is no graphical modeling environment in ESR. Therefore, all the relevant
metadata of a PROT are captured using an existing entity in ESR, which is the data type.
ESR is used as the PROT modeling tool because during PROT generation PROB works extensively with ESR and
can programmatically access the model of a PROT just as it would access other data types. Furthermore, having
the model as well as the implemented data types/services of a PROT in a single tool enables the MDSD
approach.
In order to capture the PROT object model in ESR, PROB also generates the following special data types that
define the metadata of a PROT object model.
3.4.6.1 Provider IDs
M_<Persistent Retrieval Object>_PRO_PRON_ProviderIDs
This data type can be used to specify the actual identifiers of the related back-end business objects.
3.4.6.2 Details
M_<Persistent Retrieval Object>_PRON_<Persistent Retrieval Object Node>_Details
The Details node is optional for all nodes (PRO and PRONT). In this node, the beautified views of related back-
end business objects are modeled. The elements of the node are freely definable. However, at PRONT level most
of the elements of this node can typically be found in the back-end business operations that are associated with
the PRONT. In accordance with the concepts discussed in section 3.4.3 above, the following modeling options
also possible:
For the sake of beautification, the deep structures of the back-end operations can be flattened out to define
the element structures.
Elements of this node can also be deeply structured using table-like nodes.
In case such deep structures are modeled, we strongly recommend to use the naming conventions
prescribed by PROB (with prefix M_<Persistent Retrieval Object>_) right from the beginning
during modeling. This approach will reduce manual activities later on during PROT modeling in the PROB
Modeling Wizard, as these data types are then automatically copied to the productive environment in case
different namespaces are used (see 3.4.6.5 for details).
We highly recommend to keep the node structure as simple as possible and as detailed as absolutely required
for the consumer of the PROT.
3.4.6.3 Private Details
M_<Persistent Retrieval Object>_PRON_<Persistent Retrieval Object Node>
_PrivateDetails
The PrivateDetails node is optional for all nodes (PRONs). The elements of this node are freely definable. In
contrast to the Details node, the PrivateDetails node will not be exposed by the PROT service interfaces.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 31
Private Details should only be modeled if a PRON requires additional attributes which will only be used for
internal PROT processing and should not be exposed to the consumer of the PROT.
In ESR, the elements of this node are modeled in the same way as those of the Details node. These elements
will then be available for PROT-internal processing during all phases of a PROT.
3.4.6.4 Selection Parameters
M_<Persistent Retrieval Object>_PRO_SelectionParameters
M_<Persistent Retrieval Object>_PRON_<Persistent Retrieval Object Node>_
SelectionParameters
The node SelectionParameters is optional for all nodes (PRO and PRON).
This node is used to model the parameters for retrieval of data that are relevant for the entire PROT or a specific PRON.
The elements of this node can be chosen freely as long as the naming conventions follow the service modeling
guidelines and GDTs are used as data types.
For the specification of selection parameters the specified attributes must be relevant and required to select
the corresponding business objects for the PROT.
3.4.6.5 Data Types used for Modeling
During modeling of Details, Private Details, and Selection Parameters it is important to consider how the data
types that are used for modeling are handled when it comes to generation of the runtime ESR artifacts. The
following types can be used:
Data type with prefix M_<Persistent Retrieval Object>_ as prescribed by PROB during modeling.
During generation of the (runtime) ESR artifacts, this data type will be copied to a new type with a PROT
specific name. The cardinality of all elements of this type will be set to optional. This is necessary to
support the work in progress handling of “incomplete” data within a PROT. Consequently, modeling types
with the prefix M_<Persistent Retrieval Object>_ are PROT specific and cannot be reused across
different PROT models.
GDT or other data type that does not follow the naming convention M_<Persistent Retrieval
Object>_. During generation of the (runtime) ESR artifacts, this data type will be used within the ESR
runtime artifacts as is. In contrast to the modeling type with prefix M_<Persistent Retrieval
Object>_ these types can be used across different PROT models.
Private Details are not exposed in any PROT service interfaces. However, corresponding runtime ESR artifacts
for Private Details are generated in order to have a corresponding SPROXY type available which is the basis for
the generation of DDIC types.
3.4.7 Separation of Modeling and Productive Entities
The ESR entities that are used to define the model of a PROT are not required for the productive environment
of a PROT. They are only required again by PROB if and when the PROT model changes. In this case they are
used to regenerate the remaining affected artifacts of a PROT. The model data in ESR for a PROT object model
is not required for the runtime of the PROT. Therefore, PROB (early on in the Modeling Wizard) separates the
modeling and productive environment of a PROT.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Definition
PUBLIC
© 2017 SAP SE. All rights reserved. 32
There are several separation options:
Same SWC and SWCV and ESR namespace for modeling and productive environments but separate
folders
In this case, there is no way to separate the shipment of modeling and productive content in ESR as folders
are just logical constructs. This means that the model data of a PROT is also shipped and available within
the productive landscape of the PROT. This option is mostly used for PROT prototyping in order to avoid
multiple namespaces in ESR.
Same SWC and SWCV but different namespaces for modeling and productive environments
In this case, there is a separation between modeling and productive content in ESR based on the
namespaces. This option means that the modeling data of a PROT is also shipped and available within the
productive landscape of the PROT.
Different SWC and SWCV (and therefore different namespaces) for modeling and productive
environments
Separate shipment is straightforward. Modeling content can be excluded from shipment.
This option is the most flexible one but it requires the creation of SWC/SWCV for modeling only (at least in
ESR), and during PROT generation a small additional step is required from the PROT developer to ensure
that the required data types (prerequisite data types like BusinessDocumentMessageHeader or data
types used in the Details nodes) are present in the ESR namespaces of both SWCVs.
Architectural Decisions
The way in which modeling and productive environments are separated must suit the shipment
requirements of a PROT.
Architectural Recommendation
It is strongly recommended to separate modeling and productive environments into different Software
Component Versions (SWCVs) for a productive PROT.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Programming Model
PUBLIC
© 2017 SAP SE. All rights reserved. 33
4 PROT Programming Model
A PROT that is generated by the PROB is based on MDSD. The MDSD approach shortens implementation times
by generating most of the implementation code upfront and providing only minor parts of the implementation
to be completed in code slots. Before implementing those code slots, it is very important that you understand
the underlying predefined programming model of a PROT. The detailed description of the programming model
can be found in later parts of this guide. However, this understanding is also important for PROT modeling, for
example to verify the capabilities of a PROT against the requirements of a process and to decide on the PRON
cut as well as the number and type of back-end services to be assigned to a PRON in the different life cycle
phases of a PROT). Therefore, this section provides a high-level overview of the programming model that a
PROT is based on.
4.1 Basic Principles
The programming model of a PROT is based on following basic principles:
4.1.1 Separation of Concerns: Process vs. Business Logic
In SAP SOA Modeling Methodology, the granularity at which business logic is encapsulated is the business
object. A business object resides completely in one software component (deployed on a single physical back-
end instance). It is responsible for the consistency of its own data, for its own life cycle phases, the phase
transitions and all associated validation and consistency checks.
A persistent retrieval object on the other hand is utilizing several back-end business objects, represented by the
corresponding PRONs in the PRO model. A combination of PROTs and POTs could be defined for distinct
processes that are required to provide data and orchestrate an overlapping set of back-end business objects. A
PROT implementation must deal with activities like sequencing the back-end object calls and handling
responses from individual back-end service calls for the query implemented via the PROT.
The programming model is based on this principle and, as a consequence, the generated PROT implementations
are designed exclusively for dealing with this logic.
4.1.2 Pattern for Processing Flow
The current PROT programming model complies with a use case in which a PROT executes a query in the
following pattern:
1. Retrieve the most relevant data from the back ends and to determine the number of instances of a node
type that are to be retrieved
2. Complete all details of node instances
This processing flow pattern also forms the basis for the phase model of a PROT (explained in later sections). In
addition to the basic flow of the pattern described here, the programming model also foresees a robust status
model that provides flexibility for:
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Programming Model
PUBLIC
© 2017 SAP SE. All rights reserved. 34
Indicating incomplete PROT data but allow access to already collected data to support user interfaces in
showing intermediate results
Providing information about expired data and support individual refresh on node instance level as well as
node type level.
4.2 Phase Model
Following the processing flow pattern (4.1.2), the PROT phase model consists of two phases:
Fetch phase
o Initializes the persistent retrieval object (PRO) and its nodes (PRONs) according to the given
data
o Nodes might be filled partially
Complete phase
o The PRONs not completed during Fetch phase are completed
o Addition and deletion of nodes is possible
Figure 4-1 shows a high-level overview of the phases and phase transitions of a PROT:
Fetch
StartExecutionRestartExecution
Refresh
Complete
Figure 4-1: High-Level Phase Model of a PROT
Figure 4-1 shows only a simplified phase model, related to the overall life cycle of a PROT.
A more comprehensive overview including all the allowed status transitions follows in section 4.4.
4.3 Status Model
For each phase of a PROT, there is a set of predefined statuses and status transitions.
The following basic principles apply to the PROT status model:
The status of a PRON instance can be changed
By executing a changing service operation
By events related to the corresponding back-end object
By time-out
There is a separate status on node type level (PRONT) which is calculated taking the status of all PRON
instances into account and paying heed to the fact whether the collection of instances is finished or not.
The overall status of the PRO is calculated taking the statuses of all its PRONTs into account
The statuses (PRO / PRONT / PRON) are listed as code values of the GDT
PersistentRetrievalObjectNodeStatusCode:
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Programming Model
PUBLIC
© 2017 SAP SE. All rights reserved. 35
Code Name Description
1 Waiting Waiting for another node to complete
2 Running Running its query
3 Expired Data are no longer up-to-date
4 Finished Data have been collected successfully and are up-to-date
5 Erroneous Processing failed with error messages
6 Aborted Processing has been aborted while running/waiting
Table 4-1: Values of GDT PersistentRetrievalObjectNodeStatusCode
Figure 4-2 explains at a high level, how the overall (aggregated) PRONT/PRO status is calculated from the
individual underlying statuses:
Figure 4-2: Status Calculation of Aggregated PRO/PRONT Status
Details on overall status calculation follow in Part II of this guide.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Programming Model
PUBLIC
© 2017 SAP SE. All rights reserved. 36
4.4 Status Transitions
The PROT programming model predefines the allowed status transitions depending on the status itself and the
phase in which the PROT currently is.
Figure 4-3 gives a detailed overview of the allowed status transitions:
Figure 4-3: Overview of PROT Status Transitions
Here are some key takeaways:
It is always possible to read a PROT, irrespective of the PRO status or that of its PRONs
The status Erroneous can occur due to a failed query operation
A successful execution of a PRO without failed operations results in the status Finished of this PRO
The status Expired can occur due to one of the following reasons:
Information message from the backend stating that a business object has changed
Time-based rules: Nodes instances expire after a certain amount of time
Relationship-based rules: When a predecessor (successor) of a node expires, the successor
(predecessor) automatically expires as well
A detailed description of how statuses are handled by the PROT and by the custom implementation code slots
follows in Part II of this guide.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Programming Model
PUBLIC
© 2017 SAP SE. All rights reserved. 37
4.5 Phase Implementation
Almost all the custom code slots that must be implemented by a PROT developer to complete the PROT
implementation are related to and classified according to the phase model of the PROT.
The following sections describe the key principles that you should keep in mind while implementing the phases
of a PROT.
Figure 4-4 provides a legend for the sequence diagrams in all the following sections:
Figure 4-4: Legend for Sequence Diagrams
Methods that contain a code slot are depicted as a solid grey bar. Methods that can contain a code slot but do
not have one in this particular case are depicted as a grey bar with gradient.
4.5.1 Fetch Phase
In the Fetch phase, the data of a PROT is populated according to the following basic principles:
The back-end services that have been assigned to the Fetch phase of the PRON during PROT modeling in
PROB will be called to retrieve the data of back-end business objects that is relevant for the beautified view
of the PRON (PROT service call <PRO>StartExecution, <PRO>RestartExecution, and
<PRO>Refresh).
The custom implementation must take care of the OperationType and SelectionParameters and
populate the PRON data accordingly.
The OperationType values contain instructions on whether to start, restart or refresh the data of the
PRON using the SelectionParameters provided by the PROT service via the back-end service(s)
assigned to the Fetch phase. A detailed description on how to handle the OperationType element will
follow in Part II of this guide.
The Fetch phase is parallelizing the service calls on node type level (taking dependencies into account)
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Programming Model
PUBLIC
© 2017 SAP SE. All rights reserved. 38
In the FlightSearch sample PROT, the following back-end services can be modeled for calls in the Fetch
phase: (The actual service interfaces and operations will be detailed in Part II of this guide.)
PRON: Flight
Service operation for reading flight information for the specified FromAirport, ToAirport, and
PlannedFlightDate in the SelectionParameters of the PRO and filling the PRON instance
Details for each flight that is available for the specified PlannedFlightDate.
PRON: Shuttle
There is no service operation to be called, but there will be a shuttle entry prepared for each flight
Figure 4-5 shows a sequence diagram of the Fetch phase, including the Fetch phases of all the PRONs and the
back-end services involved:
Figure 4-5: Fetch Phase – Dynamic View
The PRON "Flight" calls a back-end service during the Fetch phase. The PRON "Shuttle" does not use back-end
services in this phase.
In the Fetch phase, all the PRONs always have a code slot.
4.5.2 Complete Phase
The most important principle for this phase is that the data of a PRON can be completed based on the Fetch
results.
This phase provides the possibilities for the custom implementation to complete the data of a PRON instance
via call of specified back-end services (if selected during modeling in PROB). In addition, new node instances
can be added and existing node instances can be deleted.
In the sample PROT, the following back-end services can be modeled for calls in the Complete phase (the actual
service interfaces and operations will be detailed in Part II of this guide):
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Programming Model
PUBLIC
© 2017 SAP SE. All rights reserved. 39
PRON: Flight
Service Operation to check the availability of seats in the selected flight. The operation is provided by the
back-end business object for flight booking.
PRON: Shuttle
Service Operation to check the availability of seats in the shuttle connection for the selected flight. The
operation is provided by the back-end business object for booking shuttle connections.
Figure 4-6 shows a sequence diagram for the Complete phase of the sample PROT:
Figure 4-6: Complete Phase – Dynamic View
The Complete phase is parallelizing the service calls on instance level. The PRONs "Flight" and "Shuttle" call
services from the back end. The Complete phase is started automatically as soon as the Fetch phase is
finished.
In the Complete phase, all the PRONs always have a code slot.
4.5.3 Node Dependencies
In general, the PROT programming model treats each PRON of a PROT independently from other PRONs during
the creation or execution of a PROT (since each PRON represents an independent business object of the
corresponding back end). That means that a PRON, in general, can neither access nor modify details of another
PRON. However, during the Fetch phase and the Complete phase of a PROT, it is often required to call the back-
end services in a certain sequence to ensure an appropriate creation of the PRONs in a consistent manner. In
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Programming Model
PUBLIC
© 2017 SAP SE. All rights reserved. 40
order to implement such a sequencing of the back-end service calls, PROB offers the so-called "node
dependencies" which can be specified for a PROT at design time in the PROB Specification Wizard.
In our sample use case, the PRON "Flight" must be executed before the PRON "Shuttle" is executed, as the flight
arrival and departure times are required to successfully select the corresponding shuttle options.
The specification of node dependencies for the Fetch phase as well as the Complete phase of the sample use
case looks as follows:
Fetch Phase
Prior Persistent Retrieval Object Node (PRON) Subsequent Persistent Retrieval Object Node (PRON)
Flight Shuttle
Complete Phase
Prior Persistent Retrieval Object Node (BPON) Subsequent Persistent Retrieval Object Node (BPON)
Flight Shuttle
If node dependencies have been specified, the PROT implementation permits access to the details of the
corresponding PRON (Prior Persistent Retrieval Object Node) by a dependent PRON (Subsequent Persistent
Retrieval Object Node).
These are the most important principles for the specification of node dependencies:
Node dependencies can be specified independently for the Fetch and for the Complete phase.
Access from a subsequent PRON to a prior PRON is restricted to the corresponding phase for which the
dependency has been specified at design time.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT High-Level Design
PUBLIC
© 2017 SAP SE. All rights reserved. 41
5 PROT High-Level Design
Now that you've got an understanding of the programming model of a PROT, it is useful to look at the high-level
design of a PROT in terms of its static view.
This chapter therefore introduces the high-level design of a PROT, including a general overview of both, the
generated PROT artifacts and the static relationships at design time and runtime. The ABAP package overview
for a PROT is also introduced with high level dependencies. The last section of this chapter gives an overview of
the key information required from a development architect’s point of view (in the form of a checklist).
5.1 Block Diagram
The complete design time and runtime environment of a PROT can be classified into the following parts:
Design-time artifacts in ESR for the service operations that are provided and consumed by a PROT
The generated ABAP artifacts for the implementation of the PROT
In addition to the parts listed above, which are relevant for PROT shipment, the PROB design-time modeling
artifacts that are used for generating the PROT artifacts also reside in ESR.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT High-Level Design
PUBLIC
© 2017 SAP SE. All rights reserved. 42
Figure 5-1 provides an overview of the static structure of a PROT:
Figure 5-1: Static PROT Structure
The dashed lines represent PROT design time relationships. The following sections describe the static
structure in more detail.
5.1.1 ESR Content
PROB generates all the services required by a PROT into ESR:
Synchronous inbound services to access the PROT
Asynchronous inbound services to get informed about status changes of the related business objects
Outbound services (synchronous) that are required to call the back-end inbound services that have been
modeled at PRON level of a PROT
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT High-Level Design
PUBLIC
© 2017 SAP SE. All rights reserved. 43
Outbound events to inform about status changes of the PROT
In addition to the services mentioned above, the ESR content that is used for PROT modeling is also present
depending on the choice of SWCV and ESR namespace (see section 3.4.7).
5.1.2 ABAP Artifacts
The PROT itself is made up of all the ABAP artifacts that are generated by PROB.
PROB generates ABAP artifacts according to the package and software layer concept, which is standardized.
The layer concept of a PROT can briefly be summarized as follows:
Services Inbound Layer – ABAP implementation artifacts for all the inbound service interfaces of a PROT
Application Layer – all the artifacts that implement the ABAP APIs, phase and status handling, checks,
persistence and integration to tools like CNS and OAF for a PROT
Services Outbound Layer – ABAP implementation for all the outbound service interfaces of a PROT
5.1.3 Back-End Services
In general, PROB does not touch any existing back-end service interfaces. The service definitions of the back-
end services that are called by a PROT must exist in the same ESR system that is used by PROB for modeling
and generation of the PROT. The message types and global data types that are used by the back-end services
are copied (in a manual step) into the ESR namespace of the PROT.
Nevertheless, the PROB shipment also includes SIW templates that help you to implement the service interfaces
in the back end. You can use these templates to generate service implementations that follow a standard
programming model, which will accelerate the implementation of back-end services with features like ECH, PSJ
and so on, depending on the service type. However, please note that the shipped SIW templates are only
intended to help with service implementation. You cannot generate any ESR content with these templates.
More information on service development with the SIW templates shipped with POB can be found in the
corresponding Developer's Guide (“Implementation of Enterprise Services Using SAP Process Objects
Builder”).
5.2 Package Structure
There are four packages that define the ABAP environment of a PROT:
The root package (or <ROOT> in Figure 5-2 below) can be, for example, the structure package of the
software component.
ABAP namespaces are also supported. If an ABAP namespace is used, the package name should also start
with this ABAP namespace.
A PROT implementation (with all its ABAP artifacts) is generated into the main package <MLB>MAIN. The
super package for this main package must be specified in the PROB Specification Wizard (Step 1 – Define
ABAP Environment).
A PROT can exist together with other POTs and PROTs in this super package, as long as they use the same
productive ESR namespace. In this case
The SPROXY types for all ESR data types will be in the package for common proxy types
<COMMON_PROXIES>.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT High-Level Design
PUBLIC
© 2017 SAP SE. All rights reserved. 44
The internal DDIC types that are used across different PROTs are located in the package for common
internal types <COMMON_ITYPES>.
Figure 5-2: ABAP Environment of a PROT
Once the ABAP environment of a PROT is defined, all the ABAP artifacts of the PROT itself are generated into
the corresponding subpackages (see subsequent sections).
5.2.1 PROT Core
Figure 5-3 shows the package structure (sub-packages under the main package of a PROT). Dedicated
packages are foreseen for internal types (<MLB>_ITYPES) as well as inbound (<MLB>_SIN) and outbound
service layers (<MLB>_SOUT).
The application layer of a PROT consists of dedicated packages for general objects <MLB>_GENRL (reused
across several PROT artifacts), the core API of a PROT <MLB>_API, and a separate package <MLB>_CUST is
used for custom objects (ABAP artifacts that are intended for code slot implementation).
Please note that a PROT developer (with sufficient development coordination authorization in the ABAP system)
must create these packages manually according to the instructions in the corresponding Generation Wizard
step.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT High-Level Design
PUBLIC
© 2017 SAP SE. All rights reserved. 45
Figure 5-3: Core Package Structure of a PROT
Architecture and Design Decisions for PROT
The creation of a PROT using PROB requires several decisions, for example on input values, which must
be made by an architect. It is strongly recommended that these decisions are sufficiently documented.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT High-Level Design
PUBLIC
© 2017 SAP SE. All rights reserved. 46
5.2.2 Package Encapsulation
It is a well-proven best practice in architecture to encapsulate functionality and use package interfaces with use
accesses to expose only the required software artifacts. This ensures a better handling of dependencies
between software artifacts. In the context of a PROT implementation, the most important objective of
encapsulating artifacts is to minimize the dependency of custom code slot implementation on the other
generated PROT artifacts. To follow this practice, you should ensure that the custom code slots only use
generated objects that are sufficiently exposed. Doing this, in turn, provides the advantage that the custom code
slots will rely on stable contracts between generated and custom coding and also ensures that there will be no
impact on custom coding in case some internals of the generated (not exposed) code change due to a feature
enhancement in PROB.
PROB generates the package interfaces and checks that corresponding use accesses are maintained
sufficiently and appropriately (no less than necessary, no more than required). However, the maintenance of
use accesses itself is a manual activity that is performed in one of the last Generation Wizard steps.
The following three types of package interfaces are used within a PROT:
Interfaces for customer-specific implementations
These interfaces only expose those ABAP artifacts that are intended for custom usage and therefore
offer the required stability. These interfaces are added as use accesses to the custom package.
PROT-internal interfaces
PROT-internal interfaces are added as use accesses for packages that contain generated ABAP artifacts
only.
5.3 PROT Design & Specification Checklist
PROB requires several input data that is used to derive the names of the generated PROT artifacts such as ESR
content and ABAP implementation objects. This input data is requested by PROB in various steps of the
Modeling and Specification Wizards.
Although most of these values seem trivial to specify in the wizard steps, in a real PROT development scenario
some of these values must be chosen with care by development architects. For others, we recommend that the
architects specify naming conventions for the development teams. This section provides an overview of this
type of input data that is required by the PROB wizards together with some rationale/motivation and
suggestions for naming conventions.
The following table only gives you an overview of the input data that is important to consider from a development
architect’s point of view. We strongly recommend PROT developers to always refer to the quick help that is
provided with each PROB wizard step in order to get the most relevant information on the values to be specified,
applicable prerequisites for a step and so on.
In the "Wizard" column, the following abbreviations are used:
"M" - Modeling Wizard
"S" - Specification Wizard
"G" - Generation Wizard
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT High-Level Design
PUBLIC
© 2017 SAP SE. All rights reserved. 47
Input / Activity Wizard Step Comment / Motivation / Suggestion
Modeling a PROT - - It is a general recommendation that the overall context and
software architecture environment of a PROT should be
modeled using standard SAP or other modeling tools of
choice.
For the PROTs shipped by SAP, the SAP SOA Modeling
Methodology standards and tools must be adhered to.
Documenting a
PROT design
- - The design document of a PROT is one of the few things that
the PROB does not generate. We strongly recommend to
sufficiently document important design and architecture
decisions in a dedicated design document.
Configuration ID M Enter General
Data
Must be unique for each PROT.
Must also be unique across builders, i.e. a PROT and a POT
cannot have the same ID.
Process
Component
Name
M Enter General
Data
Must be unique for each PROT (see section 3.4.1 for details).
Exception: Multiple versions of the same PROT can have the
same process component name.
For SAP-internal development, this name must be identical
to the process component name approved in the PIC
governance process (PIC 0).
SIW Landscape
ID
M Enter General
Data
Must correspond to a working SIW Landscape (refer to SIW
customizing)
Application
Component
M Enter General
Data
Appropriate name that is assigned to the PROT in the SAP
Application Component Hierarchy. This is an important
decision that must be made by architects.
The value is used (amongst others) in the artifacts related to
the following aspects:
Packages
ECH / PPO
Later changes to this value are incompatible and require
regeneration of the PROT.
Software
Component
M Enter General
Data
Corresponds to the shipment unit in ABAP.
Cannot be changed.
ESR Namespaces
for Modeling and
Productive
Environment
M Enter ESR
Data
Important architectural decision: See section 3.4.7 above.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT High-Level Design
PUBLIC
© 2017 SAP SE. All rights reserved. 48
Input / Activity Wizard Step Comment / Motivation / Suggestion
PRON Details –
Node Type
Identification
M Define
Persistent
Retrieval
Object Nodes
For SAP-internal development:
ESR Name and Description must be identical to those
approved in the PIC process (PIC 2).
The supplementary components (Code List ID etc.)
must be identical to those maintained centrally by
integration architects.
For partner/customer development:
Separate listID/listAgencyID must be maintained
for the complete system landscape. Each PRONT of a
PROT must be assigned a code value that makes the
PRONT uniquely identifiable within the context of the
listID and listAgencyID.
We recommend to follow UpperCamelCase style when
specifying the ESR names.
PRON Details –
BO Type
Identification
M Define
Persistent
Retrieval
Object Nodes
Business Object Type Code must be unique for each PROT
and each of its versions. We therefore recommend to also
include the version of the PROT.
It is used by some of the connected tools, such as ECH.
PRON Details –
Data Type
Settings & Back-
End Operations
M Define
Persistent
Retrieval
Object Nodes
For SAP-internal development:
Values must correspond to the content of the approved
PIC document (PIC 2) for the PROT with the
corresponding models
Packages (Root,
Proxy Objects,
Common Internal
Types)
S Define ABAP
Environment
Proxy objects and common internal types that are used in
multiple PROTs must be located in a package that is different
from the root package of the PROT.
Packages must exist and sufficient use accesses must be
specified.
Package names must start with the Customer Namespace or
the ABAP Namespace, if any (see below).
Refer to section 5.2 above for details on how to specify the
packages.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT High-Level Design
PUBLIC
© 2017 SAP SE. All rights reserved. 49
Input / Activity Wizard Step Comment / Motivation / Suggestion
ABAP
Namespace,
Customer
Namespace,
ABAP
Abbreviation
S Define ABAP
Environment
ABAP Namespace, Customer Namespace and ABAP
Abbreviation are used to derive the names of ABAP artifacts
according to specified derivation rules.
Derivation rule for classes/interfaces:
[<Customer Namespace>|<ABAP
Namespace>][IF|CL]_<ABAP Abbreviation>_<PROT
Abbreviation><PROT Version>_...
For SAP-internal development:
At least one of ABAP namespace and ABAP
abbreviation must be filled
When ABAP namespace is not filled, ABAP abbreviation
must be at least three characters long and not contain
an underscore at 2nd or 3rd position (due to DDIC
naming conventions)
For partner/customer development:
Either customer namespace or ABAP namespace must
be filled
When ABAP namespace is not filled, ABAP abbreviation
must be at least two characters long and not contain an
underscore at 2nd position (due to DDIC naming
conventions)
We still recommend to limit the ABAP abbreviation to as few
characters as possible to avoid a violation of length
restrictions in the ABAP artifact names.
SPROXY Prefix S Define ABAP
Environment
For proxy types the SPROXY Prefix is used to derive the
proxy type name: <SPROXY Prefix>...
Must be identical for all objects of one ESR namespace.
This means that two PROTs in the same namespace
must have the same SPROXY prefix!
Must start with the Customer Namespace or the ABAP
Namespace, if any
Must be at least three characters long
Must not contain an underscore at 2nd or 3rd position (due to
DDIC naming conventions)
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT High-Level Design
PUBLIC
© 2017 SAP SE. All rights reserved. 50
Input / Activity Wizard Step Comment / Motivation / Suggestion
Common Internal
Types Prefix,
PROT-Specific
Internal Types
Prefix
S Define ABAP
Environment
There are two prefixes required for internal types:
Common Internal Types Prefix and PROT-Specific Internal
Types Prefix.
The prefix for common internal types is used for all internal
DDIC types that are shared within an ESR namespace, such
as DDIC types for back-end related message types.
The prefix for PROT-specific internal types is used for DDIC
types that are specific for a PROT, such as DDIC types for
PROT-related message types.
Must be at least one character shorter than the
SPROXY Prefix
Must start with the Customer Namespace or the ABAP
Namespace, if any
Must not contain an underscore at 2nd or 3rd position
(due to DDIC naming conventions)
Abbreviations for
back-end service
counterparts
S Specify
Counterparts
for Back-End
Services
The abbreviations are used to derive the names of ABAP
artifacts (see above). We therefore recommend to limit the
length of the abbreviations to as few characters as possible.
Suggested naming convention for PROT interface
abbreviations (max. abbreviation length = 4 characters):
Manage - <BO>M[I|O]
Action - <BO>A[I|O]
Query - <BO>Q[I|O]
Event <BO>E[I|O]
<BO> = Back-end business object abbreviation (maximum 2-
3 characters)
Suggested naming convention for PROT operation
abbreviations (max. abbreviation length 4 characters):
Find – FND
Read – RED
Retrieve – RTR
…
CNS Application
ID and
Information
Message
Receiver
S Enter
Information
for CNS
The Application ID identifies the PROT within the CNS
customizing. It must be unique for each PROT (across all
PROTs).
Receiver (Information Message) identifies the CNS receiver
implementation that triggers the information messages that
are sent by the PROT after response expiration.
Suggested naming conventions are as follows:
Application ID – <PROT Abbreviation><PROT
Version>
Receiver – <PROT Abbreviation><PROT Version>E
(for Response Expiration event)
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT High-Level Design
PUBLIC
© 2017 SAP SE. All rights reserved. 51
Input / Activity Wizard Step Comment / Motivation / Suggestion
Creation of
development
packages
G Create
Packages
See section 5.2
Maintenance of
use accesses
G Create Use
Accesses
See section 5.2.2
Architecture and Design Decisions for a PROT
The creation of a PROT using PROB requires several decisions, for example on input values, which must
be made by an architect. It is strongly recommended that these decisions are sufficiently documented.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT High-Level Design
PUBLIC
© 2017 SAP SE. All rights reserved. 52
Part II – Detailed Design & Implementation
PROB heavily supports the
implementation of a PROT by
generating most of the required
artifacts. However, in order to
complete the implementation,
implementation code must be
inserted in specific code slots that
are generated into the PROT
artifacts. In order to successfully
leverage the programming model of
a PROT and ensure conformance to
this model, you need to know about
the generated artifacts, about which
parts of these artifacts can be used,
and where custom objects (ABAP)
can be introduced.
This part of the Developer's Guide
provides in-depth information about
a PROT, including a description of
the generated artifacts and a sample
implementation of the predefined
code slots. It also provides
information on the APIs of the
generated artifacts and how to use
them.
Make sure that you are familiar with
the concepts explained in Part I of
this guide before proceeding.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 53
6 PROT Detailed Design
This chapter marks the start of Part II of the PROT Developer's Guide. Before you start on this part, you should be familiar with the overall background and motivation for a PROT, the high-level architecture, the programming model and the high-level design of a PROT, all of which are covered in Part I of this guide This part of the Developer's Guide provides a deeper insight into the detailed design of a PROT, with a focus on the implementation of code slots to complete the PROT development. Nevertheless, it is helpful to know exactly, what artifacts are generated for a PROT by PROB, before starting to implement the code slots. In general, a PROT implementation is responsible for:
Initializing a PROT with the query-relevant data, either as a whole or in a step-by-step manner
Executing back-end services and reacting to responses by changing the status of the PROT as required
Handling errors and expired data, reprocessing, refreshing or canceling a PROT
Process events from the back-end components, setting node instances to expired
In order to fulfill these responsibilities, the PROT implementation must have a suitable detailed design with
respect to the following key aspects (among others):
Lifecycle and associated status management
Persistence
Service handling with validation & mapping, if required
As a PROT is built following a MDSD approach, PROB generates the artifacts required to cover the aspects mentioned above. Some of these artifacts contain code slots that have to be implemented with custom code by a PROT developer. This approach of, on the one hand, generating the major parts of a PROT, and on the other hand, providing code slots for the custom code makes the PROT implementations uniform across several PROTs. In order to best leverage the design of a PROT during code slot implementation, it is very important for the PROT developer to understand how the generated artifacts conform to the detailed design, understand the boundary conditions of a PROT design and also the interfaces offered by a generated PROT implementation towards the custom coding in code slots. Therefore, this chapter focuses on the detailed design in the following aspects:
PROT layer concept and major building blocks
Correspondence of layers to the actual development packages of a PROT
Drill-down to artifacts in each layer
Static structures (class diagrams) and dynamic views (sequence diagrams) to explain key concepts and
cross-cutting concerns
“Unix was not designed to stop people from doing stupid things, because that would stop them from doing
clever things “
- Doug Gwyn
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 54
6.1 Layer Concept
PROT design follows a standardized development package concept. This concept foresees an abstract layering
of ABAP artifacts.
Figure 6-1 shows all the involved layers in a block diagram:
Figure 6-1: Block Diagram of PROT Layer Concept
A PROT basically consists of the following layers:
Inbound Communication layer – responsible for connecting the services offered by a PROT to the PROT's
application logic
Application Logic layer – responsible for handling the core processing logic of a PROT with its APIs and the
persistence
Outbound Communication layer – responsible for connecting the outbound service calls to the back ends
The following subsections provide more detailed information on each layer.
PROT
Inbound Communication
PROT Service
Providers
PROT Event
Handler
Proxy Types
R
PROT Implementation
R
Application Logic
Custom Objects General Objects
R R
PROT Persistency
Persistent
Retrieval
Object
Outbound Communication
PROT Event
ProviderBackend Service
Consumer
R
PROT Event
Channel
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 55
6.2 Application Logic Layer
The application logic layer handles the core PROT implementation. It is primarily responsible for handling PRO
instances, phase execution and status management. The single point of entry for the application logic layer is
the application façade.
Figure 6-2 shows a static view of the application façade:
Figure 6-2: Application Façade
The façade class <MLB>CL_AF implements the façade interface <MLB>IF_AF, which provides an EXECUTE
method that is used by all PROT inbound service implementations.
The façade class provides an operation-specific private method for each service operation type. These
operation-specific methods perform the complete call sequence that is necessary to execute the service call.
In order to support authorization checks and versioning, the façade class uses corresponding helpers. It also
uses the APIs for PRO/PRON instance management (shown at the right-hand side of the diagram).
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 56
Figure 6-3 shows an overall call sequence to visualize the responsibilities of the application façade:
Figure 6-3: Application Facade for Operation StartExecution<PRO> - Call Sequence
The application façade is called by the PROT inbound service via the common interface method EXECUTE. The
application façade delegates this call to an operation-specific method, which in this case is
START_EXECUTION_PRO. First, the PRO instance is created and after that, the PROT instance is locked to
prevent other users or processes from changing the instance in parallel. The execution of the PROT is started
by setting the PRON instances to status Waiting.
The RFC helper then processes the phases Fetch and Complete in background by starting a new task. At the end
of the sequence, the confirmation is filled and returned.
The remainder of this chapter will focus on the design of the APIs for PRO and PRON instance management and
Versioning. In addition, the API for message persistence as well as the phase helper classes and their relation to
the phase implementation (where the code-slots are located) will also be explained for the Fetch, and the
Complete phase.
6.2.1 Database Tables
Table 6-1 contains the PROT database tables together with the corresponding APIs:
Table Description
<MLB>_PP Contains the instance data of a persistent retrieval object.
The table is used to store all the instance data of the PRO and its PRONs. It is managed by
the PRO and PRON API (described in sections 6.2.2.1 and 6.2.2.2).
The DB stores the overall status of the PRO.
<MLB>_PS Used to store node type status data
The node type status DB stores the status of each node.
The read access to this table is managed by the PRO API described in section 6.2.2.1
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 57
<MLB>_RA Used to store Persistent Retrieval Object read access data
This database table contains the last read access timestamp regarding a PROT that are
related to read operations.
This information is used to determine whether a PRO can be deleted as there was no read
access for a certain period of time.
Whenever the table <MLB>_PP is read, the corresponding PRO or PRON API needs to
ensure that the table <MLB>_RA is also updated accordingly
The corresponding API is described in section 6.2.2.4
<MLB>_SE Used to store all currently running PRO sessions to be able to stop them in case the PRO
execution is aborted
<MLB>_SL Used to store Persistent Retrieval Object selection parameter
The selection parameters that are provided by the consumer when calling service
operations StartExecution, RestartExecution and Refresh are stored in a separate DB as
they are not part of the response view of the PRO. The selection data is stored on node
type level. This database table has the same key as the database table for node type
status data <MLB>_PS.
The corresponding API is described in section 6.2.2.3
<MLB>_SR Used to store all the elements that are used as selection fields for search queries in a
search-friendly manner.
Whenever search-relevant fields of the table <MLB>_PP are updated, the corresponding
PRO or PRON API needs to ensure that the table <MLB>_SR is also updated accordingly.
The read access to this table is managed by the PRO API described in section 6.2.2.1
<MLB>_VS Keeps the versions of all persistent object instances.
In order to be able to reconstruct the complete history of a PRO Instance a complete
image of the Instance is written to the version database.
The image consists of all public and private data of the PRO and its PRONs (aka TY_TOTAL
+ Versioning-Data)
The corresponding API is described in section 6.2.2.6.
Table 6-1: Database Tables of a PROT
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 58
6.2.2 API Design
Before the APIs of the application logic layer are discussed in detail, you should know that the API for PRO and
PRON instance management as well as the Version API are built following the same layer design.
Figure 6-4 shows the design of the PRO API as an example:
Figure 6-4: PRO API - Static View
The different layers have the following responsibilities:
The API Layer provides and implements the “public” interface, which is mainly used by the application façade
and other helper classes. It usually offers CRUD methods and other convenience methods via the API interface
(<MLB>IF_PRO_API in our example). The implementing class <MLB>CL_PRO_API holds a reference to its
corresponding interface from the object layer <MLB>IF_PRO_OBJ.
The Object Layer is responsible for buffering the data from the persistence layer and raises events in case data
is changed. It basically offers CRUD methods via the interface <MLB>IF_PRO_OBJ. The implementing class
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 59
contains the buffer and holds a reference to its corresponding persistence interface <MLB>IF_PRO_DB. In order
to be able to raise events, the class <MLB>CL_PRO_OBJ implements the event interface <MLB>IF_EVT. The
transaction control client interface <MLB>IF_TC_CLIENT is implemented to reset the buffer at the end of a
transaction.
The Persistence Layer builds the bridge between the PROT object layer and the XO framework. It draws new DB
keys, and manages the buffering of XO object instances. It is based on the complete types, the total type and
more specific interface types. The persistence interface usually offers methods like READ, WRITE and DELETE.
The class implements the buffer and the connection to the XO framework. As this class also needs to reset its
buffers at the end of a transaction, it also implements the transaction control interfaces <MLB>IF_TC_CLIENT.
The XO Layer transforms the data into DB representations. It takes care of creating, deleting, updating and
reading entries in the PROT database tables. The PROT-specific XO implementation classes inherit from
XO_BUSINESS_OBJECT and are registered in the PROT-specific XO customizing. The transaction handling is
done by a common XO transaction controller (<MLB>CL_XO_TC), which implements the transaction control
client interface. At end of a transaction, the controller calls the corresponding XO framework methods to save
or reset data.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 60
6.2.2.1 API for PRO
Apart from the generic API design described in section 6.2.2 this section describes the most important
specifics of the PRO API. A detailed view is shown in Figure 6-5:
Figure 6-5: Specific Details of the PRO API - Static View
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 61
The API interface <MLB>IF_PRO_API offers all methods to manage the instance data of a PRO and its nodes.
Helpers are used on all levels of the API stack:
The object layer is responsible for the handling of the change state ID. For this purpose it uses the Change State
Helper interface <MLB>IF_CS_HLP. The Change State Helper provides methods to track an object for
subsequent changes (TRACK_OBJECT) and to retrieve a new change state ID whenever necessary. The method
GET_CHANGE_STATE_ID will return the old change state ID if there has not been a change. The method
CREATE_CHANGE_STATE_ID unconditionally returns a new ID for example when a new object is created.
However, per LUW only one new change state ID is drawn for each PRO instance.
Raising Events: As soon as the instance data or the status changes and event is raised. This is realized by the
implementation of the event interface <MLB>IF_EVT.
In order to implement the search feature of the PRO API provides the method FIND_BY_ADMV_PRO. The actual
processing logic is not done by the XO framework but forwarded to the Query Helper <MLB>IF_QRY_HLP, which
selects the PRO instances directly from the database <MLB>_SR.
6.2.2.2 API for PRON
Apart from the generic API design described in section 6.2.2.1, there is one important aspect of the PRON API
that is worth knowing:
As shown in Figure 6-6, there is one class implementation for each PRON type. This is indicated by the
placeholder <PRON>. All PRON implementations share the same interface <MLB>IF_PRON_API. The PRON API
operates on database table <MLB>_PP.
Figure 6-6: PRON API - Static View
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 62
6.2.2.3 API for Selection Parameters
The selection parameters that are provided when calling service operations StartExecution, RestartExecution
and Refresh are stored in a separate DB as they are not part of the response view of the PRO.
The selection API provides methods to manage the selection criteria for each node type. A static view is shown
in Figure 6-7:
Figure 6-7: Selection API - Static View
It provides the following methods:
CREATE: To create the selection criteria for all node types. This method operates on the type “PRO
selection total” that includes the selection criteria of the PRO as well as for each PRON type.
UPDATE: To update the selection criteria for a given PRON type. This method operates on the selection
complete type of the PRON type
READ: To read the selection criteria of the PRO as well as for all PRON types. Similar to the method
CREATE, the method READ operates on the type “PRO selection total”.
READ_BY_NODE_TYPE: Reads selection criteria for a specific PRON type
DELETE: Deletes all selection criteria of a PRO instance including root node and all PRON types
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 63
6.2.2.4 Node Type Status
As shown in Figure 4-2 statuses are also calculated on node type level to indicate if the selection is already
finished or still running. This status is kept in a separate data base table as it is not directly allocated to an
instance in the instance data base.
The Node Type Status API (NTS API) provides methods to manage the status for each node type of a PRO
(including the overall status on root node level).
A static view on the NTS API is shown in Figure 6-8:
Figure 6-8: Node Type Status API - Static View
It provides the following methods:
CREATE: To create node type status information for each node type
READ: To read all node type status for a given PRO UUID
UPDATE: To update the status of a given node type
DELETE: To delete the status of a given node type
In addition, the internal API interface provides the following methods
SET_PRIVATE_STATUS: To set the private status of a node type
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 64
6.2.2.5 Read Access Data
Read access data contains the last read access timestamp. This information is necessary to determine whether
a PRO can be deleted as there was no read access for a certain period of time.
The Read Access Data API (RAD API) provides methods to manage this information on node instance level of a
PRO.
A static view on the Read Access Data API is shown in Figure 6-9:
Figure 6-9: Read Access Data API - Static View
The object layer buffers the data, passes the data to the persistency and is registered at transaction control to
clear buffer at the end of a transaction.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 65
6.2.2.6 Version API
In order to be able to reconstruct the complete history of a PRO instance, a complete image of the instance is
written to the version database. The data from the version database is also used for change pointers and,
consequently, for sending the information messages.
Figure 6-10 shows a static view of the versioning functionality:
Figure 6-10: Versioning – Static View
The Action Class <MLB>CL_ACT_VERS plays a major role in versioning. It implements several interfaces exposed
to different users. As an action, it implements the action interface <MLB>IF_ACT. The action is registered on
changes and status changes of PRO and PRONs. If such an event occurs, the action class buffers this
information.
A version is written each time the method WRITE_VERSION of the Version Controller <MLB>IF_VERS_CTL is
called. This interface is exposed to the application facade, which calls the method WRITE_VERSION at the end
of the call sequence of a changing service operation. The version information is built by the Total Helper. This
helper builds the "PRO Total" structure, which consists of the PRO instance data with all its PRON instances,
including private administrative data. The action class writes the data to the database <MLB>_VS using the
Version API <MLB>IF_VERS_API.
There must be a version trigger, as the information about the PROT Service, the back-end service or background
processing is a vital part of the version information. The Version Trigger interface is exposed to all possible
channels (PROT/back-end service implementation and RFCs). The trigger can only be set once per LUW.
6.2.3 Phase Handling
The processing of a PROT can be divided into the two phases Fetch and Complete.
The execution of both phases is triggered by service operations the StartExecution, RestartExecution, and
Refresh.
Chapter 7 contains further details on the phase implementation from a code slot implementer’s point of view.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 66
6.2.3.1 Phase Execution
Both phases are triggered in a sequence which means all the services execute both phases at once while the
Complete phase is started as soon as the Fetch phase is finished for all nodes defined. The Complete phase is
only triggered for node instances which have been created during Fetch phase and the instances are if possible
processed in parallel.
All tasks are executed via RFC. As all changes to the PRO have to be committed to the database in case of
success or have to be rolled back in case of errors, the RFC implementation holds references to the transaction
control mechanisms to save or reset all registered clients and to perform the final commit or rollback. The RFC
implementation delegates the execution of a task to the Phase Helper.
The Phase Helper Class does what is necessary to execute a task. It calls the required APIs and helpers to update
PRO and PRON data, calculates and sets status information and calls the phase implementation to execute the
code-slots.
The relation between Phase Helper and Phase Implementation is shown in more detail in Figure 6-11:
Figure 6-11: Relation between Phase Helper and Phase Implementation
The Phase Helper <MLB>CL_PHSH holds references to the PRON-specific phase class via the generic phase
interface <MLB>IF_PHS. The phase class delegates to the PRON Phase Implementation, which contains the
code slots for back-end service execution. If back-end services are defined for the phase, these services are
provided by the Back-End Service Provider and can be used by the Phase Implementation. In all code slots, the
Phase Helper can be used to access other PRONs.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 67
6.2.3.2 Fetch
The call sequence for a fetch task is shown in Figure 6-12:
Figure 6-12: Call Sequence for Fetch Phase
First, the RFC calls the Phase Helper for task execution. As the data is transmitted via RFC as a compressed
string, the Phase Helper first decompresses the data. As the data contains the task details containing task type
and node type, the Phase Helper calls the corresponding method for task execution, which is the method
EXECUTE_FETCH_PHASE in this case.
First, the existing PRON instances are read from the PRON API as they are passed to the phase class later. In a
next step, the selection criteria are read using the Selection API. The selection criteria from the PRO and the
relevant PRON are read by using method READ_BY_NODE_TYPE. The method FETCH of the Phase Class is called
which forwards the call to the Phase Implementation Class where the code-slots are executed. Based on the
result from the Phase Implementation Class the Phase Class determines which node instances are to be
created, updated and deleted. In addition to that the result from the code-slot is mapped to the corresponding
complete type of the node type. This is necessary, because the Phase Implementation Helper is not operating
on the complete type, but on a subset of this type, as not all details of the complete type should be exposed to
the code-slot implementer.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 68
6.2.3.3 Complete
The sequence for the Complete phase follows the same pattern as the Fetch phase: The Phase Helper prepares
the data, calls the Phase Class and updates the PRON instances based on the result and returns the compressed
result data to the RFC. As the result the EXECUTE_COMPLETE_PHASE method returns the same PRON UUIDs as
have been passed to the method. PRON instances which were deleted or created during the Complete phase
are not reflected in the result. The reason for that is the Iterator which controls the instances sent into the
Complete phase. It has to set every instance which was sent to the Complete phase to complete. New or deleted
instances do not matter here. The call sequence is shown in Figure 6-13:
Figure 6-13: Call Sequence for Complete Phase
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 69
6.2.3.4 Parallelization
One of the key capabilities of a PROT is the asynchronous, parallelized retrieval of data. From the service
consumer point of view, the services for Start, Restart and Refresh deliver an immediate response. The actual
data retrieval is performed asynchronously in background by an RFC. Within this RFC, the data retrieval is
performed in a parallelized fashion while taking the dependencies between node types into account.
Figure 6-14 shows a rough overview of the parallelization implementation:
Figure 6-14: Parallelization Implementation - Static View
The scheduler handles the processing of new tasks and makes sure that the system environment for parallel
processing is initialized and enough free processes are available. It implements appropriate waiting
mechanisms in case no processes are available or no new tasks are waiting for execution. The Scheduler class
uses the task handler to retrieve the next available tasks. For the execution of the tasks the Scheduler class uses
the task runner.
The task handler manages a list of all open and running tasks. It is responsible to keep track of the task status
(Completed or Failed) and provides the next executable tasks. The task handler uses two iterators (for Fetch
and Complete phase). These iterators deliver the node types in the right order according to their defined
dependencies.
The runner is responsible for the actual task execution. It uses an RFC to execute tasks asynchronously in a
separate session. As soon as an RFC has finished a task, the runner informs about the task completion via an
event.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 70
Figure 6-15 makes the different areas of processing even more visible:
Figure 6-15: Different Areas of Processing Decoupled by RFCs
The parallelization implementation is called by the application façade via RFC. The parallelization
implementation itself also uses an RFC for task execution in background. These RFCs separate the processing
of a PROT instance into three different sessions:
1. The consumer session of the Application Façade (green): The Application Façade triggers the parallel
processing in background by calling the scheduler via RFC. The service consumer gets an immediate
response.
2. Scheduler/Task Handler/Runner (yellow): Within this session the actual execution logic and
scheduling takes place. There must be only one process for each PROT instance. From this process
other processes are opened in parallel for task execution.
3. Phase Helper (orange): The phase helper executes tasks and is always called in a separate session via
RFC from the Runner Class.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 71
6.3 Communication Layers
The service implementation layers (Figure 6-16) are primarily responsible to connect the PROT application logic
to external components via enterprise service interfaces.
Figure 6-16: Service Implementation Layers
A PROT provides services that are called by external consumers. All the services provided by a PROT are generated into ESR by PROB. PROB also generates the implementation for these services. To get information about changes to business objects related to PRONs a PROT handles information and notifications send from the back end. In addition to providing services, a PROT also consumes services of the back ends during the PROT phase implementation. PROB also generates the ESR artifacts and the corresponding implementation for outbound service consumers for back-end services, and it generates the Event Provider service interface (to inform of the status changes of a PROT to any interested listener applications) and ABAP Channels (to inform of status changes of a PROT and status changes of a node type of a PROT to any interested listener based on WebSocket protocol). The following sections provide the details of the PROT inbound and outbound communication.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 72
6.3.1 Inbound Communication
Figure 6-17 shows the standardized service interfaces and operations that are provided by a PROT:
Figure 6-17: Overview of the Services Provided by a PROT
Except the interface <PersistentRetrievalObject>Event<Version>Out all the interfaces contain
synchronous service operations. The design of the service implementation for these kinds of services is
described in detail in section 6.3.1.1.
Besides the synchronous PROT standard services, a PROT might contain several back-end related
asynchronous inbound services to handle information and notification messages from the back-end. The
service implementation design is described in detail in section 6.3.1.2.
Query<PersistentRetrievalObject><Version>In
+ <<service interface>> Find<PersistentRetrievalObject>ResponseByAdmministrativeData ()
<PersistentRetrievalObject>Event<Version>Out
+ <<event>> InformOf<PersistentRetrievalObject>ResponseExpiration ()
Manage<PersistentRetrievalObject><Version>In
+
+
+
+
<<service interface>>
<<service interface>>
<<service interface>>
<<service interface>>
ReadResponse ()
RetrieveResponse<PRONT> ()
ReadResponse<PRON> ()
Cancel ()
<PersistentRetrievalObject><Version>ActionIn
+
+
+
+
<<service interface>>
<<service interface>>
<<service interface>>
<<service interface>>
StartExecution ()
RestartExecution ()
Refresh ()
AbortExecution ()
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 73
6.3.1.1 PROT Inbound Services (Synchronous)
Figure 6-18 shows a static view on a standard synchronous PROT inbound service implementation:
Figure 6-18: PROT Standard Synchronous Inbound Service Implementation - Static View
The service implementation shown here is a changing service that follows the request/confirmation pattern.
PROB generates one service implementation interface (and the implementing class) for each service operation.
The PROT Service Implementation is directly instantiated by the SPROXY Class.
The PROT Service Implementation covers the following aspects:
Transaction control, which means that the final transaction end event is triggered by the PROT Service
Implementation.
This is supported by using the transaction control interface from FSL, which is implemented twice: One
implementation for RESET/ROLLBACK and one implementation for SAVE/COMMIT.
Idempotency to support exactly one execution of messages in case the same message is sent twice. This
is supported by the IDP Services Helper from FSL.
Execution of the PROT application logic using the Application Façade.
Setting the version information using the Version Trigger.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 74
The call sequence is shown in Figure 6-19:
Figure 6-19: PROT Standard Synchronous Inbound Service (Request/Confirmation) – Call Sequence
The execution of the service implementation is triggered by the PROT Inbound Proxy by calling the interface
method EXECUTE of the PROT Service Implementation.
The method PREPARE checks whether or not the request has already been processed. If it has, the response for
the already processed request is returned and the processing is finished. If the request has not yet been
processed, the execution of the service implementation continues as follows:
First, the inbound request is validated to make sure that the data is plausible and fulfils the service contract. The
inbound request is then mapped from the external representation (generated by SPROXY) to the internal DDIC
representation based on which the Application Façade is called.
After the execution of the Application Facade, the response data is mapped from the internal DDIC structure
back to the external representation (generated by SPROXY).
Finally, the FINALIZE method stores the UUID of the request (taken from the message header) together with
the corresponding response message. All changes are committed via the FSL transaction control interface.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 75
Note that transaction control, idempotency, and versioning are not required for read-only service operations
(query/response pattern).
6.3.1.2 PROT Inbound Services (Asynchronous)
In addition to the standard synchronous PROT inbound service, a PROT must also implement the inbound side
for the asynchronous messages that are sent by the back ends in order to inform PRO instance(s) about
changes to the assigned back-end business objects.
Figure 6-20 shows a static view of the back-end related asynchronous inbound service implementation:
Figure 6-20: Back-End Related Asynchronous Inbound Service Implementation – Static View
The PROT Service Implementation covers the following aspects:
Transaction Control
In contrast to synchronous inbound services, the final commit or rollback is triggered by the WS runtime in
the asynchronous case and the service implementation is forbidden to call COMMIT WORK or ROLLBACK
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 76
WORK at all. Therefore, the local classes for transaction control only call RESET or SAVE from the POL
transaction interface.
Error Handling
For error handling the Service Implementation Class implements interface IF_ECH_ACTION to act as a
callback for ECH and uses the interface IF_ECH_EXECUTION to put erroneous messages to ECH
The call sequence for the processing of a back-end related asynchronous inbound service is shown in Figure
6-21:
Figure 6-21: Back-End Related Asynchronous Inbound Service Implementation – Call Sequence (Success)
First, the inbound request is validated to make sure that the data is plausible and fulfills the service contract.
The inbound request is then mapped from the external to the internal representation. After validation and
mapping the version trigger is set to BACKEND_SERVICE and the ECH Façade is instantiated with the service
operation specific parameters.
For the actual service execution, the following steps are executed for all request messages: First all provider IDs
are extracted from the Provider ID Provider, converted, and handed over to the Expiry Helper. Finally, the
transaction control takes care that the SAVE method is called for all registered TC clients. The “commit work”
is done by the WS-runtime.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 77
6.3.2 Outbound Communication
The following section focus on the design of the back-end-related outbound services.
The latter section elaborates on ABAP Channels.
6.3.2.1 Back-End Outbound Services (Synchronous)
The outbound services of a PROT are the counterparts of the consumed back-end services. As only synchronous
back-end services can be consumed, the PROT counterparts are of course synchronous as well.
The static view on a back-end related outbound service is shown in Figure 6-22:
Figure 6-22: Back-End-Related Synchronous Outbound Service Implementation – Static View
In the outbound case, the service gatekeepers are the central point of entry for all service implementations.
There is one gatekeeper for each ESR outbound service interface. The gatekeeper holds references to all service
implementation classes. As with the inbound case, there is one service implementation interface (and a
corresponding implementing class) for each service operation.
The Service Implementation Class uses the FSL Logical Port Helper for the determination of logical ports that
are required for the instantiation of the back-end facing Outbound Proxy. The logical port is calculated based on
the information transmitted in the message header of the request message.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 78
The execution of a synchronous back-end-related outbound service is shown in Figure 6-23:
Figure 6-23: Back-End-Related Synchronous Outbound Service Implementation - Call Sequence
The consumer calls the EXECUTE method of the service outbound implementation interface. The implementing
class performs a validation and maps the data from internal to external SPROXY representations.
The logical port helper from FSL is used to determine the logical port out of the information of the message
header. This logical port is used to instantiate the Outbound PROXY.
After the corresponding operation of the Outbound Proxy has been called the response message is mapped
from the SPROXY representation to the internal representation and is then returned to the consumer.
6.3.2.2 PROT Event Channels
Based on the WebSocket protocol the following channels inform about changes of a PROT:
/nodeinstancestatuschanged – Informs about status changes of the PROT instance and its node
instances
/nodetypestatuschanged – Informs about status changes of a node type of the PROT instance
In order to register to a push channel the following URL parameters are defined:
pro_uuid – UUID of the PROT instance (mandatory)
bindings – Channels to be informed about (optional). If the bindings parameter is not submitted,
information about all channels are transmitted.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 79
The events are transmitted in JSON format. An event consists of the event data as well as on metadata.
Events of the channel “/nodeinstancestatuschanged” have the following format:
{
"EVENT":{
"PRO_UUID":"<uuid in char 36 format>",
"UUID":"<uuid in char 36 format>",
“REFERENCE_ID”: “<reference id in GDT format>”,
“PROVIDER_ID”: “<provider id in GDT format>”,
"NODE_TYPE":"<scalar value of node type>",
"FROM_STATUS":"<scalar value of status code>",
"TO_STATUS":"<scalar value of status code>",
"TIMESTAMP":"<timestamp in GDT format>"
},
"METADATA":{
"APPLICATION_ID":"<name of ABAP messaging channel application of PROT>",
"CHANNEL_ID":"/nodeinstancechanged",
"NODE_TYPE":"<scalar value of node type>",
}
}
The field “PROVIDER_ID” is only transmitted in case of a node instance, for the PROT instance the field is not
transmitted.
Events of the channel “/nodetypestatuschanged” have the following format:
{
"EVENT":{
"PRO_UUID":"<uuid in char 36 format>",
"UUID":"<uuid in char 36 format>",
"NODE_TYPE":"<scalar value of node type>",
"FROM_STATUS":"<scalar value of status code>",
"TO_STATUS":"<scalar value of status code>",
"TIMESTAMP":"<timestamp in GDT format>"
},
"METADATA":{
"APPLICATION_ID":"<name of ABAP messaging channel application of PROT>",
"CHANNEL_ID":"/nodeinstancestatuschanged ",
"NODE_TYPE":"<scalar value of node type>",
}
}
The transmission of the events is based on the Event Handling of the PROT (see chapter 6.4.6) and the
transaction control of the PROT (see chapter 6.4.1). The events are transmitted only in case of COMMIT
WORK.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 80
Figure 6-24 shows a static view on ABAP channel of a PROT:
Figure 6-24: ABAP Channel - static view
The action class <MLB>CL_ACT_AMC collects the changes to be sent out as messages and hands the
collected messages over to the ABAP Messaging Channel <MLB>AMC_EVT.
The binding class <MLB>CL_APC_BND creates the connection between the messaging channel and
interested parties that have connected to the Push Channel <MLB>APC_EVT.
6.3.3 Find Service
A user might want to search for instances of a PROT that meet certain criteria, e.g.
Instances that are in status Running Instances for account 4711 that are in status Erroneous
The Find service enables a user to execute such queries. It offers the possibility to search for PRO IDs by
administrative data of PROs and PRONs. For PROs the following selection criteria can be specified:
Reference ID Business Process Chain Assignment UUID ( all PROs that are part of a specific business process) Business Process Chain Assignment Type Code ( all PROs that are part of a specific type of business
process)
Status ( all PROs that are in a certain status)
For PRONs the following administrative data can be specified:
Reference ID Provider ID ( all PROs that comprise the specified PRONs) PRONT Aggregated Status ( all PROs that comprise PRONTs in a certain aggregated status) PRON Status ( all PROs that comprise PRONs in a certain status)
If multiple attributes are defined within one entry all criteria have to be fulfilled (AND). In case of multiple
selection entries one of these entries needs to be fulfilled (OR).
The result of a query can be limited by specifying Processing Conditions. Especially for queries where the result
set is expected to be very big, processing conditions can be used by the consumer to request the result set bit
by bit, which significantly improves performance and makes the result set more manageable.
Besides, a query to the service can be identified via a SenderTechnicalID, which makes it possible to relate a
result to the corresponding query.
The PRO API contains a method FIND_BY_ADMV_PRO. Calls to this method are forwarded to the PRO Object
Layer and the PRO Persistency Class. The PRO Persistency Class uses a query helper that executes the search
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 81
query on a separate database. This database contains all elements that are relevant for search queries and
defines indices to ensure good performance.
The existing XO classes for the PRO and PRONs “mirror” the relevant data to the search database.
Figure 6-25: Query Helper - Static View
The Query Helper is responsible to build the where clauses from the selection criteria and performs the select
on the database tables. A query to the Find API consists of one or more selections, each of which contains
elements to specify administrative data of PRO and PRONs. The elements inside one selection are logically
concatenated by the AND operator, multiple selection instances are concatenated with the OR operator.
For building the where clauses the Query Helper uses a local helper interface LIF_WHERE_CLAUSE.
For the database selects the Query Helper uses the local helper interface LIF_SELECTION_HELPER. Each
WHERE clause is an object to conveniently add conditions All WHERE clauses of one selection are ordered by
their selectivity, i.e. their impact on reducing the result set.
The Query Helper uses two instances of the selection helper, as data is selected from two databases, the search
database (<MLB>SR) and the node type status database (<MLB>_PS).
In order to manage the response processing conditions of a search query (are based on the GDT
ResponseProcessingConditions), the processing conditions helper is used that is implemented as a local class.
It supports paging, so it calculates the number of results to be returned, the last returned PRO ID and reveals
whether or not more search results are available.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 82
6.4 General Concepts
With the background information on the artifacts that are generated by PROB for the PROT implementation, it
is useful to understand how the PROT implementation handles key concerns like status handling, expiration,
and so on. Concepts for the implementation of custom code slots in PROT will be described in detail in chapter
7.
6.4.1 Transaction Control
In order to ensure proper transaction handling for a PROT instance and a uniform behavior of all runtime
artifacts, a central transaction control functionality is generated for each PROT.
Proper transaction handling means:
Nothing is persisted unless the SAVE method is called.
At the end of a transaction, all PROT-instance-related buffers are empty.
Figure 6-26 shows a static view of the PROT transaction control:
Figure 6-26: PROT Transaction Control – Static View
All classes of PROT that need to connect to transaction handling, implement the client interface
<MLB>IF_TC_CLIENT. These clients are registered with the transaction controller <MLB>CL_TC. This
registration is usually done by the factory that is in charge of instantiating the client class.
When a transaction is finalized, the channel that is in charge of the transaction handling must decide whether a
SAVE or a RESET is needed (depending on the status of the transaction) and communicate this decision to the
PROT runtime transaction control interface <MLB>IF_TC. The transaction controller then forwards this call to
all its registered clients.
Note that the transaction control class neither calls COMMIT WORK nor ROLLBACK WORK. This has to be done by
the channel, e.g. the PROT service implementation that executes the request of a service consumer.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 83
6.4.2 Exceptions and Message Classes
Each PROT instance might find itself in an error situation. Depending on the situation, the PROT instance might
need to raise an exception to enable the surrounding code to do the error handling. There are three main groups
of error situations and each must be handled differently:
Coding errors that violate the assumptions of a called method will be uncovered via ASSERT statements
and most often have to be fixed by developers.
Error situations that occur in the generated part of the source code (“PROT framework”) will automatically
be handled by the framework.
Errors that arise from custom implementations might be handled by the PROT framework source code.
However, in most cases these errors have to be handled in a different way from framework-inherent errors.
This classification is the basis for the exception handling concept in the PROT design. The exception hierarchy
is shown in Figure 6-27:
Figure 6-27: PROT Exception Hierarchy – Static View
A central PROT exception class <MLB>CX_GEN is generated for all static checks. This class inherits from
CX_STATIC_CHECK. All other static check exception classes of the PROT inherit from this class. All classes have
a number of text IDs that are used for different error situations. The messages for the text IDs are taken from
the message class <MLB>EX_FW.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 84
The following exception classes are used:
<MLB>CX_IM for errors in custom implementations
Implementation-related exceptions (e.g. during the implementation of code slots) should be derived from
class <MLB>CX_IM. Customer-specific exceptions should also be defined as subclasses of this class.
<MLB>CX_STD_IM for standard exceptions that occur in custom implementations
<MLB>CX_PAR_PROC for exceptions that occur in parallelization
6.4.3 Instance Management
Object instance management is based on the following basic principles:
Each package with users has a package interface (see chapter 5.2.1).
There is one (and only one) dedicated class (called Gatekeeper or Factory), which is exposed at the
package interface and is responsible to provide instances of all other objects of this package
The instance-providing-methods of this dedicated class are encapsulated by an interface.
Beside this dedicated class, only interfaces are exposed at the package interface (with the exception of
enumeration classes)
Gatekeepers & factories are implemented as singletons (the static method is called GET_INSTANCE); all
other classes offer CREATE-methods that provide a new instance for each call (with the exceptions of
enumeration classes, exception classes and SPROXY generated classes)
This means that instance management, buffering of instances, lazy objects instantiation, etc. is done by
the gatekeepers & factories only.
The returning parameters of all create/instance-providing methods are references to an interface (REF TO
<MLB>IF).
6.4.4 Status Handling
The status concept of a PROT has already been introduced in section 4.3:
Each PRO instance has a defined aggregated status, which depends on the status of the individual node types
(PRONTs), which again depend on the status on node level (PRONs), as well as on the private status of the node
type root itself. Each of these statuses can be changed by executing a service operation on a PRON or the PRO
itself or while the PRO is running. Therefore, the overall status of the PRO must be calculated each time a service
operation on a PRON or the PRO is executed. To facilitate the calculation of the overall status of a PRO instance,
the design of PROT incorporates the concept of a private status (Figure 6-28). The private status attribute is
part of the private administrative data of the PRONTs and is not exposed to the outside.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 85
Figure 6-28: Private Status of a PRO
The overall status of the PRO is calculated by the status calculator class (Figure 6-29). The calculation is based
on a decision matrix. The status calculator interface contains two methods that are used for different purposes:
CALCULATE_AGGR_PRO_STATUS calculates the overall status based on a table of statuses
CALCULATE_AGGR_NODE_TY_STATUS calculates the node type status based on a table of statuses
Figure 6-29: PROT Status Calculator – Static View
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 86
The calculation of aggregated status is done by the Status Calculator class. The status calculation is done by
using the “last man standing” algorithm, which works as follows:
When merging two status, we assume that one of these statuses wins, because of its higher impact on the overall
state. For example, the status Erroneous has a higher impact than the status Finished, because if at least one
PRON is erroneous, the aggregated status of the PRONT is erroneous as well. After having merged all statuses,
there is one "last man standing" which is set as the aggregated status.
The order of statuses is defined for the aggregated node type status and the overall PRO status in a different.
The class implements different interface methods for each purpose:
CALCULATE_AGGR_NODE_TY_STATUS
Calculates the (aggregated) status for a node type based on the statuses of all instances that belong to
this specific node type. The order is defined by the right pile in Figure 6-30.
CALCULATE_AGGR_PRO_STATUS
Calculates the (aggregated) overall status of the PRO based on the statuses of all node types. The order
is defined by the middle pile in Figure 6-30.
Figure 6-30: Order of Statuses for Overall Status Calculation
In order to have a good performance in calculation of the aggregated status, the comparison (which status wins)
between two statuses should be very fast. For this reason, a decision table is set up (see Table 6-2) based on
the left pile in Figure 6-30 that answers the question which state of two given states (A and B) is the winner when
the node type status is to be calculated.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 87
INTI
AL
WA
ITIN
G
RU
NN
ING
EXP
IRED
FIN
ISH
ED
ERR
ON
EOU
S
AB
OR
TED
1 INTIAL A X X X X X X
2 WAITING X A B A A A A
3 RUNNING X A A A A A A
4 EXPIRED X B B A A B B
5 FINISHED X B B B A B B
6 ERRONEOUS X B B A A A B
7 ABORTED X B B A A A A
Table 6-2: Decision Matrix for Status Aggregation for Node Type Status
The rows represent the status of node A while the columns represent the status of node B. The content of the
cells reveal whether the status of node A or node B is the winner. The X indicates that the comparison of these
statuses is not defined.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 88
6.4.5 Expiration
The retrieval date time reveals when a PRON instance has been retrieved/read for the last time. As the PRO with
all its PRON instances is only a view on one or more back-end business objects, an expiration mechanism is
required in order to define under which circumstances a PRON instance is considered to be expired.
The expiry of a node instance (or a node type) can be triggered either by a back-end information/notification
message that informs about the change of a BO instance or based on expiration rules.
6.4.5.1 Expiration Triggered by Back-End Service
If a back-end system sends an information message about the change of a back-end object, the respective
asynchronous inbound service from the PROT is called. This inbound service uses the Expiry Helper which does
the actual expiration of PRONs.
Figure 6-31: Expiry Helper for Asynchronous Inbound Services
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 89
The following sequence diagram Figure 6-32 shows the flow beginning from the inbound service implementation.
Figure 6-32: Expiration based on Asynchronous Inbound Services - Call Sequence
During the processing of the Inbound Service the Expiry Helper is called. At first all PRONs (and their PROs) which have to be expired have to be found based on the Provider IDs which the Provider ID Provider provides (based on a code slot). In a second code slot the list of PRONs to be expired can be further reduced. To do so the data of the PRONs which is passed to the code slot does not only contain the provider ID but also two dates:
The back-end modification date is set in the Provider ID Provider code slot and should indicate when
the back-end object has been actually changed
The Last Retrieval Date shows when the PROT has retrieved the object from the back end the last time.
Based on that, the PRONs status can be set to Expired using the PRON APIs. Before the status can be set the PRO has to be locked using the Enqueue Helper. If the lock fails, the PRO is returned back to the inbound service implementation and put into ECH. In case of RETRY via ECH the method EXPIRE_PRONs is called directly based on the information that was stored in ECH.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 90
6.4.5.2 Expiration Based on Rules
The expiration rules are defined within step 3 of the modeling wizard. The expiration rules can be defined
separately for each node type. The rules are divided into time based and relationship based rules (see Figure
6-33).
Time-Based Rules
A time-based rule indicates that a node instance expires after a certain amount of time has elapsed.
Time based rules can be defined on instance level as well as on node type level. Instance level means,
that the PRON instance itself expires. A time-based rule on node type level means, that the node type
expires, but not the instance. This is required for scenarios where single instances do not expire by
definition, but there are new instances expected after a specified amount of time (like posting items of
an account).
The concrete duration for instance and node type level expiry are obtained from a code-slot (that can be overruled by a BAdI implementation in customer scenarios).
Relationship-Based Rules
A relationship based rule for a node type can be used to express that an instance of this node type
should expire in case a related instance (successor or predecessor) expires. The relationship of two
node instances is defined by the element Predecessor that is part of PRON AdministrativeData. A
predecessor relation can be created in the Fetch phase (see 6.2.3.2) and is persisted along with the
PRON instance.
Figure 6-33: Expiration Rules Specified in Modeling Wizard
All time dependent rules are directly applied by the Time Dependency Expiration Helper (TDP Expiration Helper)
shown in Figure 6-34. The relationship rules are handled indirectly by actions (triggered by events).
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 91
Figure 6-34: Time Dependency Expiration Helper - Static View
The Time Dependency Expiration Helper checks for all node instances (for which time dependency is relevant)
whether they are expired or not.
In order to determine if an instance is expired, Time Dependency Expiration Helper uses the Time Dependency
Helper (TDP Helper) to get the durations for instance and node level expiry.
The TDP Helper gets this information from a code-slot within the Time Dependency Provider (located in the
package <MLB>_CUST). The duration from the code-slot can be overruled by a BAdI implementation that is
called by the TDP Helper (if implemented).
The subtraction of the duration from the current timestamp is done by the Time Helper.
The Time Dependency Expiration Helper uses the corresponding APIs (PRON API and NTS API) to set the status
to Expired.
As soon as a node type or a PRON instance is set to Expired by the Time Dependency Expiration Helper,
corresponding events (Status changed and NTS changed) are raised that inform about the status changes. This
leads to the execution of the following actions:
Expiration of Dependent PRONs: Sets all dependent PRON instances (according to the relationship
rules) for a given PRON instance to Expired. This leads to subsequent events that again change the
status of a PRON to Expired which again leads to subsequent events and so on.
Change Status of PRONT: Re-calculates and changes the status of a PRONT (after instance has been
expired)
Change Status of PRO: Re-calculates and changes the status of the PRO (after private NTS has been
expired)
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 92
A basic call sequence is shown in Figure 6-35:
Figure 6-35: Instance and Node Type Expiration - Basic Call Sequence
The Time Dependency Expiration Helper is called by the Application Façade. It is called before the processing
of the following operations is executed:
- Read
- Retrieve
- Find
- Refresh
- Restart
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 93
Figure 6-36 shows in more detail how the expiry timestamps are obtained:
Figure 6-36: Obtaining Expiration Timestamps - Call Sequence
The Time Dependency Expiration Helper loops over all PRONTs for which time based rules are defined. It obtains
the expiration timestamps (shown in separate diagram) using method GET_EXPIRY_TIMESTAMPS that returns
the timestamp for both, the instance level expiry and node type level expiry.
In a next step, the relevant PRON instances are selected, i.e. those in status Finished. All other statuses must
not be considered.
For each PRON instance the timestamp of last retrieval is read via method GET_RETRIEVAL_DATETIME from
the PRON API. Then, the expiration timestamps are compared with the last retrieval timestamp.
In case the PRON instance is expired, because the timestamp is “too old”, there are the following options:
- In case instance level expiry has been set for the corresponding node type, the status of the PRON
instance is set to Expired.
- In case node type level expiry has been set for the corresponding node type, the private status of the
node type is set instead.
In case of instance level expiry for a node type, the method GET_DURATION_FOR_NODE_INSTANCE is called.
In case of node type level expiry the method GET_DURATION_FOR_NODE_TYPE is called. Both methods return
a value based on GDT Duration.
This duration is subtracted from the current timestamp by using the time helper. First it subtracts month and
years using the FIMA API, then subtracts days, hours, minutes and seconds. The result is compared with the
last retrieval timestamp. If the result is older a PRON instance is considered as expired.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 94
6.4.6 Event Handling
One of the key architecture principles of a PROT is the decoupling by using events.
In general, this leads to a requirement for decoupling as the artifacts that undergo changes (or, in other words,
raise events) must not be forced to know all the other artifacts that are interested in and should react on the
event. This decoupling is achieved by event-based communication between the talkative (event-rising) artifacts
and the interested artifacts (listeners) using the mediator design pattern. The mediator is the “man in the
middle” that registers on all events of all talkative objects and forwards these events to interested parties.
Based on this pattern, the event handling in a PROT is implemented as follows.
Figure 6-37 shows a static view of the event raising.
Figure 6-37: Raising of Events - Static View
There are three different event interfaces:
Event Interface. This is the default event interface implemented by the object layer implementation
classes. Events of this interface are raised in case the status or the data of a PRO/PRON changes.
Runner Event Interface. This interface is used in the area of asynchronous parallel processing.
NTS Event Interface. This interface is implemented by the NTS object layer class. Events of this
interface are raised if the node type status or the private status of a node type changes.
In order to manage events in a controlled way instead of registering, firing, and catching them at will, the
mediator pattern comes into play. A static view is shown in Figure 6-38.
Each PRO/PRON can raise the events CHANGED (if the data contained in the Details or the Private Details has
changed) and STATUS_CHANGED (if the status of the sending instance has changed). Event handling will be
initialized by a central event listener, called Event Mediator.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 95
Figure 6-38: Event Mediator - Static View
The Event Mediator listens for events on all registered objects. After an event has found its way to the event
handler method of the mediator, there are some actions to be performed based on that event.
The concrete actions for a given event type are provided by Action Providers, which implement the interface
<MLB>IF_AP. Action providers can register at the event mediator, which will in turn ask the providers to provide
relevant actions for a specific event. Factories are responsible for registering the events and action providers
with the mediator.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 96
Figure 6-39 shows the raising of a STATUS_CHANGED event caused by changing the status of a PRON. In this
case the status is exemplarily changed by the Expiry Helper. It could also be changed by somebody else, e.g.
the Application Façade.
Figure 6-39: Status Change of a PRON Raises STATUS_CHANGED Event
The PRON API retrieves the current instance data form the object layer, updates the status, and persists the
new data via the DB layer. Then it raises a STATUS_CHANGED event.
This event is then handled by the Event Mediator, which executes all actions that are registered for this event.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 97
The call sequence is shown in Figure 6-40:
Figure 6-40: Registered Actions are Executed
First, the Event Mediator asks the currently registered Event Filter whether the event should be ignored (this is
the case during parallel processing in the Complete phase) or not. After that it retrieves all actions registered
for this event and executes them.
The example shows the Action for Expiration of Dependent PRONs, which is registered for this specific event.
It calls the Relation Helper to update all relevant relations. To do this, the Relation Helper first retrieves all
relations from the PRO API. It then converts the relations into a suitable format and buffers them. Hence,
method GET_RELATIONS_FOR_EXPIRY is only executed once. After that, the updated relations are given back
to the PRO API. Finally, all the status of all dependent PRONs are updated in a loop.
The change of a status of a dependent PRON in turn causes the raising of a STATUS_CHANGED event, and the
processing starts all over (at the Event Mediator) again.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 98
6.4.7 Predecessor Relations
The Node Predecessor/UUID as part of AdministrativeData specifies to which predecessor node
instances are related to. The element Predecessor contains the UUIDs of the node instances, where the
current node instance depends on (predecessor node). This means attribute values of the predecessor are used
to determine this node as a successor.
Figure 6-41: Predecessor Definition
The predecessor can be used as a selection criteria for the restart operation to specify to which predecessor
node instances the restart is related to. Based on the node type /node type instance it is possible to specify via
DependentNodesRefreshRequestedIndicator that successor nodes have to be refreshed too (all node
instances succeeding the current instance - "deep refresh"). This allows to refresh dependent node without
knowledge of the Predecessor UUID.
If the relationship-based expiration rule is selected (see also 6.4.5.2) then the predecessor relationship is also
used to set those instances to Expired which are predecessor or successor of the expired node instance.
6.4.8 CNS, OAF, and Information Messages
During the execution of a PROT events are raised to inform about the expiration of a PROT instance. These
events are published as information messages to the outside world. The information messages are not sent out
directly, but in order to decouple the occurrence of the event from sending the message the Change Notification
Service (CNS) and the Outbound Agent Framework (OAF) are used.
Figure 6-42 shows how the action class for status changed events is implemented:
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 99
Figure 6-42: CNS Action Class for Status Changed Event – Static View
The action class for CNS status change is involved whenever a PRO/PRON changes its status by implementing
the action interface <MLB>IF_ACT. The implementation of the TC client interface ensures that the buffer is
processed when it comes to commit or rollback. For writing change pointers it uses the CNS helper. In order to
enrich the change pointer with version information the method MAP_VERSION_INFO_TO_ADD_INFO attaches
the version information to the change pointer.
For push scenarios, the agent implementation is waiting for new change pointers:
Figure 6-43: OAF Agent Implementation – Static View
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 100
In order to do so, the OAF Agent Implementation <MLB>CL_OAF_EXI inherits from class CL_OAF_AGENT. In
addition, it is required to register and activate the agent in customizing. As the agent needs to reset some buffers
in case of error, it implements the transaction control interface. The change pointers carry along the information
which version of the PROT instance needs to be read. It requires the method
MAP_ADD_INFO_TO_VERSION_INFO of the CNS helper to extract this data and the version API to read the
corresponding version of the process object instance. This data is then passed to the corresponding service
implementation for sending out the information message.
Figure 6-44 shows the call sequence for an expiration event from the agent’s perspective:
Figure 6-44: Call Sequence for the Processing of Change Pointers by the OAF Agent
First the agent uses method MAP_ADD_INFO_TO_VERSION_INFO of the CNS helper to extract the version of
the PRO for which an information message is to be sent out. It uses the version API to read the corresponding
data (public total type) of this PRO version. Then, the agent maps the PRO total data to the service request. This
is done for all change pointers. After all information messages are filled, the service implementation is called for
each information message. The service implementation then sends out the expiry information message to the
configured receiver(s). In case of (non-technical) errors an exception is raised and the agent framework sets
the change pointer processing status to Failed.
6.4.9 Deletion
Each PROT provides a report that can be used to delete PRO instances by different selection criteria. The
following selection parameters can be specified:
Retrieval Date Time: Selects all PRO instances with PRONs that are older than a given timeframe.
Last Access Date Time: Selects all PRO instances that have not been read for a given timeframe
Provider ID: Selects all PRO instances that contain PRONs with a given Provider ID
The selection by time frame is intended for scenarios where a report is scheduled deleting all instances that are
out of date. The selection by Provider ID is more intended for scenarios where PRO instances are to be deleted
that contain data of a specific back-end BO, e.g. a business partner.
All selection parameters are linked with AND. If an OR link is required, the report has to be executed multiple
times.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Detailed Design
PUBLIC
© 2017 SAP SE. All rights reserved. 101
An overall call sequence is shown in Figure 6-45. It does not cover all aspects of the report but focuses on the
rough interaction of all actors.
Figure 6-45: Deletion of PRO Instances – Call Sequence
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 102
7 PROT Implementation
The Persistent Retrieval Object Builder generates most of the parts that a persistent retrieval object type
consists of. Once a PROT has been generated completely, a PROT developer can implement custom logic in
dedicated places.
This chapter explains what has to be done to complete a PROT implementation. We assume that you are already
familiar with the sample business scenario (see section 2.5) and the high-level and the detailed design of a PROT,
especially with phase and status handling (see sections 6.2.3 and 6.4.4).
7.1 Custom Phase Implementation
This section explains how a developer implements the code slots for the phases. It first discusses basic
principles and afterwards provides details for each phase implementation.
7.1.1 Conventions and Disclaimers
The following sections contain source code examples (listings) that are used to illustrate how to implement the
code slots of the phase implementation. The prefix for all artifacts is /PL9/<...>_STXX_F01_.
Usually, PROT developers add their own methods to the code slot classes in order to structure the code slots.
However, to improve conciseness, the code samples in this guide do not contain any additional methods.
Moreover, exception handling should normally take place at the end of a code slot, i.e. all logic is embraced by
the try-catch-block. However, the code samples in this guide keep the try-catch-block as short as possible to
avoid unnecessary line breaks.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 103
The following listing shows a small sample excerpt:
* common prefix for all artifacts: /pl9/<...>_stxx_f01_
data: lr_pron type ref to /pl9/if_stxx_f01_n_flgt_pimpl=>ts_complete ##needed.
field-symbols: <ls_start_request> type /pl9/ptxxsflight_search_fs_p72 ##needed,
<ls_restart_request> type /pl9/ptxxsflight_search_fs_p63 ##needed,
<ls_refresh_request> type /pl9/ptxxsflight_search_fs_p10 ##needed.
try.
... "something has been omitted here
case i_operation_type.
when /pl9/ce_stxx_f01_op_ty=>start_execution_pro.
assign i_request_data to <ls_start_request>.
... "something has been omitted here
when //pl9/ce_stxx_f01_op_ty =>restart_execution_pro.
assign i_request_data to <ls_restart_request>.
... "something has been omitted here
when /pl9/ce_stxx_f01_op_ty=>refresh_pro.
assign i_request_data to <ls_refresh_request>.
... "something has been omitted here
when others.
assert 1 = 0.
endcase.
catch cx_fsl_internal_error.
* where exception handling should be
endtry.
Listing 7-1: Source Code Example
7.1.2 Goals of Phase Implementation
The main goal of the phase implementation of a PROT is to call the back-end services that were selected
during PROT modeling. In order to do this, the developer has to do the following in the corresponding code
slots:
Check the preconditions of the back-end services
Build the service requests (map from PRON parameters to service signatures)
Call the back-end service
Evaluate the service responses (map from service signature back to PRON representation, set PRON
status, handle errors and exceptions)
Depending on the phase this is done with different focuses (see section 4.5).
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 104
7.1.3 Basic Principles of Phase Implementation
All classes that contain code slots are located in the custom package (<MLB>CUST). The code slots for the
phases are contained in the phase implementation classes; there is one class for each PRON
(<MLB>CL_N_<PRON>_PIMPL).
These classes contain the following methods:
An INITIALIZE method to initialize additional attributes that are required for the phase implementation
Methods that correspond to the phases of a PROT:
<MLB>IF_N_<PRON>_PIMPL~COMPLETE
<MLB>IF_N_<PRON>_PIMPL~FETCH
Figure 7-1 gives an overview of the phase implementation and the related classes:
Figure 7-1: Phase Implementation
7.1.3.1 Custom Implementations
During the implementation of the code slots, a PROT developer can add attributes and methods to the phase
implementation classes to structure the implementation. Just like the code slots themselves, additional
attributes and methods do not get lost when a PROT is regenerated.
In addition, PROT developers can create their own classes and interfaces to be used by the code slot
implementations. In order to ensure that custom artifacts are not overwritten by the builder, these artifacts
must follow the naming convention <MLB>*_C_*, with C denoting a custom artifact.
Apart from classes and interfaces, typical examples for custom implementations are exceptions and message
classes (see section 7.1.3.3).
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 105
7.1.3.2 Access to Back-End Services
The importing parameter I_BACKEND_SERVICES provides the access to the back-end services of the node and
phase that were selected for a specific PRON. This parameter is available in the code slots. It is a structured type
and contains one entry for each service operation. The entries are references to the implementations of the
back-end service counterparts and follow the naming convention <service interface abbreviation>_<service
operation abbreviation>. A PROT developer only needs to call the EXECUTE method of the referenced
implementation to execute a back-end service.
7.1.3.3 Error Handling
A PROT developer has two options for handling errors in the code slots: Raise an exception or add an error
message to the log.
Business errors should be returned as log messages, whereas situations that require an immediate abortion of
the code slot should be handled via an exception. The procedure for returning error messages through the log
is identical for all phases:
Set the node status to Erroneous based e.g. on the value of the result code (or its equivalent in case of non-
standard services) returned by the back-end service
Add error messages from the back-end service to the provider log
Exceptions can be raised using the generated standard exception class (<MLB>CX_STD_IM), or a custom
subclass of the generated implementation exception class (<MLB>CX_IM). The custom subclass must be
created manually and should be the preferred way to raise custom exceptions. As the creation of the
implementation exception class is private, the statement RAISE EXCEPTION TYPE is not possible, as it
implicitly calls the constructor of the class. Instead, public static CREATE and RAISE methods have to be created
for the subclass. Figure 7-2 illustrates the general pattern for raising exceptions:
Figure 7-2: POL-specific Pattern for Raising Exceptions
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 106
When an exception is raised during code slot execution, the execution of the code slot is aborted. The exception
will be caught in the service implementation from which the code slot had originally been called (e.g. the
StartExecution service). In this implementation, the error messages from the exception are transferred to
the service log and the result code is set to Failed.
Example 1: Fill Provider Log
Listing 7-2 gives an example for how to use the log helper to add error messages that have been received from
a back-end service to the provider log:
data: lr_pron type ref to /pl9/if_stxx_f01_n_flgt_pimpl=>ts_fetch ##needed.
case i_operation_type.
when /pl9/ce_stxx_f01_op_ty=>start_execution_pro.
...
if ( ce_fsl_proc_result_code=>s_get_instance(
ls_flqo_qry_response-log-bus_doc_processing_result_code ) =
ce_fsl_proc_result_code=>successful ).
...
else.
lr_pron->public_admin_data-provider_log = ls_flqo_qry_response-log
lr_pron->public_admin_data-status_code =
/pl9/ce_stxx_f01_node_sts=>erroneous->get_int_value( ).
endif.
...
endcase.
Listing 7-2: Transferring Back-End Errors to the Provider Log
In case the back-end service could not be executed successfully (business document processing result code <>
Successful), the provider log (contained in the public administrative data) is filled with the log that is returned
by the back end.
Example 2: Raise Custom Exception
Listing 7-3 shows an example for raising a custom exception. In this example the exception is due to an
unsupported operation code (see section 7.1.3.5 for details).
data: lr_pron type ref to /pl9/if_stxx_f01_n_flgt_pimpl=>ts_fetch ##needed.
* operation code
case i_operation_type.
...
when others.
/pl9/cx_stxx_f01_c_custom=>raise(
textid = /pl9/cx_stxx_fb01_c_custom=>unsupported_operation_code
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 107
code = i_operation_type->get_value( )
type = /pl9/ce_stxx_f01_node_ty_c=>flgt->get_name( ) ).
endcase.
Listing 7-3: Raising a Custom Exception
The custom exception is a subclass of the generated implementation exception. As its instantiation is private,
exceptions are raised via its public static RAISE method. If an instance of the exception is required without
raising the exception, the public static CREATE method can be used (not shown in this example).
7.1.3.4 Data Access in the Phase Implementation
The following Table 7-1 gives you an overview about what can be accessed or executed in the code slots of which
phase:
What Fetch Phase Complete Phase
Synchronous Service (Read) allowed allowed
Synchronous Service (Change) Not allowed Not allowed
Asynchronous Service Not allowed Not allowed
Details Available, Changeable Available, Changeable
Private Details Available, Changeable Available, Changeable
Provider ID (in Administrative Data) Available, Changeable Available
Provider Log Available, Changeable Available, Changeable
Other Nodes Available (only predecessor
nodes)
Available (only predecessor
nodes)
Table 7-1: Read and Write Accesses in the Phase Implementation
Caution
Although it is technically possible, we strongly recommend not to call any changing service. PROTs are
not designed to handle changing services. Please use Process Objects (POTs) in this case.
7.1.3.5 Important GDTs
The following table contains GDTs that are important during code slot implementation, together with a
description and a sort name that will be used throughout this document:
GDT Short
Name
Description
BusinessDocumentMessageHeader Message
header
Contains administrative information about a
service message. It is part of all standard
services from SAP.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 108
GDT Short
Name
Description
BasicBusinessDocumentMessageHeader Basic
message
header
Only contains identifying information about a
service message. It is part of some of the
services in the SAP Business Suite.
BusinessDocumentProcessingResultCode Result
code
Indicates whether or not a service call was
successful. It is part of all standard services
from SAP.
Log Log Contains messages that occur during
application processing (the log items)
together with a
BusinessDocumentProcessingResultCo
de and a MaximumLogItemSeverityCode.
Log_V1 Log New version of GDT Log
LogItemSeverityCode
Severity
Code
Indicates the severity of a log message (GDT
Log).
MaximumLogItemSeverityCode Maximum
severity
code
Denotes the highest severity of all messages
contained in a log.
Table 7-2: Important GDTs
7.1.3.6 Operation Type
The input parameter i_operation_type is provided in Fetch Phase to indicate which service operation is
triggering the fetch. The possible values of the parameter are defined in enumeration <MLB>CE_OP_TY. Only
operation types start_execution_pro, restart_execution_pro, refresh_pro are
supported.
7.1.4 Helpers for Phase Implementation
The PROT developer is provided with a number of helpers that can be used in the code slot implementations:
7.1.4.1 Phase Helper
The phase helper (<MLB>IF_PIMPL_HLP) provides access to PRO and PRON data. The helper is passed to the
code slots via importing parameter I_PIMPL_HELPER and offers the methods described in the following table.
Methods involving PRONs usually contain generic data types in their signatures, because every PRON has its
own specific type. The descriptions below state the actual type for your convenience. For details on the used
data types see section 7.5.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 109
Method Name Description
GET_PRO Provides the complete data of the PRO including all PRONs
(<MLB>IF_IT_COMP=>TS_PRO_PUB_TOTAL).
DOES_PRON_EXIST Checks whether a PRON with the given UUID exists
GET_PRON_BY_UUID Provides the complete data of a PRON
(<MLB>IF_IT_COMP=>TS_PRON_<PRON>_COMPLETE) identified
by its UUID.
GET_NODE_TYPE_OF_PRON Provides the node type (<MLB>CE_NODE_TY_C) of a given PRON
Table 7-3: Methods of the Phase Helper
7.1.4.2 Log Helper
The log helper (<MLB>IF_LOG_HLP) provides convenience methods for handling internal and external
representations of the GDT Log resp. Log_V1. It is provided via the attribute MR_LOG_HELPER in the phase
implementation classes. The log helper is implemented locally by the FSL adapter class <MLB>CL_FSL_ADPT
and offers methods similar to the log helper of the Financial Services Library (FSL). In addition, it can merge two
logs into one.
Externally, the GDTs Log and Log_V1 are supported. Internally, the helper always uses the FSL representation
of Log_V1, which is FSL_STR_GDT_LOG_V1.
The log helpers contain the following methods:
Method Name Description
GET_LOG_BY_ECH_DATA Fills an internal log based on error information from ECH, taking the
provided result code into account. It can be used in methods for
ECH actions such as FINISH and FAIL for filling the log of the
confirmation message based on data provided by ECH.
Importing parameter I_ECH_DATA must be compatible to type
IF_FSL_LOG_FAULT_TYPES_CONS=>T_STR_ECH_DATA_STD.
GET_LOG_BY_MESSAGES Fills an internal log based on a table of BAPIRET2 messages, taking
the provided error category (if available) and the result code into
account.
Importing parameter I_MESSAGES must be compatible to
IF_FSL_LOG_FAULT_TYPES_CONS=>T_TAB_MSG_BAPI or
IF_FSL_LOG_FAULT_TYPES_CONS=>T_TAB_MSG_BAPI_WD.
GET_LOG_BY_SY Fills an internal log based on the provided system variable (SY),
taking the provided error category (if available) and result code into
account.
The method extracts the message ID, message type, and message
variables from the provided system variable.
Hint: The system variable can easily be filled with the desired error
message using the “MESSAGE…INTO“ statement.
GET_MESSAGES_BY_LOG Returns a list of messages, the severity code, and the result code
based on the provided internal log.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 110
Method Name Description
Exporting parameter E_MESSAGES must be compatible to
IF_FSL_LOG_FAULT_TYPES_CONS=>T_TAB_MSG_BAPI or
IF_FSL_LOG_FAULT_TYPES_CONS=>T_TAB_MSG_BAPI_WD.
CONVERT_GDT_LOG_TO_FSL_LOG
CONVERT_FSL_LOG_TO_GDT_LOG
These methods convert a given log from external to internal
representation and vice versa.
The expected external representations are the SPROXY types
generated for the GDTs Log and Log_V1.
Importing parameter I_GDT_TYPE of method
CONVERT_GDT_LOG_TO_FSL_LOG must be used to indicate
whether the provided log is of type Log or Log_V1.
CONVERT_FSL_LOG_TO_V1 Converts a given Log (internal representation) to Log_V1 (internal
representation).
The method also accepts Log_V1 as input. In this case it just
returns the given log. Thus, it is not necessary to check in advance
which type of log you are currently working with.
FILL_MIN_FSL_LOG Fills all the fields of an internal log that are required as a minimum
according to the provided result code.
The minimally required field is the business document processing
result code itself.
MERGE_LOGS Merges two internal logs, taking the severest result code and
severity code as new values.
Table 7-4: Methods of the Log Helper
For details on the result code and the severity code see section 7.1.3.5.
7.1.4.3 Message Helper
The FSL message helper (IF_FSL_MESSAGE_HELPER) offers convenience methods for filling BAPIRET2
messages and tables thereof from various input representations. It is provided via attribute
MR_MESSAGE_HELPER in the phase implementation classes.
The message helper contains the following methods:
Method Name Description
FILL_BAPIRET2_BY_APP_LOG_MSG Fills a BAPIRET2 message from the provided application log
message.
FILL_BAPIRETTAB_BY_APP_LOG_MSG Fills a table of BAPIRET2 messages from the provided table of
application log messages.
FILL_BAPIRET2_BY_MESSAGE Fills a BAPIRET2 message from the provided message details.
FILL_BAPIRET2_BY_SY Fills a BAPIRET2 message from the provided system variable.
FILL_BAPIRET2_BY_T100 Fills a BAPIRET2 message from the provided exception that
implements the IF_T100_MESSAGE interface, thereby taking
the provided message type into account.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 111
Method Name Description
FILL_BAPIRET2_BY_IF_MESSAGE This method fills a BAPIRET2 message from the provided
IF_MESSAGE message interface, thereby taking the provided
message type into account.
Note: If possible, use method FILL_BAPIRET2_BY_T100
instead, as it preserves the content of the original message
variables.
The base exception class CX_ROOT also implements the
IF_MESSAGE interface, but for exceptions method
FILL_BAPIRET2_BY_EXC should be used.
FILL_BAPIRET2_BY_EXC Fills a BAPIRET2 message from the provided exception, thereby
taking the provided message type into account.
FILL_BAPIRETTAB_BY_EXC Fills a table of BAPIRET2 messages from the provided
exception and all its predecessors stored in the PREVIOUS
attribute, thereby taking the provided message type into
account.
FILL_BAPIRET2_WD_BY_EXC Fills a BAPIRET2 message from the provided exception, thereby
taking the provided message type into account.
BAPIRET2 with details is represented by data type
IF_FSL_MESSAGE_HELPER=>T_STR_BAPIRET2_W_DETAILS.
FILL_BAPIRETTAB_WD_BY_EXC Fills a table of BAPIRET2 with details messages from the
provided exception and all its predecessors stored in the
PREVIOUS attribute, thereby taking the provided message type
into account.
The table of BAPIRET2 with details is represented by data type
IF_FSL_MESSAGE_HELPER=>T_TAB_BAPIRET2_W_DETAILS.
Table 7-5: Methods of the FSL Message Helper
BAPIRET2 and its table type BAPIRETTAB are widely used data types for error messages. They are important in
cases where standard services are used during the phase implementation, but other interfaces such as BAPIs
or RFCs instead. In addition, they are often employed as intermediate types for other error representations. For
example, the log helper can fill a GDT Log from a table of BAPIRET2 messages.
The FILL_*_BY_EXC methods preserve the content of the original message variables in case that the source
exception is an FSL exception (CX_FSL_) or any other exception that implements the IF_T100_MESSAGE
interface.
7.1.4.4 Message Header Helper
The FSL message header helper (IF_FSL_MESSAGE_HEADER_HELPER) offers convenience methods for
handling the GDT BusinessDocumentMessageHeader. It is provided in the phase implementation classes via
the attribute MR_MESSAGE_HEADER_HELPER.
The message header helper contains the following methods:
Method Name Description
VALIDATE_EXT Validates the external (GDT) representation of a message header.
VALIDATE_INT Validates the internal (FSL) representation of a message header.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 112
Method Name Description
CONVERT_EXT_TO_INT
CONVERT_INT_TO_EXT
These methods convert a message header from the external to the internal
representation and vice versa.
CONVERT_IN_OUT_INT Converts a message header from the internal inbound to the internal
outbound representation. That means that a new ID and UUID are drawn,
and the ID and UUID from the origin message header are used as the
REFERENCE_ID and the REFERENCE_UUID, respectively. The sender
system of the origin message header becomes the receiver system of the
new message header and vice versa.
CONVERT_IN_OUT_EXT Provides the same functionality as CONVERT_IN_OUT_INT, but supports
the external representation of a message header.
FILL_MIN_HEADER_INT Fills all the fields of a message header that are required as a minimum (ID,
UUID, CREATION_DATE_TIME, SENDER_BUSINESS_SYSTEM_ID). It is
particularly useful when filling the request message of a back-end service.
Table 7-6: Methods of the FSL Message Header Helper
7.1.4.5 Refresh Helper
The relevant instances that need to be refreshed when a service consumer calls the Refresh operation depend
on two things:
1. The Refresh Control Constraints (specified by the service consumer)
2. The Situation on the DB (statuses of node instances and their relations to each other)
The refresh control constraints (as shown in Figure 7-3) are filled by the service consumer in order to specify
what node instances are to be refreshed. At each level (root, node type, instance) there is a node “Selection”
and a node “RefreshInstruction”. The node “Selection” specifies which instances should be taken into
consideration for refresh.
Depending on the level the “RequestedIndicator” selects a specific instance (instance level), all instances for a
node type (node type level) or all instances of the PRO (root level).
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 113
Figure 7-3: Refresh Control Constraints (RCC) of the Refresh Request
The “DependentNodesSelectionRequestedIndicator” aka “deep indicator” also selects the depending node
instances (successors).
The “RefreshInstruction” defines what to do with the selected instances. The “RefreshRequestedIndicator” aka
“force indicator” indicates that an instance should be refreshed even the status is Finished.
Consequently, in order to determine which instances have actually to be refreshed, the following (persisted)
information has to be considered:
the relations of the instances in order to get all successor for a given node instance or a set of node
instances (to apply the deep indicator)
the statuses of the instances (to apply the “force indicator”)
Based on both sources the refresh helper calculates for each node type which instances are to be refreshed. A
static view is shown in Figure 7-4.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 114
Figure 7-4: Static View on Refresh Helper
The interface GET_RELEVANT_INSTANCES provides a list of PRON UUIDs for a given node type. The Refresh
Helper uses the Relations Helper to read the successor and predecessor relations for all PRON instances. The
request data (containing the RCCs) is handed over to the CREATE method at time of instantiation. The call
sequence for the method GET_RELEVANT_INSTANCES is shown in Figure 7-5:
Figure 7-5: Call Sequence for GET_RELEVANT_INSTANCES
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 115
At first access, the helper is initialized in a “lazy load” manner, because the calculation of the relevant node
instances is not for free and should only be carried out if requested.
First the RCCs (of type data) are mapped into an internal representation for better handling. Then the relevant
PRONs are selected. First, the method PRE_SELECT_PRONS selects all PRON instances according to the
“RequestedIndicator”, but without considering the deep indicator.
In a second step, the method ENRICH_WITH_DEPENDENT_PRONS drills down (starting with the PRON
instances from the first step where the deep indicator is set) until no new successors are found.
Finally, the method APPLY_REFRESH_INSTRUCTION applies the “force indicator”. That means that all
instances are skipped where the status is Finished and the “force indicator” is not set.
7.1.4.6 Restart Helper
For the restart, the relevant instances (of a node type) are depending on
1. The Restart Request (specified by the service consumer)
2. The Situation on the DB (relations of node instances)
Figure 7-6: Selection Part of the Restart Request
The Restart Request as shown in Figure 7-6 specifies selection criteria for each node type. Only in case the
“RequiredIndicator” is set, the corresponding phase implementation for this node type is called. The Node
“Predecessor”/”UUID” specifies to which predecessor node instances the restart is related to. If no UUIDs are
provided it is assumed that all instances (of all nodes types) are relevant for the restart. If at least one UUID is
provided only those instances become relevant that are located on the successor path starting with this UUID.
In order to evaluate the relevant nodes in case predecessor UUIDs are provided, the (persisted) relations are
provided.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 116
Based on the request data and the relations, the Restart Helper calculates the relevant instances. A static view
is shown in Figure 7-7.
Figure 7-7: Static View on Restart Helper
There is one instance for each node type, because the relevant instances depend on the selection that is specific
for each node type. For example, if for one node type no predecessor UUIDs are specified, the method
GET_RELEVANT_INSTANCES always returns all instances (for all other node types). If for another node type of
the same request predecessor UUIDs are specified, the method GET_RELEVANT_INSTANCES only returns
those instances (of other node types) that are related to these specific predecessors.
For the calculation of the relevant instances (specified by predecessor UUIDs) the PRON relations are required.
These relations are calculated by the Relations Helper.
7.1.5 Fetch Phase – Custom Implementation
The signature of the FETCH method of the phase implementation class (<MLB>CL_N_<PRON>_PIMPL) looks as
follows:
Method Name FETCH
Short Description Creates PRONs based on fetched data
What to do Enhance the PRON data provided as changing parameter C_PRONS with data retrieved
from the back-end services according to the input parameters operation type
I_OPERATION_TYPE, selection parameters I_PRO_PARAMETERS, and request data
I_REQUEST_DATA. Fill the provider ID and set the PRON status to
Finished in case no errors occurred and there is no further processing required in the Complete phase
Running in case no errors occurred and there is further processing required in the Complete phase
In case of errors either:
Set the PRON status to Erroneous and fill the provider log with details about the
error. This leads to overall status Erroneous of the PROT instance.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 117
Raise an exception of type <MLB>CX_IM in case of non-business related errors.
The exception is propagated to the service implementation and thus leads to
an unsuccessful service call (processing result code Failed) with an error
message in the log.
Preconditions None
Result PRONs are created successfully or error details are given in the provider log
Parameter name Parameter
Type
Ref. Data Type
I_PIMPL_HELPER Importing X <MLB>IF_PIMPL_HLP
I_BACKEND_SERVICES Importing <MLB>IF_BS_PROV=>TY_BS_<PRON>
I_PRO_PARAMETERS Importing <MLB>IF_IT_COMP=>TS_PRO_SEL_PARAMS
I_OPERATION_TYPE Importing X <MLB>CE_OP_TY
I_REQUEST_DATA Importing DATA
C_PRONS Changing <MLB>IF_N_<PRON>_PIMPL=>TT_FETCH
Exception X <MLB>CX_IM
Caution
A PRON instance needs to be created in FETCH also in case the back-end services are only called in
COMPLETE. This is due to the fact that the Complete phase for an instance is only started if there is
already an instance created in the Fetch phase.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 118
An implementation of the FETCH method typically has an activity flow similar to the one shown in Figure 7-8:
Figure 7-8: Activity Flow of Create Phase Code Slot
Access to data of other PRONs is possible if the corresponding dependencies were modeled between the PRONs
for the Fetch phase in the Specification Wizard.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 119
Example: Fetch Phase
The following two listings provide an example for the implementation of the Fetch phase for the Flight PRON.
The generated data declarations in Listing 7-4 are located outside of the code slot. The content of the code slot
is shown in Listing 7-5 and explained below.
data: lr_pron type ref to /pl9/if_stxx_f01_n_flgt_pimpl=>ts_fetch ##needed.
* data declaration for backend service request and response types
data: ls_flqo_qry_request type /pl9/cti0cflight_by_elements_2 ##needed,
ls_flqo_qry_response type /pl9/cti0cflight_by_elements_r ##needed,
ls_fbao_chk_request type /pl9/cti0cflight_booking_avail ##needed,
ls_fbao_chk_response type /pl9/cti0cflight_booking_avai5 ##needed.
* data declaration for prot service request (i_request_data)
field-symbols: <ls_start_request> type /pl9/ptxxsflight_search_fs_p72 ##needed,
<ls_restart_request> type /pl9/ptxxsflight_search_fs_p63 ##needed,
<ls_refresh_request> type /pl9/ptxxsflight_search_fs_p10 ##needed.
Listing 7-4: Data Declarations of the Fetch Phase
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 120
data: lr_flight type ref to /pl9/cti0cflight_v1,
lx_exec_error type ref to cx_fsl_execution_error.
try.
case i_operation_type.
when /pl9/ce_stxx_f01_op_ty=>start_execution_pro.
if lines( c_prons ) > 0.
/pl9/cx_stxx_f01_std_im=>raise( textid =
/pl9/cx_stxx_f01_c_custom=>invalid_cpron ).
endif.
assign i_request_data to <ls_start_request>.
* validate request input
if ( <ls_start_request>-fsrc-selection_criteria-flgt_selection-
required_indicator = abap_true and
<ls_start_request>-fsrc-selection_criteria-parameters-from is not initial and
<ls_start_request>-fsrc-selection_criteria-parameters-to is not initial and
<ls_start_request>-fsrc-selection_criteria-parameters-
planned_flight_date is not initial ).
* build service request
ls_flqo_qry_request-message_header = mr_message_header_helper
->fill_min_header_int( ).
move-corresponding <ls_start_request>-fsrc-selection_criteria-parameters-from-
airport_id to ls_flqo_qry_request-selection1-from-airport_id.
move-corresponding <ls_start_request>-fsrc-selection_criteria-parameters-to-
airport_id to ls_flqo_qry_request-selection1-to-airport_id.
ls_flqo_qry_request-selection1-planned_flight_date =
<ls_start_request>-fsrc-selection_criteria-parameters-planned_flight_date.
* call service for start execution
ls_flqo_qry_response = i_backend_services-flqo_qry
->execute( ls_flqo_qry_request ).
* map response to PRON data
loop at ls_flqo_qry_response-flight reference into lr_flight.
append initial line to c_prons reference into lr_pron.
lr_pron->public_admin_data-provider_id-airline_id =
lr_flight->id-airline_id.
lr_pron->public_admin_data-provider_id-connection_id =
lr_flight->id-connection_id.
lr_pron->public_admin_data-provider_id-planned_flight_date =
lr_flight->id-planned_flight_date.
lr_pron->details-from-airport_id-content =
lr_flight->from-location-airport_id-content.
lr_pron->details-from-date_time = lr_flight->from-date_time.
lr_pron->details-to-airport_id-content =
lr_flight->to-location-airport_id-content.
lr_pron->details-to-date_time = lr_flight->to-date_time.
lr_pron->details-price_amount-content = lr_flight->price_amount-content.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 121
lr_pron->details-price_amount-currency_code =
lr_flight->price_amount-currency_code.
* set status
lr_pron->public_admin_data-status_code =
/pl9/ce_stxx_f01_node_sts=>running->get_int_value( ).
endloop.
endif.
when /pl9/ce_stxx_f01_op_ty=>restart_execution_pro.
clear c_prons.
assign i_request_data to <ls_restart_request>.
* validate request input
if ( <ls_restart_request>-fsrc-selection_criteria-flgt_selection-
required_indicator = abap_true and
<ls_restart_request>-fsrc-selection_criteria-parameters-from
is not initial and
<ls_restart_request>-fsrc-selection_criteria-parameters-to
is not initial and
<ls_restart_request>-fsrc-selection_criteria-parameters-
planned_flight_date is not initial ).
* build service request
ls_flqo_qry_request-message_header = mr_message_header_helper
->fill_min_header_int( ).
move-corresponding <ls_restart_request>-fsrc-selection_criteria-parameters-
from-airport_id to ls_flqo_qry_request-selection1-from-airport_id.
move-corresponding <ls_restart_request>-fsrc-selection_criteria-parameters-to-
airport_id to ls_flqo_qry_request-selection1-to-airport_id.
ls_flqo_qry_request-selection1-planned_flight_date =
<ls_restart_request>-fsrc-selection_criteria-parameters-planned_flight_date.
* call service for start execution
ls_flqo_qry_response =
i_backend_services-flqo_qry->execute( ls_flqo_qry_request ).
* map response to PRON data
loop at ls_flqo_qry_response-flight reference into lr_flight.
append initial line to c_prons reference into lr_pron.
lr_pron->public_admin_data-provider_id-airline_id =
lr_flight->id-airline_id.
lr_pron->public_admin_data-provider_id-connection_id =
lr_flight->id-connection_id.
lr_pron->public_admin_data-provider_id-planned_flight_date =
lr_flight->id-planned_flight_date.
lr_pron->details-from-airport_id-content =
lr_flight->from-location-airport_id-content.
lr_pron->details-from-date_time = lr_flight->from-date_time.
lr_pron->details-to-airport_id-content =
lr_flight->to-location-airport_id-content.
lr_pron->details-to-date_time = lr_flight->to-date_time.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 122
lr_pron->details-price_amount-content = lr_flight->price_amount-content.
lr_pron->details-price_amount-currency_code =
lr_flight->price_amount-currency_code.
* set status
lr_pron->public_admin_data-status_code =
/pl9/ce_stxx_f01_node_sts=>running->get_int_value( ).
endloop.
endif.
when /pl9/ce_stxx_f01_op_ty=>refresh_pro.
assign i_request_data to <ls_refresh_request>.
* set status
loop at c_prons reference into lr_pron.
lr_pron->public_admin_data-status_code =
/pl9/ce_stxx_f01_node_sts=>running->get_int_value( ).
endloop.
when others.
assert 1 = 0. "not expected
endcase.
catch cx_fsl_internal_error cx_fsl_error_conflict_mapping cx_fsl_error_conflict_format
into lx_exec_error.
/pl9/cx_stxx_f01_std_im=>raise( textid =
/pl9/cx_stxx_f01_std_im=>err_in_service_execution
previous = lx_exec_error ).
endtry.
Listing 7-5: Code Slot of the Fetch Phase
1. The operation type is validated using the corresponding enumeration class <MLB>CE_OP_TY.
Only the values START_EXECUTION_PRO, RESTART_EXECUTION_PRO and REFRESH_PRO are
supported and in this case also implemented. For all other values a program abort is triggered, because
this is only possible in case of a wrong implementation in the framework. .
2. For the input parameter C_PRONS the following rules apply:
a. START_EXECUTION_PRO: has to be empty
b. RESTART_EXECUTION_PRO: C_PRONS are replaced by new entries
c. REFRESH: Existing C_PRONS are updated, additional C_PRONs might be added
3. At first, a minimal message header is created in the internal FSL format using the message header helper.
4. In case of START_EXECUTION_PRO and RESTART_EXECUTION_PRO the request is filled with the provided
selection criteria.
a. The back-end service is executed.
Exceptions are caught and attached to a custom exception, which is raised using its public
static RAISE method. In this case, the execution of the code slot is aborted.
b. The response message of the back-end service is processed.
A new PRON is created and first filled with the data provided in the request message.
Afterwards, the data returned by the back end is moved to the PRON.
This ensures that the PRON is filled according to the operation type. In addition to filling the
details of the PRON, the provider ID (contained in the public administrative data) is filled with
the ID of the business object.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 123
c. The status of the PRON is set to Running using enumeration class <MLB>CE_NODE_STS for
the node status code.
Running is the required value for all PRONs that are not complete and will have to be
completed during the Complete phase. If there is no Complete phase the status has to be
Finished.
5. In case of REFRESH_PRO the check request is filled with the provider id of the provided C_PRONS entries.
a. The back-end service is executed.
Exceptions are caught and attached to a custom exception, which is raised using its public
static RAISE method. In this case, the execution of the code slot is aborted.
b. The response message of the back-end service is processed.
This ensures that the PRON is filled according to the operation type.
c. The status of the PRON is set to Finished using enumeration class <MLB>CE_NODE_STS for
the node status code or to Running if further completion in Complete phase is required.
7.1.6 Complete Phase – Custom Implementation
The signature of the COMPLETE method of the phase implementation class (<MLB>CL_N_<PRON>_PIMPL)
looks as follows:
Method Name COMPLETE
Short Description Complete PRONs
What to do The Complete phase is based on the entries created during FETCH. Complete the PRON
data provided as changing parameter C_PRONS with the help of the back-end services
handed in via I_BACKEND_SERVICES. Completion can also mean adding entries to
parameter C_PRONS or deletion of entries from parameter C_PRONS.
In case of errors either:
Set the PRON status to Erroneous and fill the provider log with details about the
error. This leads to overall status Erroneous of the PROT instance.
Raise an exception of type <MLB>CX_IM in case of non-business related errors. The
exception is propagated to the service implementation and thus leads to an
unsuccessful service call (processing result code Failed) with an error message in
the log.
Preconditions PRONs have been created during Fetch phase
Result PRONs are completed successfully or errors are returned in the provider log
Parameter name Parameter
Type
Ref. Data Type
C_PRONS Importing <MLB>IF_N_<PRON>_PIMPL=>TT_COMPLETE
I_PIMPL_HELPER Importing X <MLB>IF_PIMPL_HLP
I_BACKEND_SERVICES Importing <MLB>IF_BS_PROV=>TY_BS_<PRON>
Exception X <MLB>CX_IM
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 124
A code slot implementation in the Complete phase typically has an activity flow similar to the one shown in Figure
7-9 below:
Figure 7-9: Activity Flow of Complete Phase Code Slot
Access to the data of other PRONs is possible. In the Complete phase, node dependencies are taken into
consideration.
Example: Calling Back-End Services
The following two listings show examples of how to call back-end services in a custom implementation for the
Complete phase of the Flight Search PRON. The generated data declarations in Listing 7-6 are located outside
of the code slot. The content of the code slot is shown in Listing 7-7 and explained below.
data: lr_pron type ref to /pl9/if_stxx_f01_n_flgt_pimpl=>ts_complete ##needed.
* data declaration for backend service request and response types
data: ls_flqo_qry_request type /pl9/cti0cflight_by_elements_2 ##needed,
ls_flqo_qry_response type /pl9/cti0cflight_by_elements_r ##needed,
ls_fbao_chk_request type /pl9/cti0cflight_booking_avail ##needed,
ls_fbao_chk_response type /pl9/cti0cflight_booking_avai5 ##needed.
Listing 7-6: Data Declarations of the Check Phase
Build Service Request
Call Service
Fil l Process LogSet Status
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 125
data: lx_exec_error type ref to cx_fsl_execution_error.
try.
loop at c_prons reference into lr_pron.
* build service request
ls_fbao_chk_request-message_header =
mr_message_header_helper->fill_min_header_int( ).
move-corresponding lr_pron->public_admin_data-provider_id to
ls_fbao_chk_request-flight_booking_availability-flight_id.
* call service for start execution
ls_fbao_chk_response = i_backend_services-fbao_chk->execute( ls_fbao_chk_request ).
* map response to PRON data
if ( ce_fsl_proc_result_code=>successful->s_get_instance( ls_fbao_chk_response-log-
bus_doc_processing_result_code ) = ce_fsl_proc_result_code=>successful ).
lr_pron->details-available_seat_number_value =
ls_fbao_chk_response-flight_booking_availability-available_seat_number_value.
* set status
lr_pron->public_admin_data-status_code =
/pl9/ce_stxx_f01_node_sts=>finished->get_int_value( ).
else.
lr_pron->public_admin_data-status_code =
/pl9/ce_stxx_f01_node_sts=>erroneous->get_int_value( ).
lr_pron->public_admin_data-provider_log = mr_log_helper
->convert_gdt_log_to_fsl_log( i_gdt_log = ls_mgca_rtv_response-log
i_gdt_type = ce_fsl_datatype=>log ).
endif.
endloop.
catch cx_fsl_internal_error cx_fsl_error_conflict_mapping cx_fsl_error_conflict_format
into lx_exec_error.
/pl9/cx_st00_f01_std_im=>raise( textid =
/pl9/cx_st00_f01_std_im=>err_in_service_execution
previous = lx_exec_error ).
endtry.
Listing 7-7: Code Slot of the Check Phase
1. All provided C_PRONs are accessed in a loop. The following steps are executed for each PRON:
2. The request message of the back-end service is filled.
At first, a minimal message header is created in the internal FSL format using the message header helper.
3. The request is filled with the provider ID of the flight.
4. The back-end service is executed.
Exceptions are caught and attached to a custom exception, which is raised using its public static RAISE
method. In this case, the execution of the code slot is aborted.
5. The response message of the back-end service is processed. The business document processing result
code contained in the log indicates whether the call was successful or not. This check is done using
enumeration class CE_FSL_PROC_RESULT_CODE from the FSL.
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 126
6. If successful, the PRON status is set to Finished using enumeration class <MLB>CE_NODE_STS for the
node status code. Otherwise it is set to Erroneous.
7. The provider log is filled with the error messages returned using the log helper.
7.2 Expiration of Node Instances
As introduced in section 4.4, node instances can expire due to change notifications from the backend, based
on time-dependent rules, and based on relationships between node instances. The following subsections
explain in which places you complete the implementation of your PROT with regard to node expiration.
7.2.1 Expiration Based on Back-End Information
7.2.1.1 Processing Back-End Information/Notification Messages
The method GET_PROVIDER_IDS_OF_MESSAGE is available for each back-end information/notification
operation in the class <MLB>CL_PIP_<Interface>_<Operation>. The method signature looks as
follows:
Method Name GET_PROVIDER_IDS_OF_MESSAGE
Short Description The method is used to extract the provider ID of a PRON from the information message
from the back end.
What to do Extract the provider IDs from the back-end information/notification message and add it
to the list of provider IDs for each concerned node type.
Preconditions None
Result Entries in the list of provider IDs
Parameter name Parameter
Type
Ref. Data Type
I_MESSAGE Importing DATA
R_PROVIDER_IDS Returning <MLB>IF_PIP=>TY_NODE_TYPE_PROVIDER_IDS
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 127
Example: Implementing the Provider ID Provider
A sample implementation of the code slot is shown in Listing 7-8:
data: lr_provider_id type ref to /pl9/if_stxx_f01_pip=>ty_node_type_provider_id.
field-symbols: <ls_provider_id> type /pl9/stxxsflight_id.
append initial line to r_provider_ids reference into lr_provider_id.
lr_provider_id->node_type = /pl9/ce_stxx_f01_node_ty_c=>flgt.
lr_provider_id->be_modification_date_time = <ls_message>-change_information-flight-
change_timestamp.
create data lr_provider_id->provider_id type /pl9/stxxsflight_id.
assign lr_provider_id->provider_id->* to <ls_provider_id>.
move-corresponding <ls_message>-change_information-flight-id to <ls_provider_id>.
Listing 7-8: Provider ID Provider
In the example the backend sent an information message stating that a flight has changed. The
implementation adds the ID of the flight together with its node type and the timestamp of the change to the
result list.
Make sure to use the internal representation of the provider ID (in this case /PL9/STXXSFLIGHT_ID) instead
of the SPROXY representation.
7.2.1.2 Filtering Instances to be Expired
After you have extracted the provider IDs of the changed back-end business objects from the
information/notification messages from the backend (see 7.2), you can restrict the list of relevant instances
based on the date of the last change in the back-end system. The implementation is done in the expiration
filter class <MLB>CL_EXPR_FLT.
The signature of the corresponding method the looks as follows:
Method Name FILTER_PRONS_TO_BE_EXPIRED
Short Description The method is used to restrict the list of instances that should be expired due to a
change of the corresponding back-end business object.
What to do Delete instances from the list of provided instances, for example by comparing the last
data retrieval with the change date.
Preconditions None
Result List of instances is adapted as required
Parameter name Parameter
Type
Ref. Data Type
C_PROS_W_PRONS Changing TY_PROS_W_PRONS_DETAILS
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 128
Example: Implementing the Expiration Filter
A sample implementation of the code slot is shown in Listing 7-9:
data: lr_pro_w_prons type ref to /pl9/if_stxx_f01_expr_flt=>ty_pro_w_prons_details,
lr_pron type ref to /pl9/if_stxx_f01_expr_flt=>ty_pron_details.
loop at c_pros_w_prons reference into lr_pro_w_prons.
loop at lr_pro_w_prons->prons_details reference into lr_pron.
if ( lr_pron->be_modification_date < lr_pron->last_retrieval_date ).
delete lr_pro_w_prons->prons_details.
endif.
endloop.
endloop.
Listing 7-9: Expiration Filter
In the sample implementation, all instances that were retrieved after the change date are deleted from the list
of instances to be expired.
7.2.2 Expiration Based on Time-Dependent Rules
When you selected time-dependent expiration during modeling, you can use the time dependency provider
class <MLB>_CL_TDP_PRV to define when node instances and/or node types should expire.
Expiration on node instance level means that node instances are set to Expired after a certain amount of time.
Expiration on node type level means that only the PRONT is set to Expired, all its node instances remain
unchanged.
To explain the difference between the different levels of expiration, consider our search for flights: All flights
that were previously found are considered up-to-date. However, after a certain amount of time you want to
check whether additional flights have been added by the airlines in the meantime. To achieve this you set the
Flight node type to Expired but keep all existing node instances.
The signatures of the corresponding methods the look as follows:
Method Name GET_DURATION_FOR_NODE_INSTANCE
Short Description The method is used to define the duration after which node instances should expire.
What to do Provide the duration after which instances of the given node type should expire
Preconditions None
Result The duration is filled
Parameter name Parameter
Type
Ref. Data Type
I_NODE_TYPE Importing X <MLB>CE_NODE_TY_C
R_DURATION Returning /PL9/IF_STXX_F01_IT_BASE=>TS_GDT_DURATION
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 129
Method Name GET_DURATION_FOR_NODE_TYPE
Short Description The method is used to define the duration after which node types should expire.
What to do Provide the duration after the given node type should expire
Preconditions None
Result The duration is filled
Parameter name Parameter
Type
Ref. Data Type
I_NODE_TYPE Importing X <MLB>CE_NODE_TY_C
R_DURATION Returning /PL9/IF_STXX_F01_IT_BASE=>TS_GDT_DURATION
Example: Implementing the Time Dependency Provider
A sample implementation of the methods is shown in Listing 7-10:
r_duration = 'PT5M'.
Listing 7-10: Time Dependency Provider
Node instances (types) expire after five minutes.
7.3 Parallel Processing
In order to control the parallel processing of node instances during the Complete phase, you can use the
package size provider class <MLB>CL_PP_PS_PRV to define how many node instances of one node type a
background job should process. By default each node instance is processed by its own background job.
The signature of the corresponding method the looks as follows:
Method Name GET_PACKAGE_SIZE
Short Description The method is used to define the number of node instances that are executed per
background job in the Complete phase.
What to do Per node type define the number of instances to be executed by one background job.
Preconditions None
Result Number of node instances is filled
Parameter name Parameter
Type
Ref. Data Type
I_NODE_TYPE Importing X <MLB>CE_NODE_TY_C
R_PACKAGE_SIZE Returning TY_PACKAGE_SIZE
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 130
Example: Implementing the Package Size Provider
A sample implementation of the code slot is shown in Listing 7-11:
case i_node_type.
when /pl9/ce_stxx_f01_node_ty_c=>flgt.
r_package_size = 10.
when others.
r_package_size = /pl9/if_stxx_f01_pp_ps_prv=> con_package_size_all_in_one.
endcase.
Listing 7-11: Package Size Provider
Flights should be processed in packages of ten. All others (in this case the shuttles) are processed by a single
background job (package size set to the corresponding constant).
7.4 Implementing Additional Authorization Checks
If additional authorization checks were selected during specification, these checks have to be implemented in
the class for custom authorization checks (<MLB>CL_ATH_CHK_C). You can restrict the authorizations (for
example, based on the payload of a service request) or specifically prohibit the execution of certain service
operations.
The signature of the corresponding method looks as follows:
Method Name IS_AUTHORIZED
Short Description Performs Additional Authorization Checks
What to do Implement additional authorization checks according to your needs
Preconditions None
Result The result of the authorization check is returned
Parameter name Parameter
Type
Ref. Data Type
I_ACTIVITY Importing X <MLB>CE_ATH_ACT
I_NODE_TYPE Importing X <MLB>CE_NODE_TY_C
I_OPERATION Importing X <MLB>CE_OP_TY
I_REQUEST_DATA Importing DATA
I_PRO_TOTAL Importing <MLB>IF_IT_COMP=>TS_PRO_PUB_TOTAL
R_IS_AUTHORIZED Returning ABAP_BOOL
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 131
7.5 Internal Types
Internal types are the internal representation of generated SPROXY types. They can be divided into common
internal types (shared across different PROTs with the same namespace) and PROT-specific internal types:
The common internal types are clones of the generated SPROXY types for the message types of the back-end
services. These types are ABAP Dictionary (DDIC) types and include controller tables to support extended XML
handling.
The PROT-specific internal types are cloned from the generated SPROXY types of the message types of the
PROT services. These types are also DDIC-based, but they do not contain controller tables. In addition to the
PROT-specific DDIC types, there also are some PROT-specific interface types available. These are grouped into
several interfaces (see Table 7-7 below), which are located in the general package. However, the internal types
are not 1:1 copies of the SPROXY types, but have been adapted and enriched where useful.
Interface Description
<MLB>IF_IT_BASE Base data types used as part of the other types
<MLB>IF_IT_COMP Complete types (see Table 7-9, and Table 7-10 below)
Table 7-7: Interfaces for Internal Types
For each type used in POL implementations, two type definitions are generated: A flat type (scalar or structured
with prefix ‘TS_’) and a corresponding table type of this flat structure (prefix ‘TT_’). For a PROT developer,
<MLB>IF_IT_COMP is the most important interface, because it contains the majority of the types that are used
in the code slots.
The following three tables explain commonly used types of the PRO and the PRONs from the complete types
interface. The structured types (TS_) listed below all have corresponding tabular types (TT_), which are not
mentioned in the tables.
Internal Type Description
TS_PRO_ SEL_PARAMS Selection Parameters of the PRO
TS_PRO_PUB_ADM Public administrative data of the PRO containing its UUID,
BPCA, reference ID, change state ID, type code, aggregated
status code and log
TS_PRO_TOTAL_PUB_ADM Total type of public administrative data of the PRO containing its
UUID, BPCA, reference ID, change state ID, type code,
aggregated status code, internal status, and log
TS_PRIVATE_ADMIN_DATA Private administrative data of the PRO containing its UUID
system administrative data, and version data
TS_PRO_COMPLETE Complete data of the PRO containing public and private
administrative data, and a table of relations with the UUIDs of its
PRONs, their type, status, successors and predecessors
TS_PRO_PUBLIC_COMPLETE Public complete data of the PRO containing public
administrative data
TS_PRO_TOTAL Total type of the PRO containing public and private
administrative data, selection parameters, read access data,
and the complete types of its PRONs
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
PROT Implementation
PUBLIC
© 2017 SAP SE. All rights reserved. 132
Internal Type Description
TS_PRO_PUB_TOTAL Public total type of the PRO containing public administrative
data and the complete types of its PRONs (without private
administrative data)
TS_PRO_SELECTION_TOTAL Selection Parameters of the PRO and all selection parameters of
the nodes
Table 7-8: Important PRO Types
Internal Type Description
TS_PRONT_STATUS Aggregated status codes of all node types
TS_PRONT_SEL_ADMIN_DATA Node Type Selection Administrative Data containing the
reference ID and a table of predecessors
Table 7-9: Important PRONT Types
Internal Type Description
TS_PRON_<PRON>_PROVIDER_ID Provider ID of the <PRON>
TS_PRON_<PRON>_DETAILS Details of <PRON>
TS_PRON_<PRON>_SEL_PARAMS Selection Parameters of <PRON>
TS_PRON_<PRON>_PRIVATE_DETAILS Private details of <PRON>
TS_PRON_<PRON>_PUB_ADM Public administrative data of <PRON> containing its UUID,
provider ID, reference ID, type code, status code, retrieval date
and time, predecessor, and log
TS_PRON_<PRON>_PRIV_ADM Private administrative data of <PRON> containing the PRO
UUID, system administrative data and version data
TS_PRON_<PRON>_SEL Selection attributes of <PRON> containing required indicator,
public administrative data, and selection parameters
TS_PRON_<PRON>_COMPLETE Complete type of <PRON> containing public and private
administrative data, details and private details
TS_PRON_<PRON>_PUBLIC_COMPLETE Public complete type of <PRON> containing public
administrative data, details, and private details (no private
administrative data)
Table 7-10: Important PRON Types
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Terms and Abbreviations
PUBLIC
© 2017 SAP SE. All rights reserved. 133
Terms and Abbreviations
Term /
Abbreviation
Full Name
BAdI Business Add-In
CNS Change and Notification Service
ECH Error and Conflict Handler
ESR Enterprise Services Repository
FSL Financial Services Library
GDT Global Data Type
ILM Information Lifecycle Management
OAF Outbound Agent Framework
POB SAP Process Object Builder
POT Process Object Type
PPO Post Processing Office
PROB Persistent Retrieval Object Builder
PRONT Persistent Retrieval Object Node Type
PROT Persistent Retrieval Object Type
PSJ Process Step Journal
Result Code Short for GDT BusinessDocumentProcessingResultCode
SAP PI SAP Process Integration
Severity Code Short for GDT LogItemSeverityCode
SIW Service Implementation Workbench
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Table of Figures
PUBLIC
© 2017 SAP SE. All rights reserved. 134
Table of Figures
Figure 2-1: Typical IT Landscapes and Integration Challenges ..................................................................................8
Figure 2-2: Motivation for Process Object Types and Persistent Retrieval Object Types .......................................9
Figure 2-3: PROT Development Life Cycle .................................................................................................................. 11
Figure 2-4: Flight Search .............................................................................................................................................. 14
Figure 3-1: Model-Driven Software Development in the Context of PROB/PROT .................................................. 17
Figure 3-2: SAP SOA Modeling Methodology Metamodel ....................................................................................... 20
Figure 3-3: Business Object Map for Sample Use Case (SAP SOA Modeling Methodology) ................................ 21
Figure 3-4: Metamodel of a PROT .............................................................................................................................. 22
Figure 3-5: Preliminary Object Model for Sample PROT FlightSearch .............................................................. 23
Figure 3-6: Abstract PROT Object Model Template ................................................................................................. 25
Figure 3-7: Detailed Object Model for Sample PROT FlightSearch .....................................................................27
Figure 4-1: High-Level Phase Model of a PROT ......................................................................................................... 34
Figure 4-2: Status Calculation of Aggregated PRO/PRONT Status ....................................................................... 35
Figure 4-3: Overview of PROT Status Transitions .................................................................................................... 36
Figure 4-4: Legend for Sequence Diagrams ...............................................................................................................37
Figure 4-5: Fetch Phase – Dynamic View .................................................................................................................. 38
Figure 4-6: Complete Phase – Dynamic View ........................................................................................................... 39
Figure 5-1: Static PROT Structure .............................................................................................................................. 42
Figure 5-2: ABAP Environment of a PROT ................................................................................................................. 44
Figure 5-3: Core Package Structure of a PROT......................................................................................................... 45
Figure 6-1: Block Diagram of PROT Layer Concept .................................................................................................. 54
Figure 6-2: Application Façade ................................................................................................................................... 55
Figure 6-3: Application Facade for Operation StartExecution<PRO> - Call Sequence......................................... 56
Figure 6-4: PRO API - Static View ............................................................................................................................... 58
Figure 6-5: Specific Details of the PRO API - Static View ......................................................................................... 60
Figure 6-6: PRON API - Static View ............................................................................................................................. 61
Figure 6-7: Selection API - Static View ....................................................................................................................... 62
Figure 6-8: Node Type Status API - Static View ........................................................................................................ 63
Figure 6-9: Read Access Data API - Static View........................................................................................................ 64
Figure 6-10: Versioning – Static View ........................................................................................................................ 65
Figure 6-11: Relation between Phase Helper and Phase Implementation .............................................................. 66
Figure 6-12: Call Sequence for Fetch Phase ...............................................................................................................67
Figure 6-13: Call Sequence for Complete Phase ....................................................................................................... 68
Figure 6-14: Parallelization Implementation - Static View ....................................................................................... 69
Figure 6-15: Different Areas of Processing Decoupled by RFCs.............................................................................. 70
Figure 6-16: Service Implementation Layers.............................................................................................................. 71
Figure 6-17: Overview of the Services Provided by a PROT ......................................................................................72
Figure 6-18: PROT Standard Synchronous Inbound Service Implementation - Static View .................................73
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Table of Figures
PUBLIC
© 2017 SAP SE. All rights reserved. 135
Figure 6-19: PROT Standard Synchronous Inbound Service (Request/Confirmation) – Call Sequence ............74
Figure 6-20: Back-End Related Asynchronous Inbound Service Implementation – Static View .......................... 75
Figure 6-21: Back-End Related Asynchronous Inbound Service Implementation – Call Sequence (Success) ...76
Figure 6-22: Back-End-Related Synchronous Outbound Service Implementation – Static View ........................ 77
Figure 6-23: Back-End-Related Synchronous Outbound Service Implementation - Call Sequence ....................78
Figure 6-24: ABAP Channel - static view ................................................................................................................... 80
Figure 6-25: Query Helper - Static View...................................................................................................................... 81
Figure 6-26: PROT Transaction Control – Static View ............................................................................................. 82
Figure 6-27: PROT Exception Hierarchy – Static View ............................................................................................. 83
Figure 6-28: Private Status of a PRO ......................................................................................................................... 85
Figure 6-29: PROT Status Calculator – Static View ................................................................................................. 85
Figure 6-30: Order of Statuses for Overall Status Calculation ................................................................................ 86
Figure 6-31: Expiry Helper for Asynchronous Inbound Services ............................................................................. 88
Figure 6-32: Expiration based on Asynchronous Inbound Services - Call Sequence ............................................ 89
Figure 6-33: Expiration Rules Specified in Modeling Wizard ................................................................................... 90
Figure 6-34: Time Dependency Expiration Helper - Static View............................................................................... 91
Figure 6-35: Instance and Node Type Expiration - Basic Call Sequence ................................................................ 92
Figure 6-36: Obtaining Expiration Timestamps - Call Sequence ............................................................................ 93
Figure 6-37: Raising of Events - Static View .............................................................................................................. 94
Figure 6-38: Event Mediator - Static View ................................................................................................................. 95
Figure 6-39: Status Change of a PRON Raises STATUS_CHANGED Event .............................................................. 96
Figure 6-40: Registered Actions are Executed ..........................................................................................................97
Figure 6-41: Predecessor Definition ........................................................................................................................... 98
Figure 6-42: CNS Action Class for Status Changed Event – Static View ............................................................... 99
Figure 6-43: OAF Agent Implementation – Static View ........................................................................................... 99
Figure 6-44: Call Sequence for the Processing of Change Pointers by the OAF Agent ...................................... 100
Figure 6-45: Deletion of PRO Instances – Call Sequence ....................................................................................... 101
Figure 7-1: Phase Implementation .............................................................................................................................104
Figure 7-2: POL-specific Pattern for Raising Exceptions ........................................................................................ 105
Figure 7-3: Refresh Control Constraints (RCC) of the Refresh Request ............................................................... 113
Figure 7-4: Static View on Refresh Helper ................................................................................................................ 114
Figure 7-5: Call Sequence for GET_RELEVANT_INSTANCES .................................................................................. 114
Figure 7-6: Selection Part of the Restart Request ................................................................................................... 115
Figure 7-7: Static View on Restart Helper ................................................................................................................. 116
Figure 7-8: Activity Flow of Create Phase Code Slot ............................................................................................... 118
Figure 7-9: Activity Flow of Complete Phase Code Slot .......................................................................................... 124
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Table of Tables
PUBLIC
© 2017 SAP SE. All rights reserved. 136
Table of Tables
Table 4-1: Values of GDT PersistentRetrievalObjectNodeStatusCode..................................................... 35
Table 6-1: Database Tables of a PROT ........................................................................................................................ 57
Table 6-2: Decision Matrix for Status Aggregation for Node Type Status ..............................................................87
Table 7-1: Read and Write Accesses in the Phase Implementation ....................................................................... 107
Table 7-2: Important GDTs ........................................................................................................................................108
Table 7-3: Methods of the Phase Helper .................................................................................................................. 109
Table 7-4: Methods of the Log Helper ....................................................................................................................... 110
Table 7-5: Methods of the FSL Message Helper ....................................................................................................... 111
Table 7-6: Methods of the FSL Message Header Helper ......................................................................................... 112
Table 7-7: Interfaces for Internal Types .................................................................................................................... 131
Table 7-8: Important PRO Types ............................................................................................................................... 132
Table 7-9: Important PRONT Types .......................................................................................................................... 132
Table 7-10: Important PRON Types .......................................................................................................................... 132
Design & Implementation of Persistent Retrieval Object Types using Persistent Retrieval Object Builder (SAP
Process Object Builder 2.0 FP1)
Table of Listings
PUBLIC
© 2017 SAP SE. All rights reserved. 137
Table of Listings
Listing 7-1: Source Code Example .............................................................................................................................103
Listing 7-2: Transferring Back-End Errors to the Provider Log ............................................................................. 106
Listing 7-3: Raising a Custom Exception .................................................................................................................. 107
Listing 7-4: Data Declarations of the Fetch Phase ................................................................................................... 119
Listing 7-5: Code Slot of the Fetch Phase ................................................................................................................. 122
Listing 7-6: Data Declarations of the Check Phase .................................................................................................. 124
Listing 7-7: Code Slot of the Check Phase ................................................................................................................ 125
Listing 7-8: Provider ID Provider................................................................................................................................ 127
Listing 7-9: Expiration Filter ....................................................................................................................................... 128
Listing 7-10: Time Dependency Provider .................................................................................................................. 129
Listing 7-11: Package Size Provider ...........................................................................................................................130
www.sap.com/contactsap
© 2017 SAP SE or an SAP affiliate company. All rights reserved.
No part of this publication may be reproduced or transmitted in any form
or for any purpose without the express permission of SAP SE or an SAP
affiliate company.
SAP and other SAP products and services mentioned herein as well as their
respective logos are trademarks or registered trademarks of SAP SE (or an
SAP affiliate company) in Germany and other countries. All other product
and service names mentioned are the trademarks of their respective
companies. Please see http://www. sap.com/corporate-
en/legal/copyright/index.epx#trademark for additional trademark
information and notices.