How to write a MDG API Programming using these Basic Content to Know on API

Purpose : In Detials MDG API Technical Concepts like Change Request API , External Mode API , Governance API ,Convenience API and Finally Context API.

Below are the API with their Purpose in a tabular format to understand easily

Store and provide context data using this class cl_usmd_app_context.

1.	CL_USMD_APP_CONTEXT

    TRY.
        DATA(lo_context) = cl_usmd_app_context=>get_context( ).
    ENDTRY.

    IF lo_context IS BOUND.
*--- Type of Change Request
      lo_context->get_attributes(
        IMPORTING
           ev_crequest_type  = DATA(lv_ctype)
           ev_crequest_step  = DATA(lv_wf_step) ).
    ENDIF.


    DATA: eo_context        TYPE REF TO if_usmd_app_context, "Application Context
          eo_model          TYPE REF TO if_usmd_model_ext, "USMD Model
          ev_parent_process TYPE usmd_process, "Process Type
          ev_process        TYPE usmd_process, "Process
          ev_wi_id          TYPE sww_wiid, "Workitem ID
          ev_crequest_id    TYPE usmd_crequest, "Change Request ID
          ev_crequest_type  TYPE usmd_crequest_type, "Change Request Type
          ev_crequest_step  TYPE usmd_crequest_appstep, "CR App Step
          ev_crequest_index TYPE usmd_crequest_wfindex. "CR Index
*         lv_entity         TYPE usmd_entity VALUE 'BP_CENTRL'.
    CALL METHOD cl_usmd_app_context=>get_context
      RECEIVING
        eo_context = eo_context.

    CALL METHOD eo_context->get_attributes
      IMPORTING
        eo_model          = eo_model
        ev_parent_process = ev_parent_process
        ev_process        = ev_process
        ev_wi_id          = ev_wi_id
        ev_crequest_id    = ev_crequest_id
        ev_crequest_type  = ev_crequest_type
        ev_crequest_step  = ev_crequest_step
        ev_crequest_index = ev_crequest_index.

As Governance API but using single change request using this class cl_usmd_conv_som_gov_api.

2.	CL_USMD_CONV_SOM_GOV_API
Example to read an Account group 
DATA:
      lr_gov_api     TYPE REF TO if_usmd_conv_som_gov_api,
      lrs_data       TYPE REF TO data,
      ls_entity_key  TYPE usmd_gov_api_s_ent_tabl,
      lt_entity_key  TYPE usmd_gov_api_ts_ent_tabl,
      ls_entity_data TYPE usmd_gov_api_s_ent_tabl,
      lt_entity_data TYPE usmd_gov_api_ts_ent_tabl,
      lt_object_dg   TYPE usmd_t_crequest_entity,
      lr_object_dg   TYPE REF TO usmd_s_crequest_entity,
      lv_bp          TYPE bu_businesspartner,
      lwa_ktokd      TYPE /mdgbpx/_s_bp_pp_bp_cusgen.

    FIELD-SYMBOLS:
      <lt_ent_data> TYPE ANY TABLE,
      <ls_ent_data> TYPE any,
      <ls_key>      TYPE any,
      <ls_field>    TYPE any,
      <bp_header>   TYPE data,
      <lv_ktokd>    TYPE ktokd.

    lr_gov_api = cl_usmd_conv_som_gov_api=>get_instance( 'BP' ).

    IF lr_gov_api->mv_crequest_id IS INITIAL OR lr_gov_api->mv_crequest_id = iv_cr_number.
      lr_gov_api->set_environment( iv_crequest_id = iv_cr_number ).
      lr_gov_api->get_object_list( IMPORTING et_object_list_db_style = lt_object_dg[] ).

      READ TABLE lt_object_dg REFERENCE INTO lr_object_dg
        WITH KEY usmd_entity = 'BP_HEADER'.
      IF sy-subrc = 0.
        lv_bp = lr_object_dg->usmd_value.
      ENDIF.

      CLEAR:
        ls_entity_key, ls_entity_data.
      REFRESH:
        lt_entity_key, lt_entity_data.

      ls_entity_key-entity = 'BP_CUSGEN'.
      lr_gov_api->get_entity_structure( EXPORTING iv_entity_name = ls_entity_key-entity
                                                  iv_struct_type = lr_gov_api->gc_struct_key
                                        IMPORTING er_table       = ls_entity_key-tabl ).

      ASSIGN ls_entity_key-tabl->* TO <lt_ent_data>.
      CREATE DATA lrs_data LIKE LINE OF <lt_ent_data>.
      ASSIGN lrs_data->* TO <ls_ent_data>.

      ASSIGN COMPONENT 'BP_HEADER' OF STRUCTURE <ls_ent_data> TO <bp_header>.
      <bp_header> = lv_bp.
      INSERT <ls_ent_data> INTO TABLE <lt_ent_data>.
      INSERT ls_entity_key INTO TABLE lt_entity_key.
      lt_entity_data[] = lr_gov_api->read_entity_data( it_entity_keys = lt_entity_key[] ).

      READ TABLE lt_entity_data INTO ls_entity_key
        WITH TABLE KEY entity = ls_entity_key-entity.
      ASSIGN ls_entity_key-tabl->* TO <lt_ent_data>.
      CREATE DATA lrs_data LIKE LINE OF <lt_ent_data>.
      ASSIGN lrs_data->* TO <ls_ent_data>.
      LOOP AT <lt_ent_data> INTO <ls_ent_data>.
        ASSIGN COMPONENT 'KTOKD' OF STRUCTURE <ls_ent_data> TO <lv_ktokd>.
        IF <lv_ktokd> IS ASSIGNED .

          lwa_ktokd = <ls_ent_data>.

          APPEND lwa_ktokd TO lt_ktokd.
        ENDIF.
      ENDLOOP.
    ENDIF.

