Design & Implementation of Persistent Retrieval Object ...

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


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



Table of Contents

PUBLIC


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



Table of Contents

PUBLIC


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



Preface

PUBLIC


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.



Preface

PUBLIC


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.

http://help.sap.com/pobuilder



http://scn.sap.com/docs/DOC-17603







Preface

PUBLIC


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.




Introduction

PUBLIC


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



Introduction

PUBLIC


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



Introduction

PUBLIC


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.



Introduction

PUBLIC


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.



Introduction

PUBLIC


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.

http://help.sap.com/saphelp_pobuilder10/helpdata/en/0b/da584617d042b48e98224f58842070/content.htm?frameset=/en/58/1303492f6a4d0f98467d0a6740bd7d/frameset.htm







Introduction

PUBLIC


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).



Introduction

PUBLIC


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.



Introduction

PUBLIC


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



Introduction

PUBLIC


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.



PROT Definition

PUBLIC


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



PROT Definition

PUBLIC


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.



PROT Definition

PUBLIC


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.



PROT Definition

PUBLIC


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).



PROT Definition

PUBLIC


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.

http://test.sap.com/xi/BusinessTripManagement



PROT Definition

PUBLIC


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.

http://test.sap.com/xi/FlightSearchProcessing

http://test.sap.com/xi/HotelSearchProcessing

http://test.sap.com/xi/FlightBookingProcessing



PROT Definition

PUBLIC


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’.



PROT Definition

PUBLIC


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.



PROT Definition

PUBLIC


<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



PROT Definition

PUBLIC


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:



PROT Definition

PUBLIC


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



PROT Definition

PUBLIC


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.

http://wiki.sdn.sap.com/wiki/display/GDT/SAP+Global+Data+Types+(GDTs)



PROT Definition

PUBLIC


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



PROT Definition

PUBLIC


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.



PROT Definition

PUBLIC


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.



PROT Definition

PUBLIC


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.



PROT Programming Model

PUBLIC


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:




PUBLIC


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:




PUBLIC


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.




PUBLIC


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.




PUBLIC


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)




PUBLIC


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):




PUBLIC


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




PUBLIC


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.



PROT High-Level Design

PUBLIC


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.




PUBLIC


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




PUBLIC


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>.





PUBLIC


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.




PUBLIC


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.




PUBLIC


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




PUBLIC


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.




PUBLIC



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


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.




PUBLIC



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>_...


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)




PUBLIC



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)




PUBLIC



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.




PUBLIC


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.



PROT Detailed Design

PUBLIC


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




PUBLIC


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




PUBLIC


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).




PUBLIC


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




PUBLIC


<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




PUBLIC


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




PUBLIC


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.




PUBLIC


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




PUBLIC


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




PUBLIC


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




PUBLIC


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




PUBLIC


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.




PUBLIC


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.




PUBLIC


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.




PUBLIC


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.




PUBLIC


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




PUBLIC


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.




PUBLIC


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.




PUBLIC


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.




PUBLIC


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>>




ReadResponse ()

RetrieveResponse<PRONT> ()

ReadResponse<PRON> ()

Cancel ()

<PersistentRetrievalObject><Version>ActionIn

+

+

+

+





StartExecution ()

RestartExecution ()

Refresh ()

AbortExecution ()




PUBLIC


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.




PUBLIC


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.




PUBLIC


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




PUBLIC


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.




PUBLIC


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.




PUBLIC


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.




PUBLIC


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",


}

}

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>",


"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 ",


}

}

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.




PUBLIC


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




PUBLIC


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.




PUBLIC


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.




PUBLIC


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.




PUBLIC


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.




PUBLIC


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




PUBLIC


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.




PUBLIC


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.




PUBLIC


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




PUBLIC


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.




PUBLIC


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).




PUBLIC


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)




PUBLIC


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




PUBLIC


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.




PUBLIC


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.




PUBLIC


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.




PUBLIC


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.




PUBLIC


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.




PUBLIC


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:




