Master Data Governance (MDG)

Application Programming Interface (API) Guide

Applies to:
SAP MDG 9.0 and lower

Summary
This guide provides a table of existing APIs for MDG and gives an overview of the governance and the
convenience API, explaining capabilities and behaviour. It also contains sample code.

Author(s): Marcus Galleck

Company: SAP SE

Created on: 07 June 2016

Author Bio
Marcus Galleck, SAP SE
Development Architect

1
Table of Contents

Table of Contents
1 Overview of MDG Usable APIs ............................................................................................................. 3
1.1 Availability of APIs and Their Functional scope..................................................................................... 3
1.2 Usage of MDG APIs .............................................................................................................................. 5
2 Introduction ............................................................................................................................................ 7
3 Limitations .............................................................................................................................................. 8
4 Interfaces ............................................................................................................................................. 10
4.1 Governance API .................................................................................................................................. 10
4.1.1 IF_USMD_GOV_API .................................................................................................................................... 10
4.1.2 IF_USMD_GOV_API_CR_DATA ................................................................................................................. 10
4.1.3 IF_USMD_GOV_API_ENTITY ..................................................................................................................... 10
4.1.4 IF_USMD_GOV_API_PROCESS ................................................................................................................ 10
4.1.5 IF_USMD_GOV_API_SERVICES ................................................................................................................ 10
4.1.6 IF_USMD_GOV_API_TRANS ...................................................................................................................... 10
4.1.7 IF_USMD_GOV_API_CR_ACTION ............................................................................................................. 10
4.2 Convenience API ................................................................................................................................. 11
4.2.1 IF_USMD_CONV_SOM_GOV_API ............................................................................................................. 11
4.2.2 IF_USMD_CONV_SOM_GOV_CR .............................................................................................................. 11
4.2.3 IF_USMD_CONV_SOM_GOV_ENTITY ...................................................................................................... 11
4.2.4 IF_USMD_CONV_SOM_GOV_TRANS ....................................................................................................... 11
4.2.5 IF_USMD_CONV_SOM_GOV_CR_ACTION .............................................................................................. 11
5 Simple Guide for Implementation ........................................................................................................ 12
5.1 Sequence Diagram for Convenience API Usage ................................................................................ 12
5.2 Reading Entity Data ............................................................................................................................. 12
5.2.1 Reading Entity Data - Governance API Behavior ......................................................................................... 13
5.3 Writing Entity Data ............................................................................................................................... 14
5.3.1 Write Strategies and Cross-Derivation ......................................................................................................... 14
5.3.2 Writing Data with Convenience/Governance API ......................................................................................... 15
5.3.3 Writing Data with the Change Request API.................................................................................................. 16
5.4 Authorization ........................................................................................................................................ 16
5.4.1 Entity Authorization ...................................................................................................................................... 16
5.4.2 Change Request Authorization .................................................................................................................... 16
5.5 Code Example Create Airline (with governance API) ....................................................................... 17
5.6 Code Example Change Flight Connection (with governance API) ................................................... 21
Copyright........................................................................................................................................................... 24

2
1 Overview of MDG Usable APIs
Depending on the software release, MDG offers different APIs for consumption with different functional
scopes.

1.1 Availability of APIs and Their Functional scope

Availability Description Object Purpose / Scope

EhP 5 Change Request CL_USMD_CREQUEST_API Programming interface for

CR Processing. One
API Instance per change request.
IF_USMD_CREQUEST_API Administration of change
request object list by
consumer.

External use model IF_USMD_MODEL_EXT Reading entity and hierarchy

data.
API
CL_USMD_MODEL_EXT

EhP 6 Change Request CL_USMD_CREQUEST_API No further development.

API
IF_USMD_CREQUEST_API

Governance API CL_USMD_GOV_API Programming interface for

governance process. One
instance per MDG model.
IF_USMD_GOV_API Multiple CR processing
within one instance for one
model. Limited use for
models using editions.

Convenience API CL_USMD_CONV_SOM_GOV_API Programming interface for

governance process
optimized for single object
IF_USMD_CONV_SOM_GOV_API processing and single object
processing UIs. No support
for models using editions.

App Context API CL_USMD_APP_CONTEXT Programming interface

consumed mainly by
convenience API. Stores and
IF_USMD_APP_CONTEXT calculates context data.

External use model IF_USMD_MODEL_EXT Reading entity and hierarchy

data.
API
CL_USMD_MODEL_EXT

MDG 6.1 Change Request CL_USMD_CREQUEST_API No further development.

API
IF_USMD_CREQUEST_API

Governance API CL_USMD_GOV_API Support of foreign key

entities.
IF_USMD_GOV_API

Convenience API CL_USMD_CONV_SOM_GOV_API Support of foreign key

entities.
IF_USMD_CONV_SOM_GOV_API

3
 App Context API CL_USMD_APP_CONTEXT No further development.

IF_USMD_APP_CONTEXT

External use model IF_USMD_MODEL_EXT Reading entity and hierarchy

data.
API
CL_USMD_MODEL_EXT

MDG 7.0 Change Request CL_USMD_CREQUEST_API No further development.

API
IF_USMD_CREQUEST_API

MDG 7.0 Governance API CL_USMD_GOV_API Support of new edition

management and parallel
change requests
IF_USMD_GOV_API

Convenience API CL_USMD_CONV_SOM_GOV_API Support of new edition

management and parallel
change requests
IF_USMD_CONV_SOM_GOV_API

App Context API CL_USMD_APP_CONTEXT Support of new edition

management and parallel
change requests
IF_USMD_APP_CONTEXT

External use model IF_USMD_MODEL_EXT Support for reading data

