YAML builder reference guide

Overview

The YAML Builder is a low-code interface within Boomi Data Integration designed to streamline the creation of Blueprint connectors. It enables developers and integration specialists to visually define API interactions, authentication methods, and data workflows without manually authoring complex YAML configurations.

This guide provides a comprehensive reference for configuring connectors, defining user inputs, and orchestrating API calls.

Prerequisites

Before building a connector, ensure you have:

• API documentation: Access to the REST API documentation for the service you are connecting to.
• Authentication credentials: A valid account (API Key, Username/Password, or OAuth Client) to test the connection.
• Endpoint details: Knowledge of the specific resource endpoints. For example, /users, /orders and their required parameters.

Connector configuration

The Connector configuration section establishes the foundational settings for your integration.

General settings

• Connector Name: Enter a descriptive name for your connector. For example, Shopify Admin API, Salesforce REST. This name appears in the River configuration.
• Base URL: Define the root URL for the API. For example, https://api.myservice.com/v2.

note

All step endpoints will be appended to this Base URL. Do not include trailing slashes.

Authentication

Configure how the connector establishes identity with the external API.

Auth Type	Description	Configuration Required
No Auth	For public APIs requiring no credentials.	None.
Basic Auth	Standard HTTP Basic Authentication.	Username and Password are requested from the user at runtime.
API Key	Authentication via a static key.	Key Name: The parameter name. For example, Authorization, x-api-key. Usage: Send in Header or Query Params.
OAuth2	Token-based authentication (Client Credentials).	Client ID, Client Secret, Token URL, and Scopes.

Interface parameters - User inputs

Interface parameters define the configuration form presented to the end-user when they use your connector in a River. Use these to capture dynamic values required for execution.

Configuring parameters

1. Click Add New Parameter.
2. Select the Parameter Type:
   • String: Standard text input.
   • Secure String: Masked input for sensitive values (passwords, tokens).
   • List: A predefined dropdown menu.
   • Date Range: A start/end date picker.

Date range configuration

For APIs that support time-window filtering, use the Date Range type.

• Format: Select the date format expected by the API. For example, YYYY-mm-DD, epoch, YYYY-MM-DDTHH:MM:SSZ.
• Variable Usage:
  • Start Date: {parameter_name.start_date}
  • End Date: {parameter_name.end_date}

Designing the workflow

The workflow logic is constructed using a sequence of Steps. Steps execute sequentially, and data extracted from one step can be used in subsequent steps.

REST steps

A REST Step executes a single HTTP request.

Configuration:

• Method: Select the HTTP verb (GET, POST, PUT, DELETE).

• Endpoint: Enter the resource path. For example, /customers.

  Tip: Use {variable} syntax to inject values from previous steps.

• Headers/Query Params: Define static or dynamic request metadata.

Data extraction - Variables output

To persist data for later use:

1. In the Variables Output section, click Add.
2. Variable Name: Define a key. For example, customer_ids.
3. Response Location: Select Data (Body) or Header.
4. Transformation: Use JSON Path to extract specific values. For example:
   $.data.customers[*].id extracts an array of IDs.

Pagination

Enable Pagination to automatically traverse multi-page responses.

• Page-based: Increments a counter (Page 1, 2, 3...).
• Offset-based: Skips records (Skip 0, 50, 100...).
• Cursor-based: Uses a next_token from the response.
• Break Conditions: Define rules to halt pagination. For example, Stop when items array is empty.

Retry strategy

Define policies to handle transient failures. For example, 429 Too Many Requests, 500 Internal Server Error.

Configuration: Retry 3 times with a 5 second interval for status code 500.

Working with loops

Loops enable iteration over collections of data.

Loop types

Type A: Standard loop (Iterate API results)

• Use Case: You fetched a list of items in Step 1 and need to process each item in Step 2.
• Source: Variable from a previous step. For example, users.
• Item Name: Define an alias for the current item. For example, user.
• Usage: In the nested step, reference the item using {{%user%}}.

Endpoint Example:
/users/{{%user%}}/details

Type B: External loop (Iterate source data)

• Use Case: The connector receives a list of IDs directly from the Source-to-Target River.
• Condition: The loop Block must be the First Step in the workflow.
• Variable Syntax: You must use the {ext.} prefix.

Correct syntax:
{ext.my_source_ids}

Warning: Omitting ext. causes the loop to fail as it will look for an internal variable.

Variable reference

Use the following syntax patterns to inject dynamic data into your configuration.

Context	Syntax	Description	Example
Internal Variables	{{%BASE_URL%}}	Data extracted from a previous step.	{{%BASE_URL%}}/orders
Loop Item	{{%item_name%}}	Properties of the current item in a loop.	/users/{{%user%}}
User Inputs	{param_name}	Values entered by the user in Interface Parameters.	?status={status_filter}
Date Start	{start_date.param}	The start date from a Date Range picker.	from={start_date.dates}
Date End	{end_date.param}	The end date from a Date Range picker.	to={end_date.dates}
External Data	{ext.variable_name}	Data passed from the River (Loop source only).	{ext.incoming_ids}

Best practices

• Naming conventions: Use clear, snake_case names for variables. For example, user_details instead of data.
• JSON path testing: Verify your JSON paths against sample API responses to ensure data is extracted correctly.
• Error handling: Always configure a Retry Strategy for 5xx errors to ensure river stability.