Master Data Governance Application Programming Interface Guide

Master Data Governance
Application Programming Interface Guide

Marcus Galleck

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 ......................................................................................................................... 4
2 INTRODUCTION ............................................................................................................................... 5
3 LIMITATIONS .................................................................................................................................... 6
4 INTERFACES .................................................................................................................................... 8
4.1 Governance API ............................................................................................................................... 8
4.1.1 IF_USMD_GOV_API ......................................................................................................................... 8
4.1.2 IF_USMD_GOV_API_CR_DATA ...................................................................................................... 8
4.1.3 IF_USMD_GOV_API_ENTITY .......................................................................................................... 8
4.1.4 IF_USMD_GOV_API_PROCESS ..................................................................................................... 8
4.1.5 IF_USMD_GOV_API_SERVICES ..................................................................................................... 8
4.1.6 IF_USMD_GOV_API_TRANS ........................................................................................................... 8
4.1.7 IF_USMD_GOV_API_CR_ACTION .................................................................................................. 8
4.2 Convenience API ............................................................................................................................. 8
4.2.1 IF_USMD_CONV_SOM_GOV_API .................................................................................................. 9
4.2.2 IF_USMD_CONV_SOM_GOV_CR ................................................................................................... 9
4.2.3 IF_USMD_CONV_SOM_GOV_ENTITY ........................................................................................... 9
4.2.4 IF_USMD_CONV_SOM_GOV_TRANS ............................................................................................ 9
4.2.5 IF_USMD_CONV_SOM_GOV_CR_ACTION ................................................................................... 9
5 SIMPLE GUIDE FOR IMPLEMENTATION ....................................................................................... 9
5.1 Sequence Diagram for Convenience API Usage .......................................................................... 9
5.2 Reading Entity Data ....................................................................................................................... 10
5.2.1 Reading Entity Data - Governance API Behavior ............................................................................ 10
5.3 Writing Entity Data ......................................................................................................................... 11
5.3.1 Write Strategies and Cross-Derivation ............................................................................................ 11
5.3.2 Writing Data with Convenience/Governance API ............................................................................ 13
5.3.3 Writing Data with the Change Request API ..................................................................................... 14
5.4 Authorization .................................................................................................................................. 14
5.4.1 Entity Authorization .......................................................................................................................... 14
5.4.2 Change Request Authorization ........................................................................................................ 14
5.5 Code Example Create Airline (with governance API) ............................................................. 14
5.6 Code Example Change Flight Connection (with governance API) ........................................ 18


3

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
API
CL_USMD_CREQUEST_API
IF_USMD_CREQUEST_API
Programming interface for
CR Processing. One
Instance per change request.
Administration of change
request object list by
consumer.
External use model
API
IF_USMD_MODEL_EXT
CL_USMD_MODEL_EXT
Reading entity and hierarchy
data.

EhP 6

Change Request
API
No further development.
Governance API CL_USMD_GOV_API
IF_USMD_GOV_API
governance process. One
instance per MDG model.
Multiple CR processing
within one instance for one
model. Limited use for
models using editions.
Convenience API CL_USMD_CONV_SOM_GOV_API
IF_USMD_CONV_SOM_GOV_API
governance process
optimized for single object
processing and single object
processing UIs. No support
for models using editions.
App Context API CL_USMD_APP_CONTEXT
IF_USMD_APP_CONTEXT
Programming interface
consumed mainly by
convenience API. Stores and
calculates context data.
External use model
API
IF_USMD_MODEL_EXT
CL_USMD_MODEL_EXT
data.

MDG 6.1 Change Request
API
Governance API CL_USMD_GOV_API
IF_USMD_GOV_API
Support of foreign key
entities.
Support of foreign key
entities.
IF_USMD_APP_CONTEXT
External use model
API
IF_USMD_MODEL_EXT
CL_USMD_MODEL_EXT
data.

MDG 7.0 Change Request
API
MDG 7.0 Governance API CL_USMD_GOV_API
IF_USMD_GOV_API
Support of new edition
management and parallel
change requests
change requests
IF_USMD_APP_CONTEXT
change requests
External use model
API
IF_USMD_MODEL_EXT
CL_USMD_MODEL_EXT
Support for reading data
from parallel change
requests

4

1.2 Usage of MDG APIs