from parallel change
API requests
CL_USMD_MODEL_EXT

MDG 8.0 Change Request CL_USMD_CREQUEST_API No further development.

API
IF_USMD_CREQUEST_API

MDG 8.0 Governance API CL_USMD_GOV_API Consumption of Read API

Hierarchy maintenance
IF_USMD_GOV_API

Convenience API CL_USMD_CONV_SOM_GOV_API Hierarchy maintenance

IF_USMD_CONV_SOM_GOV_API

App Context API CL_USMD_APP_CONTEXT No further development.

IF_USMD_APP_CONTEXT

External use model IF_USMD_MODEL_EXT No further development.

API
CL_USMD_MODEL_EXT

Read API CL_USMD_READ_API Enhanced entity data buffer

MDG 9.0 Change Request CL_USMD_CREQUEST_API No further development.

API
IF_USMD_CREQUEST_API

4
 MDG 9.0 Governance API CL_USMD_GOV_API No further development

IF_USMD_GOV_API

Convenience API CL_USMD_CONV_SOM_GOV_API No further development.

IF_USMD_CONV_SOM_GOV_API

App Context API CL_USMD_APP_CONTEXT No further development.

IF_USMD_APP_CONTEXT

External use model IF_USMD_MODEL_EXT No further development.

API
CL_USMD_MODEL_EXT

Read API CL_USMD_READ_API Change of buffer concept

1.2 Usage of MDG APIs

Use Case Allowed usage Forbidden usage

Build UI application, IF_USMD_GOV_API or IF_USMD_MODEL

Inbound/Remote
governed process IF_USMD_CONV_SOM_GOV_API or

IF_USMD_CREQUEST_API

IF_USMD_MODEL_EXT

(read access only)

IF_USMD_READ_API

(read access only)

Access Class IF_USMD_MODEL_EXT IF_USMD_MODEL

Implementation
(read access only) IF_USMD_GOV_API

IF_USMD_READ_API IF_USMD_CONV_SOM_GOV_A
PI
(must not be used in method
READ_VALUE) IF_USMD_CREQUEST_API

Rule Service BAdI, IF_USMD_MODEL_EXT IF_USMD_MODEL

BRF+
(read access only) IF_USMD_GOV_API

IF_USMD_CONV_SOM_GOV_A
PI

IF_USMD_CREQUEST_API

5
As some APIs are not stateless, you must not consume the convenience, governance and change request
API at the same time. Depending on the MDG release, we recommend you use the governance API or the
convenience API for your purposes. Newly implemented MDG features are supported by the governance API
and the convenience API, but not necessarily by the change request API. The external model class interface
IF_USMD_MODEL_EXT can be used for read access only to avoid harming the state of other APIs. Since
the change request API is stateless, writing and reading data with the change request API and reading data
with the external model interface does not result in a conflict. The external model interface
IF_USMD_MODEL_EXT can be consumed in combination with the governance/convenience and the change
request API.
Since the governance API and the convenience API are not stateless, data changes within the abstraction
layer (BAdI, BRF+, access class) must be done using the corresponding interfaces. Additional data can be
read with the external model interface anyway. The following figures provide the concept of layering and
usage of the APIs.

Figure 1:

(Layered view: Convenience/Governance API)

Figure 2:

6
(Layered view: Change Request API)

These figures show that only the convenience API provides the application context with information.
Consumers of the governance API or the change request API have to take care of the application context
explicitly.

2 Introduction

The primary purpose of the governance API (CL_USMD_GOV_API) is to provide applications with a single
API for the consumption of the master data governance process. The governance API covers the complete
governance process for one model with multiple change requests. The convenience API
(CL_USMD_CONV_SOM_GOV_API) is based on the governance API and is optimized for single object
processing. It can handle only one change request at a time. The convenience API methods have an
extended implicit logic for easier consumption. The convenience API can be used as an API without UI, but it
is optimized for the interaction with the generic change request UIBB and the communicator UI component.
The figure below shows the layer concept of governance API and convenience API.

Figure 3:

The consumers of the governance API and the convenience API within SAP are Master Data Governance for
Customer (MDGC), Master Data Governance for Supplier (MDGS) and Master Data Governance for Material
(MDGM). Customer projects based on the convenience API or the governance API using data models from
MDGC, MDGS or MDGM (or copies of these models with no changes to the keys of the entities) are the best
preconditions.
Currently, both APIs offer the best consumable interface and can be recommended for customer use with
restrictions.

As a prerequisite for the consumption of the governance API or the convenience API functionality, the MDG
foundation business functions MDG_FOUNDATION for EhP5 and MDG_FOUNDATION_2 for EHP6 have to
be switched on. Applications using the governance process need to have an active data model and the
necessary customizing for workflow processing.

7
The purpose of the change request API (CL_USMD_CREQUEST_API) is to provide an API for a single
change request (per instance). The change request API provides less convenience for consumers, as they
have to take care of the change request object list themselves. In addition, the change request API provides
only a basic functionality for the governance process for simple data models. For complex data models, such
as material, customer or supplier, we recommend you consume the convenience API or the governance API.

Figure 4:

3 Limitations

The convenience API can handle exactly one change request at a time. However, one instance of the
convenience API can handle multiple change requests sequentially. For each change request, the buffers
have to be refreshed at the end of the change request processing, and the environment has to be set again
for the next change request to be processed. At the end of the sequential process, it is sufficient to call the
ABAP command commit work. Depending on the software release, the governance API and the convenience
API can handle editions and hierarchy maintenance (see table in section 1.1).

