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

5.3

Reading Entity Data - Governance API Behavior ......................................................................................... 13

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

IF_USMD_MODEL_EXT

Reading entity and hierarchy data.

External use model API

CL_USMD_MODEL_EXT

EhP 6

Change Request API

CL_USMD_CREQUEST_API

No further development.

IF_USMD_CREQUEST_API Governance API

CL_USMD_GOV_API IF_USMD_GOV_API

Convenience API

CL_USMD_CONV_SOM_GOV_API IF_USMD_CONV_SOM_GOV_API

App Context API

CL_USMD_APP_CONTEXT IF_USMD_APP_CONTEXT

External use model API

IF_USMD_MODEL_EXT

Programming interface for governance process. One instance per MDG model. Multiple CR processing within one instance for one model. Limited use for models using editions. Programming interface for governance process optimized for single object processing and single object processing UIs. No support for models using editions. Programming interface consumed mainly by convenience API. Stores and calculates context data. Reading entity and hierarchy data.

CL_USMD_MODEL_EXT

MDG 6.1

Change Request API

CL_USMD_CREQUEST_API

No further development.

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 API

IF_USMD_MODEL_EXT

Reading entity and hierarchy data.

CL_USMD_MODEL_EXT

MDG 7.0

Change Request API

CL_USMD_CREQUEST_API

No further development.

IF_USMD_CREQUEST_API MDG 7.0

Governance API

CL_USMD_GOV_API IF_USMD_GOV_API

Convenience API

CL_USMD_CONV_SOM_GOV_API IF_USMD_CONV_SOM_GOV_API

App Context API

CL_USMD_APP_CONTEXT IF_USMD_APP_CONTEXT

External use model API

IF_USMD_MODEL_EXT CL_USMD_MODEL_EXT

MDG 8.0

Change Request API

CL_USMD_CREQUEST_API

Support of new edition management and parallel change requests Support of new edition management and parallel change requests Support of new edition management and parallel change requests Support for reading data from parallel change requests

No further development.

IF_USMD_CREQUEST_API MDG 8.0

Governance API

Convenience API

CL_USMD_GOV_API

Consumption of Read API

IF_USMD_GOV_API

Hierarchy maintenance

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 API

IF_USMD_MODEL_EXT

No further development.

CL_USMD_MODEL_EXT

MDG 9.0

Read API

CL_USMD_READ_API

Enhanced entity data buffer

Change Request API

CL_USMD_CREQUEST_API

No further development.

IF_USMD_CREQUEST_API

4

MDG 9.0

Governance API

No further development

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

IF_USMD_MODEL_EXT

No further development.

CL_USMD_MODEL_EXT Read API

1.2

CL_USMD_READ_API

Change of buffer concept

Usage of MDG APIs

Use Case

Allowed usage

Forbidden usage

Build UI application, Inbound/Remote governed process

IF_USMD_GOV_API or

IF_USMD_MODEL

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 Implementation

Rule Service BAdI, BRF+

IF_USMD_MODEL_EXT

IF_USMD_MODEL

