CubeMaster API Integration Guide

What is a RESTful API?

A RESTful API (Representational State Transfer) is a standardized way for software systems to communicate over the internet using the same HTTP protocol your browser uses to load web pages. Think of it like a restaurant menu: your IFS system is the customer placing an order (the request), and CubeMaster is the kitchen that prepares and returns the result (the response).

HTTP methods tell the server what action to perform:

• GET: Retrieve data (e.g., look up an existing load plan).
• POST: Submit data to create something new (e.g., submit items and containers to build a new load plan).
• PUT / PATCH: Update an existing resource.
• DELETE: Remove a resource.

In this guide, we exclusively use the POST method to submit a cargo-and-container request and receive an optimized load plan back.

The CubeMaster API Endpoint

Common Query Parameters

These optional parameters can be appended to the URL to control the output:

Example full URL:

https://api.cubemaster.net/loads?loadSaved=true&graphicsCreated=true&UOM=UnitMetric

Before configuring IFS, ensure the following conditions are met in your environment:

Required Access & Roles

Network & Firewall Requirements

The IFS Application Server (or the middleware component executing PL/SQL REST calls) must be allowed to make outbound HTTPS connections on port 443 to the following hosts:

• api.cubemaster.net — the API endpoint for submitting load requests.
• cubemaster.net — if using the Swagger interactive documentation for testing.

Work with your network/security team to whitelist these domains in your corporate firewall and any proxy servers. If your IFS server routes outbound traffic through a proxy, the Plsql_Rest_Sender_API call or your IFS Connect routing address may need to be configured with the proxy host and port.

IFS Part Catalog Data Requirements

CubeMaster requires accurate physical dimensions (length, width, height) and weight for every cargo item. Before enabling this integration in production:

• Verify that the parts in part_catalog_pub (or your custom dimension table) have non-null length, width, height, and weight values.
• Confirm that dimensions are stored in a consistent unit of measure (all metric or all imperial) that matches the UOM parameter you will send to the API.
• Items with zero dimensions will be ignored by the CubeMaster engine and flagged in the calculationError field of the response.

IFS Connect is the native enterprise integration broker built into IFS Applications. A Routing Address defines the external target endpoint (CubeMaster API) that IFS Connect will forward messages to.

4.1 Navigate to Routing Addresses

1. Log in to IFS Applications 9 with an administrator account.
2. Open Solution Manager from the main menu.
3. Navigate to Integration > IFS Connect > Routing Addresses.
4. Click New to create a new routing address record.

4.2 Routing Address Configuration

Fill in the fields as shown below:

4.3 HTTP Header Configuration

In the HTTP Header block of the Routing Address form, add the following two headers. These are sent with every outbound request:

TokenID: YOUR_API_KEY_HERE
Content-Type: application/json

4.4 Save and Test Connectivity

1. Click Save on the Routing Address record.
2. Use the built-in Test Connection button (if available in your IFS version) to verify the server can reach api.cubemaster.net.
3. Alternatively, run a manual ping or curl test from the IFS application server:

   curl -X POST https://api.cubemaster.net/loads \
     -H "TokenID: YOUR_API_KEY_HERE" \
     -H "Content-Type: application/json" \
     -d '{"title":"test","cargoes":[],"emptyContainers":[]}'

4. A 200 OK or a validation error JSON response confirms the server can reach the API. A connection timeout indicates a firewall block.

A Routing Rule tells IFS Connect which outbound messages should be forwarded to the CubeMaster Routing Address configured in Step 4. It acts as a filter based on the message type.

5.1 Create a Routing Rule

1. In Solution Manager, navigate to Integration > IFS Connect > Routing Rules > Outbound.
2. Click New to create a new rule.
3. Fill in the fields as follows:

   Field	Value
   Rule Name	ROUTE_TO_CUBEMASTER
   Message Handler	APPLICATION_MESSAGE
   Condition	MESSAGE_TYPE = 'CUBEMASTER_LOAD_REQUEST'
   Destination Address	CUBEMASTER_API_POST (from Step 4)
   Active	Yes

4. The Condition is the critical field. Only messages where MESSAGE_TYPE equals CUBEMASTER_LOAD_REQUEST will be routed to the CubeMaster API. All other messages are unaffected.
5. Click Save.

5.2 How Message Routing Works