To reduce the risk of inconsistent programming against two APIs, the convenience API cannot be
instantiated if the governance API has been instantiated before, and vice versa. You cannot simultaneously
run both APIs. You can instantiate exactly one of these APIs at a time in one logical unit of work (LUW).
However, the convenience API consumes the governance API. The governance API as well as the
convenience API are instantiated as singletons. For one data model, one instance is provided. It is not
recommended to instantiate the governance API or the convenience API for different data models. The
abstraction layer cannot handle multiple data models simultaneously.

You should use one API (convenience API / governance API / [change request API]) for one data
model in one logical unit of work at a time. The external model interface can be used in parallel.

With the convenience API/governance API, it is not possible to activate a change request directly. Both APIs
strictly follow the governance process and use the workflow of the selected change request type. It is also
not possible to create a change request by referencing the convenience/governance API.

8
One instance of the change request API can handle only one change request. A consumer of this API has to
take care of the object list of a change request. Before checking or saving the data of one change request,
the change requests object list needs to be consistent. With the change request API, you can activate or
reject the change request by passing the governance process (workflow/dual-control-principle). In addition,
the change request API offers the possibility to move objects between different change requests or to split
one change request and to move objects to the new change request. With the change request API it is also
possible to create a change request using another change request as a template.

With the change request API, it is not possible to process hierarchies.

Parallel change request types cannot be used together with editions. It is only possible to set the flag for
parallel change requests in the Customizing activity Create Change Request Type if the edition type is
empty.

With the external interface for data models (IF_USMD_MODEL_EXT) it is not possible to change change
request data or entity data to ensure that the interface does not affect the state of any of the above
mentioned APIs. Regardless of the writing modes, the READ_CHAR_VALUE method triggers a flush (Cross
Entity Derivation) by default. With the external interface for data models, it is also possible to read
hierarchies.

The read API can be used separately to read entity data. It provides the change request ID as a parameter in
the interface. If the change request ID is not provided the current change request is determined. If no change
request is in the context no inactive data can be read. The read API is no direct replacement for the external
data model because the external data model provides more read modes and other parameter combinations.

9
4 Interfaces

Both the governance API as well as the convenience API have a static factory method, GET_INSTANCE, to
provide an instance of the requested API for a specific data model. The data model is mandatory for both
APIs. To request the API several times for one data model, the same instance of the API is provided by the
GET_INSTANCE method. GET_INSTANCE allows applications to inherit from this class and provide an own
implementation, which can provide additional methods for your convenience (for example, providing a
method to read a business partner with the structure BUT000 instead of reading the entity type BP_HEADER
with the ABAP statement REF TO DATA as the export parameter).

4.1 Governance API

The governance API CL_USMD_GOV_API (IF_USMD_GOV_API) includes other interfaces for better clarity,
since there are many methods involved. Nearly all methods of the governance API are documented in the
system. The functionality, the requirements and the expected results of a particular method are briefly
described in the method documentation.
The governance API is consumed by the convenience API and the data load process.

4.1.1 IF_USMD_GOV_API

The interface IF_USMD_GOV_API combines all necessary sub-interfaces to support the governance
process. The purpose of the sub-interfaces is to categorize the methods for their use. There is one event
defined for this interface that is raised as soon as the data has been changed due to derivations or data
enrichments.

4.1.2 IF_USMD_GOV_API_CR_DATA

The methods of this interface can be used for change request header data, change request notes, change
request attachments, and target systems.

4.1.3 IF_USMD_GOV_API_ENTITY

The methods of this interface can be used for data manipulation based on the governance process. There,
methods can be used for locking an entity, reading and writing entity data, etc.
The attributes of this interface are constants for creating data references of different kinds.

4.1.4 IF_USMD_GOV_API_PROCESS

The methods of this interface can be used to check the data of a change request and to create and forward
the workflow.

4.1.5 IF_USMD_GOV_API_SERVICES

The methods of this interface can be used to retrieve change requests by a specific entity as well as for step
type determination for a specific change request, and for the determination of permitted changes for a
change request in process.

4.1.6 IF_USMD_GOV_API_TRANS

This interface contains two methods that can be used to save the change requests and the corresponding
inactive entity data, and to refresh the master data governance buffer (change request data and entity data).

4.1.7 IF_USMD_GOV_API_CR_ACTION

This interface contains one method for the deletion of a change request in draft mode.

10
4.2 Convenience API

The Convenience API CL_USMD_CONV_SOM_GOV_API (IF_USMD_CONV_SOM_GOV_API) consumes

the functions and methods of the Governance API. It is designed for easy and convenient consumption of the
governance process within a specific object application. The application has to take care of the transactional
behaviour and application-specific data.
One important method is the SET_ENVIRONMENT method. As change requests might be created implicitly
because there is no explicit method for creating a change request, the change request ID or at least the
change request type needs to be set if you want to change an object for which no change request exists. For
example, the creation of a change request is triggered by locking the main entity of a data model and by
retrieving a temporary number for the main entity. Before an entity can be locked and a change request can
be created, the environment has to be set. If you want to create a new change request, the change request
type has to be defined.
Just like the governance API, the convenience API also includes other interfaces for better clarity.

4.2.1 IF_USMD_CONV_SOM_GOV_API

The interface IF_USMD_CONV_SOM_GOV_API combines all necessary sub-interfaces to support the

convenient governance process. The purpose of the sub-interfaces is to categorize the methods for their
use. There are three events defined for this interface that are raised in the following situations:
data has been changed due to derivations or data enrichments
data was saved
the key of an entity has changed during activation
The methods of this interface can be used for message handling, setting of the environment, and for
determining the processing details of an entity.

4.2.2 IF_USMD_CONV_SOM_GOV_CR