(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

IF_USMD_MODEL_EXT

IF_USMD_MODEL

(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 request’s 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 crossderivation 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 crossderivation. No data is written to the delta buffer.



Write mode 2 writes the data for one entity type into the delta buffer first. The crossderivation 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 5.4.1

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

TYPE REF TO if_usmd_gov_api, TYPE usmd_crequest, "Change Request ID

lr_carr_key_str lr_carr_key_tab lr_carr_data_str lr_carr_data_tab

TYPE TYPE TYPE TYPE

ls_entity lt_entity

TYPE usmd_gov_api_s_ent_tabl, TYPE usmd_gov_api_ts_ent_tabl,

lt_messages

TYPE usmd_t_message.

REF REF REF REF

TO TO TO TO

data, data, data, data,

"Entity "Entity "Entity "Entity

Carrier Carrier Carrier Carrier

-

key structure key table data structure data table

FIELD-SYMBOLS:

TYPE TYPE TYPE TYPE TYPE

any, ANY TABLE, any, ANY TABLE, 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

IMPORTING er_structure er_table

= lo_gov_api->gc_struct_key = lr_carr_key_str = 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 er_table

= lr_carr_data_str = lr_carr_data_tab ).

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

ASSIGN lr_carr_data_str->* TO . ASSIGN lr_carr_data_tab->* TO . "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 TO . IF sy-subrc = 0. = 'YZ'. INSERT INTO TABLE . 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 = ). 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 TO .

ASSIGN COMPONENT 'CARRNAME' OF STRUCTURE TO . = 'Fantasy Flight Airlines'.

ASSIGN COMPONENT 'CURRCODE' OF STRUCTURE TO . = 'USD'.

18

ASSIGN COMPONENT 'URL' OF STRUCTURE TO . = 'http://www.fantasyflight.com'.

INSERT INTO TABLE . "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 = ). 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 = IMPORTING et_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 = ). 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 lv_crequest_id

TYPE REF TO if_usmd_gov_api, TYPE usmd_crequest, "Change Request ID

lr_pfli_key_str lr_pfli_key_tab lr_pfli_data_str lr_pfli_data_tab

TYPE TYPE TYPE TYPE

REF REF REF REF

TO TO TO TO

data, data, data, data,

"Entity "Entity "Entity "Entity

Flight Flight Flight Flight

Connection Connection Connection Connection

lr_flight_key_str lr_flight_key_tab lr_flight_data_str lr_flight_data_tab

TYPE TYPE TYPE TYPE

REF REF REF REF

TO TO TO TO

data, data, data, data,

"Entity "Entity "Entity "Entity

Flight Flight Flight Flight

-

ls_entity lt_entity

TYPE usmd_gov_api_s_ent_tabl, TYPE usmd_gov_api_ts_ent_tabl,

lt_messages

TYPE usmd_t_message.

FIELD-SYMBOLS:

TYPE TYPE TYPE TYPE

any, INDEX TABLE, any, INDEX TABLE,



TYPE TYPE TYPE TYPE

any, INDEX TABLE, any, INDEX TABLE,



TYPE any.

-

key structure key table data structure data table

key structure key table data structure data table

"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 . ASSIGN lr_pfli_key_tab->* TO . ASSIGN COMPONENT 'CARR' OF STRUCTURE TO . = 'LH'. ASSIGN COMPONENT 'PFLI' OF STRUCTURE TO . = '0401'. INSERT INTO TABLE . "Assign the created data references for the flight connection data to the field symbols ASSIGN lr_pfli_data_str->* TO . ASSIGN lr_pfli_data_tab->* TO . "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 TRY. lo_gov_api->enqueue_entity( EXPORTING iv_crequest_id iv_entity_name it_data CATCH cx_usmd_gov_api_entity_lock cx_usmd_gov_api. EXIT. ENDTRY. "5: Read the flight connection data in order to do some TRY. lo_gov_api->read_entity( EXPORTING iv_crequest_id iv_entity_name it_key IMPORTING et_data CATCH cx_usmd_gov_api_core_error cx_usmd_gov_api. EXIT. ENDTRY.

to be enqueued. = lv_crequest_id = 'PFLI' = ).

changes = = = =

lv_crequest_id 'PFLI' ).

READ TABLE INDEX 1 INTO . CLEAR . ASSIGN COMPONENT 'ARRTIME' OF STRUCTURE TO . = '075500'. ASSIGN COMPONENT 'DEPTIME' OF STRUCTURE TO . = '184000'. INSERT INTO TABLE . "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 = ).

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 . ASSIGN lr_flight_key_tab->* TO . MOVE-CORRESPONDING TO . INSERT INTO TABLE . ASSIGN lr_flight_data_str->* TO . ASSIGN lr_flight_data_tab->* TO . "8: Read some flight data in order to do some changes TRY. lo_gov_api->read_entity( EXPORTING iv_crequest_id iv_entity_name it_key IMPORTING et_data CATCH cx_usmd_gov_api_core_error cx_usmd_gov_api. EXIT. ENDTRY.

= = = =

lv_crequest_id 'FLIGHT' ).

READ TABLE INDEX 1 INTO . CLEAR . IF sy-subrc 0. MOVE-CORRESPONDING TO . ASSIGN COMPONENT 'FLDATE' OF STRUCTURE TO . = '31122013'. ENDIF. ASSIGN COMPONENT 'SEATSOCC' OF STRUCTURE TO . = '209'. INSERT INTO TABLE . "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 = ). 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 iv_entity_name it_data lo_gov_api->dequeue_crequest( EXPORTING iv_crequest_id CATCH cx_usmd_gov_api. "Adequate exception handling ENDTRY.

= = = =

lv_crequest_id 'PFLI' ). lv_crequest_id ).

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