When your PL/SQL block (Step 7) calls Plsql_Rest_Sender_API.Call_Rest_EndPoint_Empty_Body, it places an outbound message with the type CUBEMASTER_LOAD_REQUEST into the IFS Connect message queue. IFS Connect evaluates all active Routing Rules and, matching on MESSAGE_TYPE, forwards the message payload to the configured HTTP Routing Address (CUBEMASTER_API_POST).

This decoupled design means your PL/SQL code does not directly call the CubeMaster API — IFS Connect handles delivery, retry logic, and error recording automatically.

Before writing any PL/SQL, it is critical to understand the exact JSON structure the CubeMaster API expects, and what it returns. Mis-formatted JSON is the most common source of integration errors.

6.1 Request Payload Structure

The request body is a single JSON object with four top-level keys:

6.2 Cargo Item Fields (cargoes)

6.3 Container Fields (emptyContainers)

6.4 Rules Fields (rules)

6.5 Complete Sample Request Payload

{
  "title": "IFS-SHP-100245",
  "description": "Automated load from IFS Applications 9",
  "cargoes": [
    {
      "name": "PART-A01",
      "description": "Industrial Valve Assembly",
      "style": "Shipcase",
      "qty": 45,
      "length": 60,
      "width": 40,
      "height": 40,
      "weight": 15.5,
      "orientationsAllowed": "OrientationsUpright",
      "colorKnownName": "Brown"
    },
    {
      "name": "PART-B05",
      "description": "Control Panel Unit",
      "style": "Shipcase",
      "qty": 12,
      "length": 120,
      "width": 80,
      "height": 100,
      "weight": 110.0,
      "isFragile": true,
      "colorKnownName": "Blue"
    }
  ],
  "emptyContainers": [
    {
      "name": "40HC",
      "containerType": "SeaVan",
      "length": 1203,
      "width": 235,
      "height": 269,
      "maxWeight": 26000,
      "qty": 2
    }
  ],
  "rules": {
    "calculationType": "MixLoad",
    "algorithmType": "Optimization",
    "isWeightLimited": true,
    "fillDirection": "FrontToRear"
  }
}

6.6 Sample API Response

On success, the API returns HTTP 200 OK with a JSON body similar to the following:

{
  "status": "succeed",
  "message": "Engine created. 2 cargoes. 2 empty containers. Calculation ended. The load saved successfully.",
  "calculationError": "NoErrors",
  "document": {
    "title": "IFS-SHP-100245",
    "isShared": true,
    "calculationTimeInSeconds": 0.87,
    "createdBy": "user@company.com",
    "createdAt": "2025-03-10T08:22:01+09:00"
  },
  "loadSummary": {
    "cargoesLoaded": 57,
    "piecesLoaded": 57,
    "cargoesLeft": 0,
    "volumeLoaded": 17820000,
    "weightLoaded": 2017.5,
    "containersLoaded": 1
  },
  "filledContainers": [
    {
      "name": "#1 40HC",
      "sequence": 1,
      "loadSummary": {
        "cargoesLoaded": 57,
        "volumeUtilization": 84.5,
        "weightUtilization": 45.2,
        "floorUtilization": 91.3
      },
      "loadSize": {
        "length": 1180.5,
        "width": 234.0,
        "height": 265.2
      },
      "graphics": {
        "images": {
          "path3DDiagram": "https://api.cubemaster.net/Pictures/a7b8c9d10.PNG",
          "pathComposite": "https://api.cubemaster.net/Pictures/composite_a7b8.PNG"
        }
      }
    }
  ]
}

With the Routing Address and Routing Rule in place, we can now write the PL/SQL code that extracts IFS order data, builds the JSON payload, and dispatches it through IFS Connect. This code runs as an Execute Online SQL action inside an IFS Custom Event.

7.1 IFS Table Reference

7.2 Full PL/SQL Block (Annotated)

DECLARE
   -- -----------------------------------------------
   -- Variable declarations
   -- -----------------------------------------------
   ls_payload     CLOB;          -- The full JSON payload (CLOB for large orders)
   ls_items       CLOB := '';    -- Temporary buffer for cargoes array entries
   ln_item_count  NUMBER := 0;   -- Track how many items were added
   order_no_      VARCHAR2(50) := '&NEW:ORDER_NO';  -- IFS event parameter

   -- -----------------------------------------------
   -- Cursor: fetch all order lines with dimensions
   -- Only include parts that have valid dimensions
   -- -----------------------------------------------
   CURSOR get_lines IS
      SELECT
         l.catalog_no      AS part_no,
         l.catalog_desc    AS part_desc,
         l.buy_qty_due     AS qty,
         NVL(c.length, 0)  AS l,
         NVL(c.width,  0)  AS w,
         NVL(c.height, 0)  AS h,
         NVL(c.weight, 0)  AS wt
      FROM customer_order_line l
      LEFT JOIN part_catalog_pub c ON l.catalog_no = c.part_no
      WHERE l.order_no = order_no_
        AND l.buy_qty_due > 0;    -- Skip zero-quantity lines