The methods of the interface IF_USMD_CONV_SOM_GOV_CR handle change request header data as well
as change request notes, attachments, and target systems. With the method
RETRIEVE_CREQUESTS_BY_ENTITY you can determine whether an entity is in process and which
change request is used for processing. Methods relevant to the workflow are also available, for example the
method SET_ACTION. It can be used to provide the action result of a workflow action to finalize processing,
to approve, or to reject.

4.2.3 IF_USMD_CONV_SOM_GOV_ENTITY

The methods of interface IF_USMD_CONV_SOM_GOV_ENTITY handle entity data. Entity data can be
enqueued. If you have not already set an existing change request ID as environment, enqueueing an entity
or acquiring a new temporary entity key creates a change request. Otherwise a change request type needs
to be provided. Data can be retrieved, written and checked. SAP also provides a method for field property
determination.

4.2.4 IF_USMD_CONV_SOM_GOV_TRANS

The two methods of interface IF_USMD_CONV_SOM_GOV_TRANS are relevant to transactional handling.

This interface contains the methods SAVE and REFRESH_BUFFERS.

4.2.5 IF_USMD_CONV_SOM_GOV_CR_ACTION

This interface IF_USMD_CONV_SOM_GOV_CR_ACTION contains only one method for the deletion of a
change request in draft mode (no workflow has been started so far for the relevant change request).

11
5 Simple Guide for Implementation
5.1 Sequence Diagram for Convenience API Usage

The next figure focuses on the convenience API and its usage. The governance API consumes the relevant
methods from the abstraction layer.
Figure 5:

5.2 Reading Entity Data

In a master data governance process, there are different sources of entity data. There is active data that can
be used for business processes, and there is inactive data that has to be checked and approved before

12
being used in business processes. Inactive data becomes active data when the data is approved and
activated, or inactive data is deleted when data creation or data change is declined.
All APIs (change request API, governance API, convenience API, and the external data model interface)
trigger a flush when a corresponding READ method is called for entity data. To avoid that a derivation cycle
is triggered, a flush can only be suppressed with the external data model interface. This is necessary to read
additional data during the derivation process.

5.2.1 Reading Entity Data - Governance API Behavior

Data from an object can be read from different sources during the governance process. If no change request
ID is specified, active data will be read. If a change request ID is specified, the inactive data will be read from
the change request by default. Reading active data can be enforced. The following matrix describes the rules
for reading entity data:

Figure 6:

During a round-trip within an API, the following sources of data are available:
the active data/ the snapshot data
the inactive data
the delta buffer content before a derivation

The delta buffer content (for example, just modified screen fields) is provided at the interface of the cross-
derivation or the check. The active or inactive data (before or during the derivation or the check) can be read
with the external data model interface IF_USMD_MODEL_EXT with the method READ_CHAR_VALUE and
the corresponding READ_MODE parameter. To avoid unnecessary flushes (derivations), the NO_FLUSH
parameter should be set to X.

When you use parallel change requests it is possible to have several change requests for one business
object. There is only one set of inactive data (as in a non-parallel change request). The change list
determines the inactive record that is assigned to a particular change request. When the system reads the
inactive data in the context of a particular change request it provides only the subset of inactive data
assigned to that change request.

Depending on the software release the governance API and the convenience API provide an additional
parameter (IV_EDITION) for reading entity data. If an edition is not provided the APIs will take the edition
assigned to the change request.
If neither an edition is provided nor a valid change request, no edition will be taken into account for reading
entity data. In this case all editions will be provided.

13
If a valid change request with a valid edition and an edition parameter is provided the edition parameter will
be used for reading entity data.

5.3 Writing Entity Data

Entity data changes are always persisted in the staging area. With all the APIs mentioned above, it is not
possible to write entity data to the active area immediately. The staging area contains the inactive data. It will
become active as soon as the change request is activated. Once the change request is finalized (finally
approved or finally rejected), the inactive data is deleted from the staging area. The staging area (generated
table content) can be accessed with the report USMD_DATA_MODEL using transaction SE38.

5.3.1 Write Strategies and Cross-Derivation

As of ERP EhP6, the abstraction layer (CL_USMD_MODEL) offers the following write modes for writing
entity data.

Write mode 1 writes the data directly to the MDF buffer without performing a cross-
derivation. No data is written to the delta buffer.
Write mode 2 writes the data for one entity type into the delta buffer first. The cross-
derivation is triggered immediately after writing the complete entity data for one entity.
Write mode 3 writes the entity data to the delta buffer only without an implicit
derivation. A flush has to be triggered to write the data from the delta buffer to the
MDF buffer.

Additionally, for write mode 2 and write mode 3, the following applies:
Before the data is transferred from the delta buffer to the MDF buffer, the cross-derivation (access class and
derive method of the RULE_SERVICE_BADI) is performed. The complete delta buffer is provided to those
interfaces.
A write mode is used for writing and deleting entity data. It is not recommended to mix write modes to
change entity data.
Writing entity data requires a fully specified entity: The entity type and the entity key is specified completely.

Checking and saving the data triggers a flush. To read the data, it is possible to suppress the flush (for
IF_USMD_MODEL_EXT~READ_CHAR_VALUE). A cross-derivation is performed only if entity data has
changed and, as a consequence, the delta buffer contains changed data. The reuse area access class is
called for each entity type depending on the data model (for flexibility data models, no access class is
available). The cross-derivation BAdI implementation is called once for all changed entity types. The
complete delta buffer content is provided to the access class and the BAdI implementation.
When you use parallel change requests it is be possible that derived entity types are not in the scope of the
change request type or the derived entity can be interlocked in another change request. In such a case the
derived data which cannot be added to the change list is filtered. Only these entities are derived that are in
scope and can be interlocked. The removed entities are listed in a warning message. If the derived data is
essential for data consistency a corresponding check should take care of this. The derivation provides no
error message in such a case.

