Skip to content

Building Your First Orchestration

This walkthrough guides you through creating a simple orchestration that decodes a VIN (Vehicle Identification Number) using a public API. By the end, you will have a working orchestration you can run and monitor.

Prerequisites

Before you start, ensure you have:

  • At least one active connection (the NHTSA VPIC connector works well for this example, as it requires no credentials)
  • Enterprise Admin or higher role in DIBOP

Step 1: Create a New Orchestration

  1. Navigate to BUILD > Orchestrations in the sidebar
  2. Click New Orchestration
  3. Fill in the basics:
Field Value
Name VIN Decode Example
Description Decodes a VIN using the NHTSA VPIC API and returns vehicle details
  1. Click Create

You are now in the orchestration editor with an empty workflow.

Step 2: Define Input Parameters

Your orchestration needs a VIN as input. Add an input parameter:

  1. In the Parameters panel, click Add Parameter
  2. Configure:
Field Value
Name vin
Type String
Required Yes
Description The 17-character Vehicle Identification Number to decode
  1. Click Save Parameter

Step 3: Add an API Call Step

Now add a step that calls the NHTSA VPIC API to decode the VIN.

  1. Click Add Step
  2. Select step type: API Call
  3. Configure the step:
Field Value
Step Name decode_vin
Description Call NHTSA VPIC to decode the VIN
Connection NHTSA VPIC
Operation Decode VIN
Parameters vin: ${parameters.vin}

The ${parameters.vin} syntax references the input parameter you defined in Step 2. When the orchestration runs, it will be replaced with the actual VIN value.

  1. Click Save Step

Step 4: Add a Transform Step

The NHTSA API returns a large response with many fields. Add a transform step to extract only the fields you care about.

  1. Click Add Step
  2. Select step type: Data Transform
  3. Configure:
Field Value
Step Name extract_vehicle_details
Description Extract key fields from the NHTSA response
  1. In the transform editor, define the mapping:
{
  "make": "${decode_vin.response.Results[0].Make}",
  "model": "${decode_vin.response.Results[0].Model}",
  "year": "${decode_vin.response.Results[0].ModelYear}",
  "body_class": "${decode_vin.response.Results[0].BodyClass}",
  "engine_type": "${decode_vin.response.Results[0].EngineModel}",
  "fuel_type": "${decode_vin.response.Results[0].FuelTypePrimary}",
  "plant_country": "${decode_vin.response.Results[0].PlantCountry}"
}
  1. Click Save Step

Step 5: Review the Orchestration

Your orchestration now has:

  1. Input: A VIN parameter
  2. Step 1 (decode_vin): Calls the NHTSA API with the VIN
  3. Step 2 (extract_vehicle_details): Extracts key fields from the response

Review the step order and parameter mappings in the orchestration editor. The flow should read naturally from top to bottom.

Step 6: Test with Sample Data

Before activating, test the orchestration with a sample VIN.

  1. Click Test Run in the toolbar
  2. Enter a sample VIN in the parameters panel:
{
  "vin": "1HGCM82633A004352"
}
  1. Click Execute
  2. Watch the execution trace in real time:
    • Step 1 (decode_vin) calls the NHTSA API and shows the raw response
    • Step 2 (extract_vehicle_details) transforms the data and shows the extracted fields

If everything looks correct, you will see a green Success status.

Test with Multiple VINs

Try a few different VINs to make sure the orchestration handles various vehicle types correctly. If a VIN is invalid, the NHTSA API will return empty results -- this is a good opportunity to add error handling later.

Step 7: Activate the Orchestration

  1. Click Activate in the toolbar
  2. Confirm the activation

Your orchestration is now Active and can be:

  • Run manually from the Orchestration Runner
  • Triggered by other systems via the API
  • Scheduled to run at regular intervals

Running Your Orchestration

From the Orchestration Runner

  1. Navigate to BUILD > Orchestration Runner
  2. Select your "VIN Decode Example" orchestration
  3. Enter the VIN parameter
  4. Click Run
  5. Watch the Execution Trace in the results panel

From the API

You can also trigger orchestrations via the DIBOP API:

curl -X POST "https://<your-instance>.dibop.ca/api/v1/orchestrations/<id>/execute" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"vin": "1HGCM82633A004352"}}'

Enhancing Your Orchestration

Now that you have a working orchestration, consider these enhancements:

Add Error Handling

What if the VIN is invalid or the API is down? Add error handling to the decode_vin step:

  • On Error: Continue (instead of Abort)
  • Retry: 2 attempts with 1-second delay
  • Fallback: A transform step that returns a "VIN not found" response

Add a Conditional Step

Add a conditional step that checks whether the decode was successful before proceeding:

If ${decode_vin.response.Count} > 0:
    → extract_vehicle_details
Else:
    → return_not_found

Write to Another System

Add a final step that writes the decoded vehicle data to your DMS or CRM using another connected system.

What You Have Learned

In this walkthrough, you have:

  • Created an orchestration with input parameters
  • Added an API Call step that calls an external system
  • Added a Transform step that reshapes the response
  • Tested the orchestration with sample data
  • Activated the orchestration for production use

Next Steps