BEGIN
   -- -----------------------------------------------
   -- Step A: Build each cargo item JSON object
   -- -----------------------------------------------
   FOR rec_ IN get_lines LOOP
      -- Skip items with no valid dimensions
      IF rec_.l > 0 AND rec_.w > 0 AND rec_.h > 0 THEN
         IF ln_item_count > 0 THEN
            ls_items := ls_items || ',';   -- comma-separate items
         END IF;

         ls_items := ls_items ||
            '{' ||
               '"name":"'        || rec_.part_no   || '",' ||
               '"description":"' || REPLACE(rec_.part_desc, '"', '\"') || '",' ||
               '"style":"Shipcase",' ||
               '"qty":'          || TRIM(TO_CHAR(rec_.qty)) || ',' ||
               '"length":'       || TRIM(TO_CHAR(rec_.l))   || ',' ||
               '"width":'        || TRIM(TO_CHAR(rec_.w))   || ',' ||
               '"height":'       || TRIM(TO_CHAR(rec_.h))   || ',' ||
               '"weight":'       || TRIM(TO_CHAR(rec_.wt))  ||
            '}';

         ln_item_count := ln_item_count + 1;
      END IF;
   END LOOP;

   -- Guard: do not send an empty cargoes array
   IF ln_item_count = 0 THEN
      RETURN;  -- No valid items found; abort silently
   END IF;

   -- -----------------------------------------------
   -- Step B: Assemble the full JSON payload
   -- -----------------------------------------------
   ls_payload :=
      '{' ||
         '"title":"'       || order_no_ || '",' ||
         '"description":"IFS Auto-Generated Shipment",' ||

         -- Cargo items array (built above)
         '"cargoes":['     || ls_items || '],' ||

         -- Default 40HC container (can be made dynamic via a separate cursor)
         '"emptyContainers":[{' ||
            '"name":"40HC",' ||
            '"containerType":"SeaVan",' ||
            '"length":1203,' ||
            '"width":235,' ||
            '"height":269,' ||
            '"maxWeight":26000,' ||
            '"qty":3' ||         -- allow up to 3 containers for large orders
         '}],' ||

         -- Optimization rules
         '"rules":{' ||
            '"calculationType":"MixLoad",' ||
            '"algorithmType":"Optimization",' ||
            '"isWeightLimited":true,' ||
            '"fillDirection":"FrontToRear"' ||
         '}' ||
      '}';

   -- -----------------------------------------------
   -- Step C: Send through IFS Connect outbound queue
   -- -----------------------------------------------
   Plsql_Rest_Sender_API.Call_Rest_EndPoint_Empty_Body(
      rest_endpoint_ => 'CUBEMASTER_API_POST',  -- must match Routing Address name
      payload_       => ls_payload,
      http_method_   => 'POST'
   );

EXCEPTION
   WHEN OTHERS THEN
      -- Log to IFS Application Error log for debugging
      Error_SYS.Record_General(
         'CUBEMASTER_INT',
         'Payload dispatch failed for order :P1. Error: :P2',
         order_no_,
         SQLERRM
      );
END;

7.3 Key Code Notes

• CLOB vs. VARCHAR2: We use CLOB for ls_payload because large orders with dozens of line items can exceed the 32 KB limit of VARCHAR2.
• REPLACE for special characters: The REPLACE(rec_.part_desc, '"', '\"') escapes double quotes in part descriptions to prevent JSON parse errors.
• Guard clause: The IF ln_item_count = 0 THEN RETURN prevents submitting an empty cargoes array, which would cause an API validation error.
• Dynamic container selection: In the example above, a fixed 40HC container is used. For a production system, you should add a second cursor to query the planned shipment container from the IFS Shipment or Delivery schedule tables.
• TO_CHAR with TRIM: Always use TRIM(TO_CHAR(...)) for numbers to avoid leading spaces in the JSON output, which can cause parse errors in strict JSON validators.

A Custom Event in IFS is the automation trigger that executes your PL/SQL block when a specific business condition occurs. This connects the business process (e.g., order release) to the CubeMaster API call.

8.1 Create the Custom Event