14
Figure 7:
The figure below describes the flush in a sequence diagram in detail.

5.3.2 Writing Data with Convenience/Governance API

Data for an entity can be written if a change request has been created beforehand. If entity data is written
into a change request, the convenience API or the governance API determines whether it is necessary to
write a record into the object list of the change request. As a prerequisite for writing entity data into a change
request, the enqueue of the corresponding object has to be performed successfully. Entity data can only be
written when the enqueue has been successfully performed.

If the change request type is valid for parallel change requests an entry in the change list is made. For
parallel change requests it is necessary to have an assignment from the inactive data record to the change
request. The entity type to be written needs to be in scope of the change request type. Additionally, the entity
to be written must not be assigned to another change request.

When you want to write edition dependent data the system uses the edition that is assigned to the change
request. Edition dependent data can only be written if the change request has a valid edition assigned to it.

By default, the WRITE strategy of the governance API (and also of the convenience API) is set to write mode
3 (collect changes and derive data on flush). It is not possible to set a different WRITE strategy for the
governance API (write mode 1 = no derivation, write directly to change request buffer; write mode 2 = derive
directly after WRITE). A derivation (flush) is done implicitly by reading entity data, checking entity data and
saving the change request. However, the application can trigger a derivation when the

15
CONFIRM_ENTITY_DATA method is called. There is one exception for the convenience/governance API for
the write strategy: if the changeable key of an entity is changed, the change is written to the MDF at once
(write strategy 1).
When the write method of the convenience/governance API is called, the DERIVE_ENTITY exit of the
USMD_RULE_SERVICE BAdI is also called. The API does not enrich the data of the entity data. In addition,
the structure provided by the caller is used for the derivation. That means that only those attributes that are
part of the structure are available for a derivation (DERIVE_ENTITY). It is recommended to use the structure
(Key and Attributes) to write entity data. This ensures that the complete attribute set is available for a
derivation. It is recommended to provide the complete data (even if only one attribute is changed) to write an
entity. Otherwise it is recommended to read the entity data first, change the attribute(s), and write the
changed data. In this case, it is ensured that the complete attribute set is available for a derivation
(DERIVE_ENTITY) and that all attribute values are available.
Before the data is written to the abstraction layer, there are prerequisites that have to be fulfilled:
The object (main entity) needs to be locked.
The entity that you want to change is not interlocked by another change request.
The user has the authorization to create (if it is a new entity) or change (if it is an
existing entity) the entity.
For parallel change requests: The entity type is part of the change request type scope.
Once these checks have been successfully performed, the data is passed on to the abstraction layer using
write mode 3 (collect). Subsequently to writing the entity data to the abstraction layer, the object list of the
corresponding change request is updated (if necessary).

5.3.3 Writing Data with the Change Request API

The change request API does not offer an automatism to write the correct entities to the object list by writing
entity data. This has to be done by the API caller. The object has to be registered manually to the object list
in case entity data of that object is changed. The behavior for the entity derivation (DERIVE_ENTITY) is the
same as described in chapter 5.3.1. The cross-entity derivations are done when the data for one entity type
is written. The change request API uses write mode 2 (derive directly after write). The change request API
only checks the authorization for the provided entity and the existence of a corresponding entry in the
change request object list.

5.4 Authorization

5.4.1 Entity Authorization

While reading and writing entity data to a change request, an authority check is performed. To read entity
data, the authorization check is done for the display authorization (AUTH_ACT = 3). To write entity data, the
authorization check action depends on whether active data exists. If the entity data exists only as inactive
data (no active data is available), the authorization check verifies, if a user is authorized to create the entity
(AUTH_ACT = 1). If active data is available, the authorization check verifies, if a user is authorized to change
the entity (AUTH_ACT = 2).

5.4.2 Change Request Authorization

During the creation of a change request, the authorization action create (AUTH_ACT = 1) is necessary for
the relevant change request type.
To create a workflow, the CREATE (AUTH_ACT = 1) authorization for a specific change request type is
required. To complete a workflow step, the CHANGE (AUTH_ACT = 2) authorization for the change request
type is required.

16
To change the object list of the change request, it is not necessary to check the change request
authorization.

5.5 Code Example Create Airline (with governance API)

*&---------------------------------------------------------------------*
*& Report zcreatecarr_sf
*&---------------------------------------------------------------------*
*& This example creates a new change request. Along with the change
*& request, a new airline (carrier) is created.
*&
*& The exceptions raised by the governance API contain the error
*& messages and some other attributes. Therefore, it is possible to react
*& to the errors raised by the governance API.
*&---------------------------------------------------------------------*

REPORT zcreatecarr_sf.

DATA:
lo_gov_api TYPE REF TO if_usmd_gov_api,
lv_crequest_id TYPE usmd_crequest, "Change Request ID

lr_carr_key_str TYPE REF TO data, "Entity Carrier - key structure

lr_carr_key_tab TYPE REF TO data, "Entity Carrier - key table
lr_carr_data_str TYPE REF TO data, "Entity Carrier - data structure
lr_carr_data_tab TYPE REF TO data, "Entity Carrier - data table

ls_entity TYPE usmd_gov_api_s_ent_tabl,

lt_entity TYPE usmd_gov_api_ts_ent_tabl,

lt_messages TYPE usmd_t_message.

FIELD-SYMBOLS:
<ls_carr_key> TYPE any,
<lt_carr_key> TYPE ANY TABLE,
<ls_carr_data> TYPE any,
<lt_carr_data> TYPE ANY TABLE,
<value> TYPE any.

