Execute Integration

Execute an integration activity through the Boltic workflow engine. By default, the SDK polls until the execution completes. Set executeOnly: true to return immediately after triggering.

Function Signature

client.workflow.executeIntegration(params: ExecuteIntegrationParams): Promise<BolticSuccessResponse<ExecuteActivityResponseData | IntegrationExecutionData> | BolticErrorResponse>

Parameters

Parameter	Type	Required	Description
data	object	✅	Activity data describing what to execute
data.type	string	✅	Activity type (e.g., "apiActivity")
data.name	string	✅	Activity name (used as identifier)
data.properties	object	✅	Activity-specific properties (varies by integration)
executeOnly	boolean	❌	If true, return immediately without polling. Default: false
result	object	❌	Context payload (payload + global_variables). Defaults to empty objects.

Execute and Wait for Result (Default)

The SDK automatically polls until the execution reaches a terminal state:

import { createClient } from "@boltic/sdk";

const client = createClient("your-api-key");

const result = await client.workflow.executeIntegration({
    data: {
        type: "apiActivity",
        name: "fetch-products",
        properties: {
            method: "get",
            endpoint: "https://dummyjson.com/products",
            query_params: {},
            headers: {},
            body: null,
            body_type: "none",
            api_timeout: 30000,
            maximum_timeout: 60000,
            integration_slug: "blt-int.api",
        },
    },
});

if (result.error) {
    console.error("Execution failed:", result.error.message);
} else {
    console.log("Execution result:", result.data);
}

Fire-and-Forget (executeOnly)

Return immediately after triggering the activity. Use the returned execution_id to check results later:

const result = await client.workflow.executeIntegration({
    data: {
        type: "apiActivity",
        name: "fetch-products",
        properties: {
            method: "get",
            endpoint: "https://dummyjson.com/products",
            integration_slug: "blt-int.api",
        },
    },
    executeOnly: true,
});

if (!result.error) {
    const executionId = result.data.execution_id;
    console.log("Execution started:", executionId);

    // Check the result later
    const execResult = await client.workflow.getIntegrationExecuteById(executionId);
    console.log("Result:", execResult.data);
}

Activity Properties

The properties object varies by integration type. Common properties for API activities:

Property	Type	Description
method	string	HTTP method (get, post, put, delete)
endpoint	string	Target URL
query_params	object	URL query parameters
headers	object	Request headers
body	unknown	Request body (for POST/PUT)
body_type	string	Body content type (none, json, form-data)
api_timeout	number	Timeout in milliseconds
maximum_timeout	number	Maximum timeout in milliseconds
integration_slug	string	Integration identifier (e.g., blt-int.api)

Passing Context

Provide a result payload to pass context or global variables to the activity:

const result = await client.workflow.executeIntegration({
    data: {
        type: "apiActivity",
        name: "create-order",
        properties: {
            method: "post",
            endpoint: "https://api.example.com/orders",
            body: { product_id: "123", quantity: 2 },
            body_type: "json",
            integration_slug: "blt-int.api",
        },
    },
    result: {
        payload: { user_id: "user-456" },
        global_variables: { api_version: "v2" },
    },
});

Error Handling

const result = await client.workflow.executeIntegration({
    data: {
        type: "apiActivity",
        name: "api-call",
        properties: {
            method: "get",
            endpoint: "https://api.example.com/data",
            integration_slug: "blt-int.api",
        },
    },
});

if (result.error) {
    switch (result.error.code) {
        case "MISSING_EXECUTION_ID":
            console.error("API did not return an execution ID");
            break;
        case "EXECUTION_TIMEOUT":
            console.error("Execution did not complete within the polling window");
            break;
        default:
            console.error("Error:", result.error.message);
    }
}

Polling Behavior

When executeOnly is false (default):

• The SDK polls getIntegrationExecuteById every 1 second
• Maximum 30 polling attempts (30 seconds total)
• Returns the final result when the execution data is non-empty
• Returns an EXECUTION_TIMEOUT error if polling is exhausted