Use Case Allowed usage Forbidden usage
Build UI application,
Inbound/Remote
governed process
IF_USMD_GOV_API or
or

IF_USMD_MODEL_EXT
(read access only)
IF_USMD_MODEL
Access Class
Implementation
IF_USMD_MODEL_EXT
(read access only)
IF_USMD_MODEL
IF_USMD_GOV_API
Rule Service BAdI,
BRF+
IF_USMD_MODEL_EXT
(read access only)
IF_USMD_MODEL
IF_USMD_GOV_API

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:

5

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

6

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.

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


7

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


8

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.

4.2 Convenience API


9

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

10

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

11

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

12

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.


13

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

14

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

15

*& 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)
EXPORTING iv_entity_name = 'CARR'
iv_struct = lo_gov_api->gc_struct_key_attr
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'.

16

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

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

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
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
it_key = <lt_carr_key>
IMPORTING et_data = <lt_carr_data> ).

17

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

"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.
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
it_data = <lt_carr_key> ).
lo_gov_api->dequeue_crequest(
EXPORTING iv_crequest_id = lv_crequest_id ).
"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 ).
ENDTRY.

"Interested in the errors occured?
lt_messages = lo_gov_api->get_messages( ).


18

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' ).
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
EXPORTING iv_entity_name = 'PFLI'
IMPORTING er_structure = lr_pfli_key_str
er_table = lr_pfli_key_tab ).


19

EXPORTING iv_entity_name = 'PFLI'
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' ).

"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.
it_key = <lt_pfli_key>
IMPORTING et_data = <lt_pfli_data> ).
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.
it_data = <lt_pfli_data> ).

20

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)
EXPORTING iv_entity_name = 'FLIGHT'
IMPORTING er_structure = lr_flight_key_str
er_table = lr_flight_key_tab ).

EXPORTING iv_entity_name = 'FLIGHT'
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.
iv_entity_name = 'FLIGHT'
it_key = <lt_flight_key>
IMPORTING et_data = <lt_flight_data> ).
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.
iv_entity_name = 'FLIGHT'
it_data = <lt_flight_data> ).
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

21

ls_entity-entity = 'PFLI'.
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 ).

"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.
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
it_data = <lt_pfli_key> ).
lo_gov_api->dequeue_crequest( EXPORTING iv_crequest_id = lv_crequest_id ).
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 ).
ENDTRY.

"Interested in the messages occurred?
lt_messages = lo_gov_api->get_messages( ).

Copyright
Copyright 2014 SAP AG. 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 AG.
The information contained herein may be changed without prior notice.
Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors.
Microsoft, Windows, Excel, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation.
IBM, DB2, DB2 Universal Database, System i, System i5, System p, System p5, System x, System z, System z10, System z9, z10, z9,
iSeries, pSeries, xSeries, zSeries, eServer, z/VM, z/OS, i5/OS, S/390, OS/390, OS/400, AS/400, S/390 Parallel Enterprise Server,
PowerVM, Power Architecture, POWER6+, POWER6, POWER5+, POWER5, POWER, OpenPower, PowerPC, BatchPipes,
BladeCenter, System Storage, GPFS, HACMP, RETAIN, DB2 Connect, RACF, Redbooks, OS/2, Parallel Sysplex, MVS/ESA, AIX,
Intelligent Miner, WebSphere, Netfinity, Tivoli and Informix are trademarks or registered trademarks of IBM Corporation.
Linux is the registered trademark of Linus Torvalds in the U.S. and other countries.
Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems
Incorporated in the United States and/or other countries.
Oracle is a registered trademark of Oracle Corporation.
UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group.
Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of
Citrix Systems, Inc.
HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C, World Wide Web Consortium, Massachusetts
Institute of Technology.
Java is a registered trademark of Sun Microsystems, Inc.
JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by
Netscape.
SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP Business ByDesign, and other SAP products and services mentioned
herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries.
Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and
other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered
trademarks of Business Objects S.A. in the United States and in other countries. Business Objects is an SAP company.
All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document
serves informational purposes only. National product specifications may vary.
These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP
Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or
omissions with respect to the materials. The only warranties for SAP 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.

Master Data Governance Application Programming Interface Guide

Caricato da

Informazioni sul documento

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Master Data Governance Application Programming Interface Guide

Caricato da

Copyright:

Formati disponibili

Master Data Governance

Application Programming Interface Guide

Potrebbero piacerti anche