"1st: Create an instance of the governance API

TRY.
lo_gov_api = cl_usmd_gov_api=>get_instance( iv_model_name = 'SF' ).
CATCH cx_usmd_gov_api.
EXIT.
ENDTRY.

"2nd: Create all the data references needed to maintain the carrier entity
"Create a data reference of the key structure / table of entity CARR (Carrier)
lo_gov_api->create_data_reference(
EXPORTING iv_entity_name = 'CARR'
iv_struct = lo_gov_api->gc_struct_key
IMPORTING er_structure = lr_carr_key_str
er_table = lr_carr_key_tab ).

"Create a data reference of the key and attribute structure / table of

"entity CARR (Carrier)
lo_gov_api->create_data_reference(
EXPORTING iv_entity_name = 'CARR'
iv_struct = lo_gov_api->gc_struct_key_attr

17
 IMPORTING er_structure = lr_carr_data_str
er_table = lr_carr_data_tab ).

"Assign the created data references for carrier key and carrier data
"to field symbols
ASSIGN lr_carr_key_str->* TO <ls_carr_key>.
ASSIGN lr_carr_key_tab->* TO <lt_carr_key>.

ASSIGN lr_carr_data_str->* TO <ls_carr_data>.

ASSIGN lr_carr_data_tab->* TO <lt_carr_data>.

"3rd: Fill the key and data structure with values to create a new carrier
"The entity CARR only has key field CARR. The new carrier ID should be 'YZ'
ASSIGN COMPONENT 'CARR' OF STRUCTURE <ls_carr_key> TO <value>.
IF sy-subrc = 0.
<value> = 'YZ'.
INSERT <ls_carr_key> INTO TABLE <lt_carr_key>.
ELSE.
EXIT.
"Tough luck unfortunately, this field name is not part of the key structure
ENDIF.

"4th: Create a new change request using change request type and a
"description (required)
TRY.
lv_crequest_id = lo_gov_api->create_crequest(
iv_crequest_type = 'SFC01'
iv_description = 'Create new Carrier YZ' ).

CATCH cx_usmd_gov_api.
"Something went wrong while creating the change request (e.g. model blocked
"or change request type unknown).
EXIT.
ENDTRY.

"5th: Before making changes to an object, the object needs to be enqueued

"even if this is a creation scenario
TRY.
lo_gov_api->enqueue_entity( EXPORTING iv_crequest_id = lv_crequest_id
iv_entity_name = 'CARR'
it_data = <lt_carr_key> ).
CATCH cx_usmd_gov_api_entity_lock cx_usmd_gov_api.
EXIT.
"Tough luck
"something went wrong while enqueueing the entity (it could be a
"technical reason, or maybe the carrier is already interlocked?!
ENDTRY.

"6th: Provide some entity attributes (complete data structure)

MOVE-CORRESPONDING <ls_carr_key> TO <ls_carr_data>.

ASSIGN COMPONENT 'CARRNAME' OF STRUCTURE <ls_carr_data> TO <value>.

<value> = 'Fantasy Flight Airlines'.

ASSIGN COMPONENT 'CURRCODE' OF STRUCTURE <ls_carr_data> TO <value>.

<value> = 'USD'.

18
ASSIGN COMPONENT 'URL' OF STRUCTURE <ls_carr_data> TO <value>.
<value> = 'http://www.fantasyflight.com'.

INSERT <ls_carr_data> INTO TABLE <lt_carr_data>.

"7th: Write the entity data to the change request

TRY.
lo_gov_api->write_entity( EXPORTING iv_crequest_id = lv_crequest_id
iv_entity_name = 'CARR'
it_data = <lt_carr_data> ).
CATCH cx_usmd_gov_api_entity_write.
EXIT.
"Tough luck - might be that you have no authorization, or the entity is
"not enqueued or cannot be added to the object list of the change
"request
ENDTRY.

"8th: optionally, the entity data is read again... just to make sure everything
"went right.
TRY.
lo_gov_api->read_entity( EXPORTING iv_crequest_id = lv_crequest_id
iv_entity_name = 'CARR'
it_key = <lt_carr_key>
IMPORTING et_data = <lt_carr_data> ).
CATCH cx_usmd_gov_api_core_error cx_usmd_gov_api.
EXIT.
"Adequate Exception handling
ENDTRY.

"9th: The complete change request should be checked before it is saved

TRY.
lo_gov_api->check_crequest_data( iv_crequest_id = lv_crequest_id ).
"Collect the entities to be checked
ls_entity-entity = 'CARR'.
ls_entity-tabl = lr_carr_key_tab.
INSERT ls_entity INTO TABLE lt_entity.
"check the entity
lo_gov_api->check_complete_data(
EXPORTING iv_crequest_id = lv_crequest_id
it_key = lt_entity ).

CATCH cx_usmd_gov_api_core_error cx_usmd_gov_api.

"Possibility to handle the erroneous data or go on.
ENDTRY.

"10th: Save the change request (and the entity data of course)
TRY.
lo_gov_api->save( ).
"Save is done in draft mode by default so it is possible to
"save the change request even if change request data or
"entity data is not consistent.
CATCH cx_usmd_gov_api_core_error.
EXIT.
"Adequate Exception handling
ENDTRY.

"11th: At the end, it is necessary to clean the house

TRY.
lo_gov_api->dequeue_entity( EXPORTING iv_crequest_id = lv_crequest_id

19
 iv_entity_name = 'CARR'
it_data = <lt_carr_key> ).
lo_gov_api->dequeue_crequest(
EXPORTING iv_crequest_id = lv_crequest_id ).
CATCH cx_usmd_gov_api.
"Not a tragedy - maybe the workflow could not be processed properly after
"it was started
ENDTRY.

