Adding custom events in Business Network for Logistics - Global Track and Trace(GTT)

[Sunny_Bhatia1]

Businesses often need to track internal or external events that are specific to their industry or driven by internal KPIs to monitor the status of business documents. SAP Business Network Global Track and Trace(BN4L GTT) offers public APIs that support many common, industry-standard event types. Additionally, customers can use the "Other" event type to track events that fall outside predefined event types.

However, when even that is not sufficient, SAP Business Network Global Track and Trace(BN4L GTT) provides a flexible framework to define and integrate custom event, allowing customers to capture and monitor events that are uniquely relevant to their business processes.

In this blog, I will share how easily the customers can create their own custom events via the standard apps available.

Prerequisites:

• The SAP Business Network for Logistics (BN4L) sample extractor code, delivered by the product team, should be implemented in the SAP S/4HANA system to enable the integration of event data with GTT.
• To configure and add custom events in SAP Business Network Global Track and Trace (GTT), the IT user or system integrator must have the DataModelAdminTemplate role assigned in the SAP BTP subaccount where the GTT application is subscribed.

Overview of Steps:

• Step 1: Create and Extend the Custom Event in S/4HANA TM
  • Define the custom event in the S/4HANA Transportation Management (TM) system and enhance the BN4L GTT extractor logic to send the planned date and time of the event to GTT.

• Step 2: Configure the Custom Event in BN4L GTT
  • Use the SAP Business Network GTT app to configure the custom event and map it to the corresponding IDoc segmentreceived from the source system.

Detailed Steps: 

Step 1: Create and Extend the Custom Event in S/4Hana TM

• Step 1.1: Configuration of new event type in S/4Hana TM
  • We begin by setting up the new custom event in the S/4HANA Transportation Management (TM) system. To do this, navigate to the SAP Customizing Implementation Guide (SPRO) and follow the path: SAP Customizing Implementation Guide(IMG) -> Transportation Management -> Integration -> Tracking and Tracing of Processes and Documents -> Define Transportation Activities for Tracking and Tracing. Here, you can define the new event type that will later be mapped and sent to SAP Business Network Global Track and Trace (GTT).Note: This configuration path is based on S/4HANA 2022 release. It may vary slightly in earlier or more recent versions of Transportation Management.

• Step 1.2: Extending the GTT extractor code 
  • Edit the class "ZCL_GTT_STS_PE_FO_FILLER" and add a new method called ZZ_CUSTOMSHIP_EVENT to populate the planned date and time of the custom event "ZZ_CUSTOM_EVENT" into the IDoc. Please note that the actual ABAP class to be modified may vary depending on your tracking configuration set up in transaction "ZGTT_TRACK_CONF". This is because the data filler class responsible for planned events is determined by the specific tracking configuration defined for your scenario.

    In this example, I am sending the departure date and time of the source location as the planned timestamp for the custom event. However, you can implement your own logic to calculate the appropriate date and time based on other available fields from the Freight Order, and then include that information in the IDoc accordingly.

  • Method Declaration and Code Snippet: 

 methods ZZ_CUSTOMSHIP_EVENT
    importing
      !IV_TOR_ID type /SCMTMS/TOR_ID optional
      !IT_STOP type /SCMTMS/T_EM_BO_TOR_STOP optional
      !IT_LOC_ADDR type /BOFU/T_ADDR_POSTAL_ADDRESSK
      !IT_STOP_POINTS type ZIF_GTT_STS_EF_TYPES=>TT_STOP_POINTS optional
      !IS_APP_OBJECTS type TRXAS_APPOBJ_CTAB_WA
    changing
      !CT_EXPEVENTDATA type ZIF_GTT_STS_EF_TYPES=>TT_EXPEVENTDATA .