PUBLIC


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




PUBLIC


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.




PUBLIC


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



PROT Implementation

PUBLIC


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.



PROT Implementation

PUBLIC


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>.


when //pl9/ce_stxx_f01_op_ty =>restart_execution_pro.

assign i_request_data to <ls_restart_request>.


when /pl9/ce_stxx_f01_op_ty=>refresh_pro.

assign i_request_data to <ls_refresh_request>.


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).



PROT Implementation

PUBLIC


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).



PROT Implementation

PUBLIC


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



PROT Implementation

PUBLIC


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.



...

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).


* operation code


...

when others.

/pl9/cx_stxx_f01_c_custom=>raise(

textid = /pl9/cx_stxx_fb01_c_custom=>unsupported_operation_code



PROT Implementation

PUBLIC


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.



PROT Implementation

PUBLIC


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.



PROT Implementation

PUBLIC


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:


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.



PROT Implementation

PUBLIC



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:


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.



PROT Implementation

PUBLIC



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:


VALIDATE_EXT Validates the external (GDT) representation of a message header.

VALIDATE_INT Validates the internal (FSL) representation of a message header.



PROT Implementation

PUBLIC



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).



PROT Implementation

PUBLIC


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.



PROT Implementation

PUBLIC


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



PROT Implementation

PUBLIC


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.



PROT Implementation

PUBLIC


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.



PROT Implementation

PUBLIC


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.



PROT Implementation

PUBLIC


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.



PROT Implementation

PUBLIC


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 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



PROT Implementation

PUBLIC


data: lr_flight type ref to /pl9/cti0cflight_v1,

lx_exec_error type ref to cx_fsl_execution_error.

try.



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.



PROT Implementation

PUBLIC


lr_pron->details-price_amount-currency_code =

lr_flight->price_amount-currency_code.

* set status


/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 ).


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.


ls_flqo_qry_response =

i_backend_services-flqo_qry->execute( ls_flqo_qry_request ).


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.



PROT Implementation

PUBLIC


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



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.



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.



PROT Implementation

PUBLIC


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


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



PROT Implementation

PUBLIC


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



PROT Implementation

PUBLIC


data: lx_exec_error type ref to cx_fsl_execution_error.

try.

loop at c_prons reference into lr_pron.


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.


ls_fbao_chk_response = i_backend_services-fbao_chk->execute( ls_fbao_chk_request ).


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


/pl9/ce_stxx_f01_node_sts=>finished->get_int_value( ).

else.


/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.



PROT Implementation

PUBLIC


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


Type

Ref. Data Type

I_MESSAGE Importing DATA

R_PROVIDER_IDS Returning <MLB>IF_PIP=>TY_NODE_TYPE_PROVIDER_IDS



PROT Implementation

PUBLIC


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


Type

Ref. Data Type

C_PROS_W_PRONS Changing TY_PROS_W_PRONS_DETAILS



PROT Implementation

PUBLIC


Example: Implementing the Expiration Filter


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


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



PROT Implementation

PUBLIC


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


Type

Ref. Data Type


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


Type

Ref. Data Type


R_PACKAGE_SIZE Returning TY_PACKAGE_SIZE



PROT Implementation

PUBLIC


Example: Implementing the Package Size Provider


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


Type

Ref. Data Type

I_ACTIVITY Importing X <MLB>CE_ATH_ACT


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



PROT Implementation

PUBLIC


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



PROT Implementation

PUBLIC



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


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


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



Terms and Abbreviations

PUBLIC


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



Table of Figures

PUBLIC


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



Table of Figures

PUBLIC


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



Table of Tables

PUBLIC


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



Table of Listings

PUBLIC


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.

http://www.sap.com/corporate-en/legal/copyright/index.epx#trademark

http://www.sap.com/corporate-en/legal/copyright/index.epx#trademark

Design & Implementation of Persistent Retrieval Object ...

Documents

Transcript of Design & Implementation of Persistent Retrieval Object ...