COMMIT WORK AND WAIT.

"12th: If everything is fine, the workflow can be started for

"the change request (this is like a 'submit')
TRY.
lo_gov_api->start_workflow( iv_crequest_id = lv_crequest_id ).
CATCH cx_usmd_gov_api_core_error.
"Adequate Exception handling
ENDTRY.

"Interested in the errors occured?

lt_messages = lo_gov_api->get_messages( ).

20
5.6 Code Example Change Flight Connection (with governance API)

*&---------------------------------------------------------------------*
*& Report ZCHANGEPFLI_SF
*&---------------------------------------------------------------------*
*& This example creates a new change request. Along with the change
*& request, an existing flight connection is changed. Additionally, a
*& dependent entity of type flight schedule is changed/created.
*&
*& The exceptions raised by the governance API contain the error
*& messages and some other attributes. Therefore, it is possible to react
*& to the errors raised by the governance API.
*&---------------------------------------------------------------------*

REPORT zchangepfli_sf.

DATA:
lo_gov_api TYPE REF TO if_usmd_gov_api,
lv_crequest_id TYPE usmd_crequest, "Change Request ID

lr_pfli_key_str TYPE REF TO data, "Entity Flight Connection - key structure

lr_pfli_key_tab TYPE REF TO data, "Entity Flight Connection - key table
lr_pfli_data_str TYPE REF TO data, "Entity Flight Connection - data structure
lr_pfli_data_tab TYPE REF TO data, "Entity Flight Connection - data table

lr_flight_key_str TYPE REF TO data, "Entity Flight - key structure

lr_flight_key_tab TYPE REF TO data, "Entity Flight - key table
lr_flight_data_str TYPE REF TO data, "Entity Flight - data structure
lr_flight_data_tab TYPE REF TO data, "Entity Flight - data table

ls_entity TYPE usmd_gov_api_s_ent_tabl,

lt_entity TYPE usmd_gov_api_ts_ent_tabl,

lt_messages TYPE usmd_t_message.

FIELD-SYMBOLS:
<ls_pfli_key> TYPE any,
<lt_pfli_key> TYPE INDEX TABLE,
<ls_pfli_data> TYPE any,
<lt_pfli_data> TYPE INDEX TABLE,

<ls_flight_key> TYPE any,

<lt_flight_key> TYPE INDEX TABLE,
<ls_flight_data> TYPE any,
<lt_flight_data> TYPE INDEX TABLE,

<value> TYPE any.

"1: Create an instance of the governance API

TRY.
lo_gov_api = cl_usmd_gov_api=>get_instance( iv_model_name = 'SF' ).
CATCH cx_usmd_gov_api.
EXIT.
ENDTRY.

"2: Create the data references needed to maintain the flight connection entity
"Create a data reference of the key structure/table of entity PFLI
lo_gov_api->create_data_reference(
EXPORTING iv_entity_name = 'PFLI'
iv_struct = lo_gov_api->gc_struct_key
IMPORTING er_structure = lr_pfli_key_str
er_table = lr_pfli_key_tab ).

21
lo_gov_api->create_data_reference(
EXPORTING iv_entity_name = 'PFLI'
iv_struct = lo_gov_api->gc_struct_key_attr
IMPORTING er_structure = lr_pfli_data_str
er_table = lr_pfli_data_tab ).

"Assign the created data references for the flight connection key to the field symbols
ASSIGN lr_pfli_key_str->* TO <ls_pfli_key>.
ASSIGN lr_pfli_key_tab->* TO <lt_pfli_key>.

ASSIGN COMPONENT 'CARR' OF STRUCTURE <ls_pfli_key> TO <value>.

<value> = 'LH'.
ASSIGN COMPONENT 'PFLI' OF STRUCTURE <ls_pfli_key> TO <value>.
<value> = '0401'.
INSERT <ls_pfli_key> INTO TABLE <lt_pfli_key>.

"Assign the created data references for the flight connection data to the field symbols
ASSIGN lr_pfli_data_str->* TO <ls_pfli_data>.
ASSIGN lr_pfli_data_tab->* TO <lt_pfli_data>.

"3: Create a new change request using change request type and a
description (required)
TRY.
lv_crequest_id = lo_gov_api->create_crequest(
iv_crequest_type = 'SFP02'
iv_description = 'Change Flight Connection LH 400' ).

CATCH cx_usmd_gov_api.
"Something went wrong while creating the change request (e.g. data model blocked
or change request type unknown).
EXIT.
ENDTRY.

"4: Before making changes to an object, the object needs to be enqueued.

TRY.
lo_gov_api->enqueue_entity( EXPORTING iv_crequest_id = lv_crequest_id
iv_entity_name = 'PFLI'
it_data = <lt_pfli_key> ).
CATCH cx_usmd_gov_api_entity_lock cx_usmd_gov_api.
EXIT.
ENDTRY.

"5: Read the flight connection data in order to do some changes

TRY.
lo_gov_api->read_entity( EXPORTING iv_crequest_id = lv_crequest_id
iv_entity_name = 'PFLI'
it_key = <lt_pfli_key>
IMPORTING et_data = <lt_pfli_data> ).
CATCH cx_usmd_gov_api_core_error cx_usmd_gov_api.
EXIT.
ENDTRY.

READ TABLE <lt_pfli_data> INDEX 1 INTO <ls_pfli_data>.

CLEAR <lt_pfli_data>.

ASSIGN COMPONENT 'ARRTIME' OF STRUCTURE <ls_pfli_data> TO <value>.