METHOD ZZ_CUSTOMSHIP_EVENT.
    DATA: ls_loc_addr TYPE REF TO /bofu/s_addr_postal_addressk,
          lt_loc_root TYPE /scmtms/t_bo_loc_root_k.

    FIELD-SYMBOLS <ls_root> TYPE /scmtms/s_em_bo_tor_root.

    ASSIGN is_app_objects-maintabref->* TO <ls_root>.
    IF sy-subrc <> 0.
      RETURN.
    ENDIF.

    LOOP AT it_stop USING KEY parent_seqnum ASSIGNING FIELD-SYMBOL(<ls_stop>) WHERE parent_node_id = <ls_root>-node_id.
      CHECK <ls_stop>-stop_cat = /scmtms/if_common_c=>c_stop_category-outbound AND
            <ls_stop>-plan_trans_time IS NOT INITIAL.

      READ TABLE it_stop_points REFERENCE INTO DATA(ls_stop_points)
                                     WITH KEY log_locid = <ls_stop>-log_locid
                                              seq_num   = <ls_stop>-seq_num.
      CHECK sy-subrc = 0.

*      TEST-SEAM shp_dep_lt_loc_root.
        /scmtms/cl_pln_bo_data=>get_loc_data(
          EXPORTING
            it_key      = VALUE #( ( key = <ls_stop>-log_loc_uuid ) )
          CHANGING
            ct_loc_root = lt_loc_root ).
*      END-TEST-SEAM.
      READ TABLE lt_loc_root REFERENCE INTO DATA(ls_loc_root)
                                     WITH KEY key COMPONENTS key = <ls_stop>-log_loc_uuid.
      CHECK sy-subrc = 0.

      DATA(lv_tz) = COND tznzone( WHEN ls_loc_root->time_zone_code IS NOT INITIAL
                                  THEN ls_loc_root->time_zone_code
                                  ELSE sy-zonlo ).

      DATA(lv_exp_datetime) = <ls_stop>-plan_trans_time.

      zcl_gtt_sts_tools=>convert_utc_timestamp(
        EXPORTING
          iv_timezone  =  lv_tz
        CHANGING
          cv_timestamp = lv_exp_datetime ).

      mv_milestonecnt += 1.
      APPEND VALUE #(
      appsys            = mo_ef_parameters->get_appsys(  )
      appobjtype        = mo_ef_parameters->get_app_obj_types( )-aotype
      language          = sy-langu
      appobjid          = is_app_objects-appobjid
      milestone         = zif_gtt_sts_constants=>cs_milestone-fo_cust_event
      evt_exp_datetime  = |0{ lv_exp_datetime }|
      evt_exp_tzone     = lv_tz
      locid1            = <ls_stop>-log_locid
      locid2            = ls_stop_points->stop_id
      loctype           = zcl_gtt_sts_tools=>get_location_type( iv_locno = <ls_stop>-log_locid ) ) TO ct_expeventdata.

      CLEAR: lt_loc_root, ls_loc_root.
    ENDLOOP.
  ENDMETHOD.​

• Call the above method in the class ZCL_GTT_STS_PE_FO_FILLER method ZIF_GTT_STS_PE_FILLER~GET_PLANNED_EVENTS() as below:

 zz_customship_event(
      EXPORTING
        iv_tor_id       = lv_tor_id
        it_stop         = lt_stop
        it_loc_addr     = lt_loc_address
        it_stop_points  = lt_stop_points
        is_app_objects  = is_app_objects
      CHANGING
        ct_expeventdata = ct_expeventdata ).
​

By implementing the above method in the class ZCL_GTT_STS_PE_FO_FILLER, you complete the process of sending the new custom event to BN4L GTT via the IDoc.

Step 2: Configure the Custom Event in BN4L GTT

The first step is to add the custom event in the relevant tracked process. A tracked process in SAP Global Track and Trace (GTT) represents a business process that involves multiple parties and may also include other interrelated processes. It defines a sequence of planned events—referred to as milestones in systems like SAP Event Management—that are expected to occur during process execution. As the process unfolds, GTT captures actual events, which can either be the realization of planned events or unexpected/unplanned occurrences, providing real-time visibility and actionable insights.

