Integrating CubeMaster API with ShipERP (on SAP)
A technical guide for building the integration using ABAP.
Architecture: This guide outlines a direct integration from an SAP system to the CubeMaster API. An ABAP program will be created to make the HTTP call, triggered by a user action within a standard SAP Shipment or Delivery transaction.
As with all integrations, the first step is to get your unique API key from CubeMaster for authentication. Copy this key and keep it safe for the next step.
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:
- Using transaction SECSTORE, create a new entry.
- Define a unique record ID, for example,
Z_CUBEMASTER_API_KEY. - Store the API key from CubeMaster as the value for this record.
- 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:
- Go to transaction SE11 (ABAP Dictionary).
- Create a new transparent table, e.g.,
ZCM_SHIPMENT_RESULTS. -
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)
- 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:
- Go to transaction SE24 and create a new global class, e.g.,
ZCL_CUBEMASTER_INTEGRATION. - Create a public method, e.g.,
CALCULATE_LOAD_PLAN, with an importing parameter for the Shipment Number (I_TKNUMTYPETKNUM). - 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.
" ... loop through lt_delivery_items and build the 'Cargoes' part of the JSON ...
" 3. Build the JSON Request Body
" In a real scenario, you would loop through delivery data to build this dynamically.
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/v1/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 = 'x-api-key' 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
" Use class /UI2/CL_JSON to deserialize lv_response into an ABAP structure.
DATA: ls_response_data TYPE ZCM_YOUR_RESPONSE_STRUCTURE.
/ui2/cl_json=>deserialize(
EXPORTING json = lv_response
CHANGING data = ls_response_data ).
" Example of getting one value:
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.
" ... map other fields ...
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:
- Identify the relevant SAP screen. For shipments, this is often in transaction VT01N (Create), VT02N (Change), or the ShipERP equivalent screen.
- Using a Screen Enhancement, User Exit, or BAdI (Business Add-In), add a new button to the application toolbar labeled "Calculate Load Plan".
- Write the code behind this button to capture the current Shipment Number (
TKNUM) from the screen. -
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 ). - 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.