<value> = '075500'.
ASSIGN COMPONENT 'DEPTIME' OF STRUCTURE <ls_pfli_data> TO <value>.
<value> = '184000'.
INSERT <ls_pfli_data> INTO TABLE <lt_pfli_data>.

"6: Write the changes for the flight connection

TRY.
lo_gov_api->write_entity( EXPORTING iv_crequest_id = lv_crequest_id
iv_entity_name = 'PFLI'
it_data = <lt_pfli_data> ).

22
 CATCH cx_usmd_gov_api_entity_write.
EXIT. "Do better next time!
ENDTRY.

"7: Create all the data references needed to maintain the flight entity
"Create a data reference of the key structure/table of entity FLIGHT (Flight)
lo_gov_api->create_data_reference(
EXPORTING iv_entity_name = 'FLIGHT'
iv_struct = lo_gov_api->gc_struct_key
IMPORTING er_structure = lr_flight_key_str
er_table = lr_flight_key_tab ).

lo_gov_api->create_data_reference(
EXPORTING iv_entity_name = 'FLIGHT'
iv_struct = lo_gov_api->gc_struct_key_attr
IMPORTING er_structure = lr_flight_data_str
er_table = lr_flight_data_tab ).

"Assign the created data references for flight connection key to the field symbols
ASSIGN lr_flight_key_str->* TO <ls_flight_key>.
ASSIGN lr_flight_key_tab->* TO <lt_flight_key>.

MOVE-CORRESPONDING <ls_pfli_key> TO <ls_flight_key>.

INSERT <ls_flight_key> INTO TABLE <lt_flight_key>.

ASSIGN lr_flight_data_str->* TO <ls_flight_data>.

ASSIGN lr_flight_data_tab->* TO <lt_flight_data>.

"8: Read some flight data in order to do some changes

TRY.
lo_gov_api->read_entity( EXPORTING iv_crequest_id = lv_crequest_id
iv_entity_name = 'FLIGHT'
it_key = <lt_flight_key>
IMPORTING et_data = <lt_flight_data> ).
CATCH cx_usmd_gov_api_core_error cx_usmd_gov_api.
EXIT.
ENDTRY.

READ TABLE <lt_flight_data> INDEX 1 INTO <ls_flight_data>.

CLEAR <lt_flight_data>.

IF sy-subrc <> 0.
MOVE-CORRESPONDING <ls_flight_key> TO <ls_flight_data>.
ASSIGN COMPONENT 'FLDATE' OF STRUCTURE <ls_flight_data> TO <value>.
<value> = '31122013'.
ENDIF.

ASSIGN COMPONENT 'SEATSOCC' OF STRUCTURE <ls_flight_data> TO <value>.

<value> = '209'.

INSERT <ls_flight_data> INTO TABLE <lt_flight_data>.

"9: Write the changes for the flight

TRY.
lo_gov_api->write_entity( EXPORTING iv_crequest_id = lv_crequest_id
iv_entity_name = 'FLIGHT'
it_data = <lt_flight_data> ).
CATCH cx_usmd_gov_api_entity_write.
EXIT. "Do better next time!
ENDTRY.

"10: The complete change request should be checked before it is saved

TRY.
lo_gov_api->check_crequest_data( iv_crequest_id = lv_crequest_id ).
"Collect the entities to be checked
ls_entity-entity = 'PFLI'.

23
 ls_entity-tabl = lr_pfli_key_tab.
INSERT ls_entity INTO TABLE lt_entity.
"Check the entity
lo_gov_api->check_complete_data(
EXPORTING iv_crequest_id = lv_crequest_id
it_key = lt_entity ).

CATCH cx_usmd_gov_api_core_error cx_usmd_gov_api.

"Handle the erroneous data or go on.
ENDTRY.

"11: Save the change request (and the entity data, of course)
TRY.
lo_gov_api->save( ).
"Save is done in draft mode by default so it is possible to
save the change request even if the change request data or
the entity data is not consistent.
CATCH cx_usmd_gov_api_core_error.
EXIT.
"Adequate exception handling
ENDTRY.

"12: At the end, it is necessary to clean the house

TRY.
lo_gov_api->dequeue_entity( EXPORTING iv_crequest_id = lv_crequest_id
iv_entity_name = 'PFLI'
it_data = <lt_pfli_key> ).
lo_gov_api->dequeue_crequest( EXPORTING iv_crequest_id = lv_crequest_id ).
CATCH cx_usmd_gov_api.
"Adequate exception handling
ENDTRY.

COMMIT WORK AND WAIT.

"13: If everything is correct, the workflow can be started for

the change request (this is like a 'submit')
TRY.
lo_gov_api->start_workflow( iv_crequest_id = lv_crequest_id ).
CATCH cx_usmd_gov_api_core_error.
"Adequate exception handling
ENDTRY.

"Interested in the messages occurred?

lt_messages = lo_gov_api->get_messages( ).

Copyright
2016 SAP SE or an SAP SE 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.
The information contained herein may be changed without prior notice.
Some software products marketed by SAP SE and its distributors contain proprietary software components
of other software vendors. National product specifications may vary.
These materials are provided by SAP SE and its affiliated companies (SAP SE Group) for informational
purposes only, without representation or warranty of any kind, and SAP SE Group shall not be liable for
errors or omissions with respect to the materials. The only warranties for SAP SE Group products and
services are those that are set forth in the express warranty statements accompanying such products and
services, if any. Nothing herein should be construed as constituting an additional warranty.
SAP SE and other SAP SE products and services mentioned herein as well as their respective logos are
trademarks or registered trademarks of SAP SE in Germany and other countries.

24
Please see
http://www.sap.com/corporate-en/legal/copyright/index.epx#trademark
for additional trademark information and notices.

25