Handling of several change request and entity data .

3.	CL_USMD_GOV_API
DATA :
      lr_crequest                 TYPE REF TO if_usmd_crequest_api,
      lr_gov_api                  TYPE REF TO if_usmd_gov_api,
      t_crequest_obj_list         TYPE   usmd_gov_api_t_ent_struc,
      lr_adpostal_detail_key_str  TYPE REF TO data,
      lr_adpostal_detail_key_tab  TYPE REF TO data,
      lr_adpostal_detail_data_str TYPE REF TO data,
      lr_adpostal_detail_data_tab TYPE REF TO data,
      w_crequest_obj_list         TYPE   usmd_gov_api_s_ent_struc,
      ls_crequest                 TYPE usmd_s_crequest.

    FIELD-SYMBOLS :
      <fs_t_adpostal_detail_key>  TYPE ANY TABLE,
      <fs_w_adpostal_detail_key>  TYPE any,
      <fs_t_adpostal_detail_data> TYPE INDEX TABLE,
      <fs_w_adpostal_detail_data> TYPE any.

    "Get API Instance:
    CALL METHOD cl_usmd_crequest_api=>get_instance
      EXPORTING
        iv_crequest          = im_cr_id
      IMPORTING
        re_inst_crequest_api = lr_crequest.

    "CR Request Details:
    CALL METHOD lr_crequest->read_crequest
      IMPORTING
        es_crequest = ls_crequest.

    ex_crequest = ls_crequest.

    "Get Instance of Model:
    lr_gov_api = cl_usmd_gov_api=>get_instance( iv_model_name = im_modelname ).

    "Get Object List:
    lr_gov_api->get_object_list( EXPORTING iv_crequest_id = im_cr_id
                                 IMPORTING et_object_list = t_crequest_obj_list ).

    "Check with Entity Type:
    READ TABLE t_crequest_obj_list INTO w_crequest_obj_list WITH KEY entity = im_entity.
    IF sy-subrc <> 0.
*      RETURN.
    ENDIF.

    CLEAR : lr_adpostal_detail_key_str,lr_adpostal_detail_key_tab.

    "Get KeyStr and KeyTab:
    lr_gov_api->create_data_reference( EXPORTING iv_entity_name = im_entity
                                                 iv_struct      = lr_gov_api->gc_struct_key
                                       IMPORTING er_structure   = lr_adpostal_detail_key_str
                                                 er_table       = lr_adpostal_detail_key_tab ).
    "Get AdPostal data:
    lr_gov_api->create_data_reference( EXPORTING iv_entity_name = im_entity
                                       iv_struct      = lr_gov_api->gc_struct_key_attr
                             IMPORTING er_structure   = lr_adpostal_detail_data_str
                                       er_table       = lr_adpostal_detail_data_tab ).

    ASSIGN lr_adpostal_detail_key_str->*  TO <fs_w_adpostal_detail_key>.
    ASSIGN lr_adpostal_detail_key_tab->*  TO <fs_t_adpostal_detail_key>.
    ASSIGN w_crequest_obj_list-r_struc->* TO <fs_w_adpostal_detail_key>.
    INSERT <fs_w_adpostal_detail_key> INTO TABLE <fs_t_adpostal_detail_key>.
    ASSIGN lr_adpostal_detail_data_str->*  TO <fs_w_adpostal_detail_data>.
    ASSIGN lr_adpostal_detail_data_tab->* TO <fs_t_adpostal_detail_data>.

    "AD_postal Detail Data:
    TRY.
        lr_gov_api->read_entity( EXPORTING iv_entity_name   = im_entity
                                           it_key           = <fs_t_adpostal_detail_key>
                                           iv_crequest_id   = im_cr_id
                                           if_active_data   = abap_false
                                 IMPORTING et_data          = <fs_t_adpostal_detail_data> ).

      CATCH cx_usmd_gov_api_core_error cx_usmd_gov_api.
