CubeMaster API Integration Guide

A RESTful API is a way for systems like Dynamics 365 to talk to external services like CubeMaster:

• Endpoint: A URL like https://api.cubemaster.net/loads where you send data.
• POST Method: Used to send data to create a resource (e.g., a load plan).
• JSON: A lightweight data format (like a structured list) for sending and receiving info.
• Headers: Metadata sent with your request, including the TokenID for security.
• Response: The server’s reply, which could be success data or an error message.

We’ll send shipment data from Dynamics 365 to CubeMaster and get back a detailed load plan.

Prepare Dynamics 365 to integrate with the CubeMaster API:

1. Log in to Dynamics 365:
   • Go to your instance (e.g., https://yourcompany.crm.dynamics.com).
   • Enter your credentials in the login screen and click "Sign In."
2. Navigate to Power Automate:
   • From the Dynamics 365 home screen, click the app launcher (9-dot grid) in the top-left corner.
   • Select "Power Automate" from the list of apps.
3. Create a new flow:
   • In Power Automate, click "Create" in the left sidebar (a blue button).
   • Choose "Automated Cloud Flow" from the options.
   • In the pop-up, enter a name like "CubeMaster Load Builder" in the "Flow name" field.
   • Search for and select the trigger "When a record is created (Dynamics 365)" in the "Choose your flow's trigger" box.
   • Click "Create" at the bottom of the pop-up.
4. Configure the trigger:
   • In the trigger settings, select your "Organization Name" from the dropdown (your Dynamics 365 instance).
   • Set "Entity Name" to "Sales Orders" or "Shipments" (depending on your data source) from the dropdown.
   • Click "New Step" (a circular plus button below the trigger).

Use Dynamics 365 order or shipment data to build the JSON request for https://api.cubemaster.net/loads:

1. Access order/shipment details:
   • In Dynamics 365, go to "Sales" > "Orders" or "Inventory" > "Shipments" from the left navigation bar.
   • Select an order (e.g., click a row in the "Active Sales Orders" grid).
   • Note fields like "Order Number" (for Title), "Description," and line items (for Cargoes).
2. Add a "Compose" action in Power Automate:
   • Click "New Step" > search for "Compose" > select "Data Operation - Compose."
   • In the "Inputs" field, construct the JSON using dynamic content from the trigger:
3. Build the JSON payload:

   {
       "Title": @{triggerOutputs()?['body/name']},
       "Description": @{triggerOutputs()?['body/description']},
       "Cargoes": [
           {
               "Name": @{triggerOutputs()?['body/_productid_value@OData.Community.Display.V1.FormattedValue']},
               "Length": @{triggerOutputs()?['body/new_length']},
               "Width": @{triggerOutputs()?['body/new_width']},
               "Height": @{triggerOutputs()?['body/new_height']},
               "Weight": @{triggerOutputs()?['body/new_weight']},
               "OrientationsAllowed": "OrientationsAll",
               "TurnAllowedOnFloor": false,
               "Qty": @{triggerOutputs()?['body/quantity']},
               "ColorKnownName": "Brown"
           }
       ],
       "Containers": [
           {
               "VehicleType": "Dry",
               "Name": "53FT-Intermodal",
               "Length": 630,
               "Width": 98,
               "Height": 106,
               "ColorKnownName": "Blue"
           }
       ],
       "Rules": {
           "IsWeightLimited": true,
           "IsSequenceUsed": false,
           "FillDirection": "FrontToRear",
           "CalculationType": "MixLoad"
       }
   }

   Notes:

   • Use dynamic content (lightning bolt icon) to insert fields like productid, quantity, etc.
   • Add custom fields (e.g., new_length) via "Settings" > "Customizations" > "Customize the System."
   • For multiple line items, use "Apply to each" to loop through triggerOutputs()?['body/salesorderdetails'].

Send the request to CubeMaster using Power Automate:

1. Add an HTTP action:
   • Click "New Step" > search for "HTTP" > select "HTTP - HTTP."
2. Configure the HTTP action:
   • Method: Select "POST" from the dropdown.
   • URI: Enter https://api.cubemaster.net/loads.
   • Headers: Add:
     • Key: Authorization, Value: Bearer @{variables('TokenID')}
     • Key: Content-Type, Value: application/json
   • Body: Insert "Outputs" from the "Compose" action.
3. Save and test:
   • Click "Save" and "Test" (top-right), then create a test order in Dynamics 365.

Process and store the response:

1. Inspect the response:

   {
       "status": "succeed",
       "message": "Engine created. 5 cargoes. 1 empty containers. Calculation started. Calculation ended. The load built successfully. The load saved to the cloud database.",
       "document": {
           "title": "New Mixed Truck Load",
           "calculationTimeInSeconds": 0.6152743
       },
       "loadSummary": {
           "cargoesLoaded": 68,
           "volumeLoaded": 5261723.4606,
           "weightLoaded": 42674.59999999999
       },
       "filledContainers": [
           {
               "name": "#1 53FT-Intermodal",
               "loadSummary": {
                   "volumeUtilization": 80.39990374424703
               },
               "graphics": {
                   "images": {
                       "path3DDiagram": "https://api.cubemaster.net/runtimes/b28413ca_51ed_44c9_b92e_13147363fd61.PNG"
                   }
               }
           }
       ]
   }

2. Add "Parse JSON":
   • Click "New Step" > "Parse JSON."
   • Content: Select "Body" from HTTP.
   • Schema: Generate from the sample response above.
3. Update Dynamics 365 record:
   • Click "New Step" > search for "Update a record (Dynamics 365)."
   • Set "Entity Name" to "Sales Orders" or "Shipments," and "Item ID" to the trigger's ID.
   • Map fields: Set custom field new_volumeutilization to body('Parse_JSON')?['filledContainers']?[0]?['loadSummary']?['volumeUtilization'].

Techniques for monitoring and debugging your API integration:

• Power Automate Run History: Check flow execution details under "My flows" > select your flow > view "28-day run history."
• HTTP Error Statuses: Handle errors like 401 Unauthorized (invalid TokenID) or 400 Bad Request (malformed JSON) using Power Automate "Configure run after" settings.
• Dynamics 365 System Jobs: Inspect background job statuses via "Settings" > "System Jobs."