A common example of a standard tracked process is a shipment, and this blog will focus primarily on how to enhance and customize event tracking within a shipment tracked process.

• Step 2.1: Create a new custom event in "Manage Model" app of SAP BN4L 
  • Login to BN4L - GTT app and navigate to 'Manage Model' app under 'Model Management' section. In this step, we will extend the standard delivered model 'gttft1 - GTT Standard Model' to add the custom event. You can click on standard model and go to edit mode to add the new event.
  • Navigate to 'Event Type Pool' tab where all the standard and user-defined events are maintained.
  • Click on 'Create' button on the top of the list of events and provide the information in the pop-up 'Create Event Type' for the new custom event such as name, description and the tracked process it will be associated to. As I am adding the custom event for the 'Shipment' tracked process, I have selected the 'Shipment' from the drop-down field:
  • (Optional): Once the new event is created, it will appear in the list of events on the left side of the section. You will then have the option to add any user-model fields that are specifically relevant to this new event. By default, the new event inherits all the standard core-model fields under the section CoreModel.Event. However, if you have a business requirement to capture any additional specific fields or data for the custom event, you can add them here under the User Model Fields section.
• Step 2.2: Maintain the required configuration for custom event 

  In this step, I will configure the newly created event by classifying it as either an Admissible Planned or Admissible Unplanned event for a tracked process. This classification should be based on your specific business requirements.

  For this example, I will configure the custom event as a Planned event for the 'Shipment' tracked process.

  • Navigate to 'Tracked Process' tab and scroll to 'Shipment' tracked process from the list of tracked processes.
  • Select 'Admissible Planned Event' from 'Content' drop-down as we are adding the custom event as planned event. You will see all the User Model Planned Event types and the Standard Model Event Types which are relevant for 'Shipment' Tracked Process.
  • Click on 'Add' button and add the required configuration for the new event. Once added, click on 'Save' button to save the changes related to custom event. 
    • Tolerances: The tolerance value is used to calculate the earliest and latest timestamps of the events if it's not provided by the source of the planned event.
    • Periodic Overdue Detection:It's used to define how often you want the system to check the status of overdue events. In the below screenshot, I have defined it as 10 minutes and the system will check the status of overdue events every 10 minutes. You can also define how many times the system should check the Overdue status by maintaining the value for the field 'Max Overdue Detection'. 
    • You can also configure notification emails to be sent if an event becomes overdue and has not yet been reported. This helps alert the relevant stakeholders so they can take timely action.
  • Step 2.3: Map the event with the IDOC segment

    In this step, we will map the newly created custom event for the Shipment tracked process to the corresponding IDoc segment in the incoming shipment data—either from an external system or from SAP S/4HANA Transportation Management. (Extending the S/4Hana TM extractor code for sending the data for custom events will be covered in another blog)

    Since the custom event has been added as an Admissible Planned Event, the planned timestamps will be provided by the source system through the shipment document.

  • Navigate to 'IDOC Integration' tab and select 'Shipment' in the tracked process field. This will list all the data (events and fields) related to shipment tracked process and how it is mapped to the standard delivered IDOC for shipment creation.
  • Check the newly created custom event under the 'Tracked Process/Events' section and map it to the event name 'ZZ_CUSTOM_EVENT' created in S/4Hana Transportation Management in Step 1.
  • Click ‘Deploy’ to save and deploy the model. Once deployment is successful—usually within a few seconds—the model status will change to Active.

This will complete the configuration required on BN4L GTT to add any custom event and map it to the incoming IDOC from an external system or SAP S/4Hana Transporation Management. 

Testing Results:

The new custom event will appear in the Track Shipment app for shipments created after the implementation is completed. Since the event was configured as a Planned Event under the Shipment Tracked Process, it will be visible in the Tracking Timeline of the shipment.

You can also test the setup by manually reporting the event via the same app using the “Report” button, which allows you to simulate and validate the event flow.

In my upcoming blog, I will explain how to recieve the actual event from an external system or a third-party systems using the SAP Business Network Global Track and Trace API's.