1. In Solution Manager, navigate to Monitoring > Events > Custom Events.
2. Click New.
3. Configure the event header:

   Field	Recommended Value
   Event Name	CUBEMASTER_LOAD_ON_ORDER_RELEASE
   Logical Unit	CustomerOrder (or Shipment if triggering from shipment)
   Firing Condition	Attribute: Objstate, Operation: Changed To, Value: Released
   Active	Yes

4. Click Save to save the event header before adding actions.

8.2 Add the Execute Online SQL Action

1. In the Actions sub-tab of your new event, click New.
2. Set Action Type to Execute Online SQL.
3. Paste the complete PL/SQL block from Step 7 into the SQL Text field.
4. The event parameter &NEW:ORDER_NO in the PL/SQL will automatically be replaced with the actual order number at runtime by the IFS event framework.
5. Click Save.

8.3 Alternative Trigger Points

Depending on your business process, you may want to trigger the CubeMaster call at a different point:

After CubeMaster processes the request, it returns a JSON response. You can configure IFS to capture and store key fields from this response back into IFS records.

9.1 Response Field Mapping

Map CubeMaster's response JSON fields to IFS Custom Fields on the Shipment or Customer Order screen:

9.2 Implementing a Response Transformer

IFS Connect supports a Response Transformer on each Routing Address. This allows you to define XPath or JSONPath expressions to parse the CubeMaster response and trigger a second IFS event or update record fields automatically.

1. In the CUBEMASTER_API_POST Routing Address record, navigate to the Response Handling tab.
2. Enable Parse Response and set format to JSON.
3. Define JSONPath mappings, for example:

   JSONPath Expression	Target Parameter
   $.status	CUBEMASTER_STATUS
   $.loadSummary.volumeUtilization	VOL_UTIL
   $.loadSummary.cargoesLeft	CARGOES_LEFT
   $.filledContainers[0].graphics.images.path3DDiagram	DIAGRAM_URL

4. Use these extracted parameters in a response event to call a second PL/SQL block that writes the values back to the IFS Customer Order or Shipment custom fields.

10.1 Pre-Deployment Sandbox Testing

1. Open https://api.cubemaster.net/index.html.
2. Click the Authorize button and enter your TokenID.
3. Expand the POST /loads endpoint and click Try it out.
4. Paste a sample payload (matching what your PL/SQL would produce) into the request body and click Execute.
5. Verify that the response contains "status": "succeed" and a valid path3DDiagram URL before enabling the IFS event.

10.2 Monitoring IFS Connect Message Queue

1. Navigate to Solution Manager > Integration > IFS Connect > Application Messages.
2. Filter by Queue Name or Message Type = CUBEMASTER_LOAD_REQUEST to find all outbound messages from your integration.
3. Check the State column. Possible states include:
   • Sent — Successfully forwarded to CubeMaster.
   • Failed — Delivery failed. Click the message to see the Error Text.
   • Cancelled — Manually cancelled or exceeded retry limit.
   • Waiting — In queue, not yet dispatched.
4. For Failed messages, click the row to open the message details and review the Error Text field. Common errors are listed in section 10.4 below.
5. You can manually Resend a failed message after correcting the underlying issue.

10.3 Verifying the Event Fires Correctly

1. Navigate to Solution Manager > Monitoring > Events > Application Event Log.
2. Filter by Event Name = CUBEMASTER_LOAD_ON_ORDER_RELEASE.
3. Check the Status of recent event executions. A Completed status means the PL/SQL ran successfully and placed a message in the queue.
4. An Error status means the PL/SQL itself threw an exception. Review the Error Message column — this will show the Oracle error or the message from Error_SYS.Record_General.

10.4 Common Errors & Solutions

10.5 Unit of Measure Alignment

10.6 Performance Considerations

• Large orders (> 100 lines): CubeMaster calculation time scales with the number of unique cargo types and total quantity. For orders with many lines, set the Timeout on the Routing Address to 120 seconds or more.
• Batch processing: If many orders are released simultaneously, IFS Connect queues messages and processes them sequentially. Monitor queue depth to ensure messages are delivered in a timely manner.
• API rate limits: Check your CubeMaster subscription plan for any API call rate limits (e.g., X calls per minute). If exceeded, the API returns HTTP 429 Too Many Requests. Implement a delay or queue throttle in IFS Connect if needed.
• CLOB handling: PL/SQL concatenation of CLOB types is slower than VARCHAR2. For very large payloads, consider using DBMS_LOB.APPEND for optimal performance.