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

Master Data Governance

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

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.

Convenience API CL_USMD_CONV_SOM_GOV_API IF_USMD_CONV_SOM_GOV_API

Programming interface for 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.




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.






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







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 IF_USMD_CONV_SOM_GOV_API or IF_USMD_CREQUEST_API 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 IF_USMD_CONV_SOM_GOV_API IF_USMD_CREQUEST_API

Rule Service BAdI, BRF+

IF_USMD_MODEL_EXT (read access only)

IF_USMD_MODEL IF_USMD_GOV_API IF_USMD_CONV_SOM_GOV_API IF_USMD_CREQUEST_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 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 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.

Documents

Master Data Governance Application Programming Interface Guide