CubeMaster API Integration Guide

Hardcoding credentials in ABAP code is a major security risk. The SAP standard and best practice is to use the Secure Store & Forward (SSF) mechanism or the Secure Store (SECSTORE).

What Your Basis/Security Team Will Do:

1. Using transaction SECSTORE, create a new entry.
2. Define a unique record ID, for example, Z_CUBEMASTER_API_KEY.
3. Store the API key from CubeMaster as the value for this record.
4. Your ABAP code will then securely read this record by its ID, avoiding any hardcoded credentials.

You need a place to store the results returned by the CubeMaster API and link them to your SAP Shipment document.

What an ABAP Developer Will Do:

1. Go to transaction SE11 (ABAP Dictionary).
2. Create a new transparent table, e.g., ZCM_SHIPMENT_RESULTS.
3. Define fields to store the data. The key should be the SAP Shipment Number (TKNUM).
   • MANDT (Client)
   • TKNUM (Shipment Number - Key Field)
   • STATUS (e.g., CHAR 10)
   • MESSAGE (e.g., STRING)
   • VOL_UTILIZATION (e.g., DEC 5, 2)
   • WEIGHT_LOADED (e.g., QUAN)
   • PIECES_LOADED (e.g., INT4)
   • DIAGRAM_URL (e.g., STRING)
4. Activate the table.

The core of the integration is an ABAP class that will build the request, call the API, and process the response. The standard classes for this are CL_HTTP_CLIENT for the call and /UI2/CL_JSON for handling JSON.

What an ABAP Developer Will Do:

1. Go to transaction SE24 and create a new global class, e.g., ZCL_CUBEMASTER_INTEGRATION.
2. Create a public method, e.g., CALCULATE_LOAD_PLAN, with an importing parameter for the Shipment Number (I_TKNUM TYPE TKNUM).
3. Implement the method with the logic below.

METHOD calculate_load_plan.
  DATA: lo_http_client TYPE REF TO if_http_client,
        lv_url         TYPE string,
        lv_json_body   TYPE string,
        lv_response    TYPE string,
        ls_secstore    TYPE secstore_entry,
        lv_api_key     TYPE string.

  " 1. Retrieve API Key from Secure Store
  CALL FUNCTION 'SECSTORE_READ_ENTRY'
    EXPORTING
      id      = 'Z_CUBEMASTER_API_KEY'
    IMPORTING
      entry   = ls_secstore
    EXCEPTIONS
      OTHERS  = 1.
  IF sy-subrc = 0.
    lv_api_key = ls_secstore-value.
  ELSE.
    MESSAGE 'API Key not found in SECSTORE' TYPE 'E'.
    RETURN.
  ENDIF.

  " 2. Select Shipment/Delivery data based on I_TKNUM
  " This logic will be specific to your system. You need to select delivery items (LIPS)
  " associated with the shipment (VTTP/VTTS) and get their dimensions from the material master (MARA/MARM).
  " For this example, we will construct a hardcoded JSON string.
  
  DATA: lt_delivery_items TYPE TABLE OF lips,
        ls_delivery_item  TYPE lips.
        
  SELECT * FROM vttp INTO TABLE @DATA(lt_vttp) WHERE tknum = @i_tknum.
  LOOP AT lt_vttp ASSIGNING FIELD-SYMBOL(<fs_vttp>).
      SELECT * FROM lips APPENDING TABLE lt_delivery_items WHERE vbeln = <fs_vttp>-vbeln.
  ENDLOOP.

  " 3. Build the JSON Request Body
  lv_json_body = '{' &&
  '  "Title": "SAP Shipment ' && i_tknum && '",' &&
  '  "Cargoes": [' &&
  '    {' &&
  '      "Name": "ITEM001",' &&
  '      "Length": 72,' &&
  '      "Width": 30,' &&
  '      "Height": 75,' &&
  '      "Weight": 1002.45,' &&
  '      "Qty": 16' &&
  '    }' &&
  '  ],' &&
  '  "Containers": [{' &&
  '    "Name": "53FT-Intermodal",' &&
  '    "Length": 630,' &&
  '    "Width": 98,' &&
  '    "Height": 106' &&
  '  }]' &&
  '}'.

  " 4. Make the HTTP Call
  lv_url = 'https://api.cubemaster.net/loads'.
  cl_http_client=>create_by_url(
    EXPORTING url = lv_url
    IMPORTING client = lo_http_client
  ).

  lo_http_client->request->set_method('POST').
  lo_http_client->request->set_header_field( name = 'TokenID' value = lv_api_key ).
  lo_http_client->request->set_header_field( name = 'Content-Type' value = 'application/json' ).
  lo_http_client->request->set_cdata( data = lv_json_body ).

  lo_http_client->send( ).
  lo_http_client->receive( ).
  lv_response = lo_http_client->response->get_cdata( ).
  lo_http_client->close( ).

  " 5. Parse the JSON Response and Update Z-Table
  DATA: ls_response_data TYPE ZCM_YOUR_RESPONSE_STRUCTURE.
  /ui2/cl_json=>deserialize(
     EXPORTING json = lv_response
     CHANGING data = ls_response_data ).

  DATA(lv_vol_util) = ls_response_data-filledcontainers[ 1 ]-loadsummary-volumeutilization.
  
  DATA ls_results TYPE zcm_shipment_results.
  ls_results-tknum = i_tknum.
  ls_results-status = ls_response_data-status.
  ls_results-vol_utilization = lv_vol_util.
  
  MODIFY zcm_shipment_results FROM ls_results.
  COMMIT WORK.

ENDMETHOD.

The final piece is to give users a way to run your code. This is typically done by adding a custom button to a standard SAP transaction screen.

What a Functional/ABAP Consultant Will Do:

1. Identify the relevant SAP screen. For shipments, this is often in transaction VT01N (Create), VT02N (Change), or the ShipERP equivalent screen.
2. Using a Screen Enhancement, User Exit, or BAdI (Business Add-In), add a new button to the application toolbar labeled "Calculate Load Plan".
3. Write the code behind this button to capture the current Shipment Number (TKNUM) from the screen.
4. Call the public method you created in your ABAP class, passing the Shipment Number to it:

   DATA(lo_cubemaster) = NEW zcl_cubemaster_integration( ).
   lo_cubemaster->calculate_load_plan( i_tknum = lv_current_shipment_number ).

5. After the call, refresh the screen or display a success message to the user.

With the results saved in your custom Z-table, you can now display them within SAP.

Options for Displaying Data:

• Custom Subscreen: Enhance the shipment transaction (e.g., VT02N) to include a new tab or subscreen. On this screen, read from your ZCM_SHIPMENT_RESULTS table and display the key metrics like Volume Utilization and Weight Loaded.
• ALV Report: Create a simple ALV report (transaction SE38) where users can enter a shipment number and see the full results. In this report, you can make the DIAGRAM_URL field a hotspot, so when a user clicks it, it opens the 3D diagram in their browser.