*          EXIT.
    ENDTRY.
    IF <fs_t_adpostal_detail_data> IS NOT INITIAL.
      "Read Index 1.
      READ TABLE <fs_t_adpostal_detail_data> INDEX 1 INTO <fs_w_adpostal_detail_data>.
      CLEAR <fs_t_adpostal_detail_data>.
      IF sy-subrc EQ 0 .
        ex_cr_data = <fs_w_adpostal_detail_data>.
      ENDIF.
    ENDIF.

Reading Entity Data using this External Mode API

4.	CL_USMD_MODEL_EXT
READ  Entity data
  DATA: lo_model     TYPE REF TO if_usmd_model_ext,
          ls_sel       TYPE usmd_s_sel,
          lt_sel       TYPE usmd_ts_sel,
          lt_objlist   TYPE usmd_t_crequest_entity,
          ls_objlist   TYPE usmd_s_crequest_entity,
          lv_structure TYPE REF TO data.

    FIELD-SYMBOLS : <lt_data> TYPE ANY TABLE.

    IF iv_crequest IS INITIAL.
      RETURN.
    ELSE.
      IF io_model IS INITIAL.
        CALL METHOD cl_usmd_model_ext=>get_instance
          EXPORTING
            i_usmd_model = '0G'
          IMPORTING
            eo_instance  = lo_model.
      ELSE.
        lo_model = io_model.
      ENDIF.

      CLEAR: ls_sel, lt_sel.
      ls_sel-fieldname = usmd0_cs_fld-crequest.
      ls_sel-option = 'EQ'.
      ls_sel-sign = 'I'.
      ls_sel-low = iv_crequest.
      INSERT ls_sel INTO TABLE lt_sel.

      CALL METHOD lo_model->read_char_value
        EXPORTING
          i_fieldname = usmd0_cs_fld-crequest
          it_sel      = lt_sel
          i_readmode  = if_usmd_model_ext=>gc_readmode_no_inact
        IMPORTING
          et_data     = lt_objlist.

      IF lt_objlist IS INITIAL.
        RETURN.
      ELSE.
*        LOOP AT lt_objlist INTO ls_objlist WHERE usmd_entity = if_usmdz_cons_entitytypes=>gc_entity_account. " Entity - ACCOUNT
        LOOP AT lt_objlist INTO ls_objlist.
          CLEAR: ls_sel.
          ls_sel-fieldname = ls_objlist-usmd_entity_obj.
          ls_sel-option = 'EQ'.
          ls_sel-sign = 'I'.
          ls_sel-low = ls_objlist-usmd_value.
          INSERT ls_sel INTO TABLE lt_sel.
        ENDLOOP.


        CALL METHOD lo_model->create_data_reference
          EXPORTING
            i_fieldname = iv_entity
            i_struct    = 'KATTR'
          IMPORTING
            er_data     = lv_structure.

        ASSIGN lv_structure->* TO <lt_data>.

        CALL METHOD lo_model->read_char_value
          EXPORTING
            i_fieldname = iv_entity
            it_sel      = lt_sel
            i_readmode  = iv_readmode
          IMPORTING
            et_data     = <lt_data>.
        it_data[] = <lt_data>[].
      ENDIF.
    ENDIF.

How to use change request API is as follows.

5.	CL_USMD_CREQUEST_API

    DATA :
      lr_crequest                 TYPE REF TO if_usmd_crequest_api.

   CALL METHOD cl_usmd_crequest_api=>get_instance
      EXPORTING
        iv_crequest          = iv_cr_number
      IMPORTING
        re_inst_crequest_api = lr_crequest.

    "CR Request Details:
    CALL METHOD lr_crequest->read_crequest
      IMPORTING
        es_crequest = w_crequest.

Conclusion: Now you are able to use the above API  classes to write a complete API Programming to submit CR.

This blog post is to identify the difference and their usages for Governance API and Convenience Governance API and External Mode API and Context read API.

• API – Application Programming Interface.