Waiting for engine...
Skip to main content

Boomi Platform API Reference (1.0.0) - GlobalVariable

Toggle Pane
API docs by Redocly

License: Boomi API License and Rate Limits

Download OpenAPI Specification: Download

Run In Postman

For more information about Postman collections, forking, and making your first API call, refer to the Working with Boomi APIs on Postman page.

GlobalVariable

The GlobalVariable API allows creation, retrieval, update, and querying of Global Variable definitions within a Boomi account. Global Variables are named, account-scoped variables that can hold different values per environment, and support optional encryption for sensitive data.

You assign different values per environment using the GlobalVariableValue API. Each Global Variable has an optional initial value, an optional description, and a lifecycle status (active or archived). You can encrypt variables to protect sensitive values.

The name field serves as the object ID. When a variable is created, an initial UpdateTransaction record is automatically created to start the audit trail.

Account requirement: The GLOBAL_VARIABLES feature must be enabled on the account for this API to work. If it is not, all operations return 403 Forbidden with the message "Global Variable is inactive". To enable the feature, contact your Boomi Account representative.

Required Privileges

You need these privileges in the target environment:

Write access

  • GLOBAL_VARIABLE_CREATE — Create and edit Global Variables.

Read access (any one of the following)

  • BUILD — Design, build, and modify processes and components.
  • BUILD_READ_ACCESS — View processes and components.
  • BRANCH_COMPONENT_READ_WRITE — Read access to processes and components on all branches; write access on all branches except main.

Note:
- Available on all runtime types.
- DELETE operation is not supported. To decommission a variable, set its status to archived.
- Archived variables retain their history and values but cannot receive new value assignments.
- An account-level limit on the number of active Global Variables is enforced on CREATE and on re-activation from archived status.

For more information, refer to the related APIs:

Retrieves an instance of a GlobalVariable object

Retrieves a single Global Variable by name.

Authorizations:
basicAuth
path Parameters
id
required
string

The name of the Global Variable to retrieve.

Responses

Response Schema:
name
string

Unique name for the Global Variable within the account. Serves as the object ID in URL paths.

encrypted
boolean
Default: false

Whether the variable's assigned values are stored encrypted. Once set to true, cannot be changed back to false.

initialValue
string

Optional default value automatically assigned to environments that have not yet been explicitly assigned a value.

description
string

Optional human-readable description of the variable's purpose.

status
string
Default: "active"
Enum: "active" "archived"

Lifecycle state of the variable. Archived variables cannot be assigned new values. Re-activating from archived to active triggers a limit check.

createdBy
string

Username or email of the user who created the variable. This value is set automatically by the platform and cannot be edited.

createdDate
string <date-time>

ISO 8601 timestamp of when the variable was created. This value is set automatically by the platform and cannot be edited.

modifiedBy
string

Username or email of the user who last modified the variable. This value is set automatically by the platform and cannot be edited.

modifiedDate
string <date-time>

ISO 8601 timestamp of the last modification. This value is set automatically by the platform and cannot be edited.

Response samples

Content type
{
  • "@type": "GlobalVariable",
  • "name": "MY_VARIABLE",
  • "encrypted": false,
  • "initialValue": "defaultValue",
  • "description": "A sample global variable",
  • "status": "active",
  • "createdBy": "user@example.com",
  • "createdDate": "2025-01-01T00:00:00Z",
  • "modifiedBy": "user@example.com",
  • "modifiedDate": "2025-01-01T00:00:00Z"
}

Modifies or updates a GlobalVariable object

Updates an existing Global Variable identified by name. Re-activating an archived variable (status change from archived to active) triggers an account-level limit check.

Authorizations:
basicAuth
path Parameters
id
required
string

The name of the Global Variable to update.

Request Body schema:
optional
name
string

Unique name for the Global Variable within the account. Serves as the object ID in URL paths.

encrypted
boolean
Default: false

Whether the variable's assigned values are stored encrypted. Once set to true, cannot be changed back to false.

initialValue
string

Optional default value automatically assigned to environments that have not yet been explicitly assigned a value.

description
string

Optional human-readable description of the variable's purpose.

status
string
Default: "active"
Enum: "active" "archived"

Lifecycle state of the variable. Archived variables cannot be assigned new values. Re-activating from archived to active triggers a limit check.

Responses

Response Schema:
name
string

Unique name for the Global Variable within the account. Serves as the object ID in URL paths.

encrypted
boolean
Default: false

Whether the variable's assigned values are stored encrypted. Once set to true, cannot be changed back to false.

initialValue
string

Optional default value automatically assigned to environments that have not yet been explicitly assigned a value.

description
string

Optional human-readable description of the variable's purpose.

status
string
Default: "active"
Enum: "active" "archived"

Lifecycle state of the variable. Archived variables cannot be assigned new values. Re-activating from archived to active triggers a limit check.

createdBy
string

Username or email of the user who created the variable. This value is set automatically by the platform and cannot be edited.

createdDate
string <date-time>

ISO 8601 timestamp of when the variable was created. This value is set automatically by the platform and cannot be edited.

modifiedBy
string

Username or email of the user who last modified the variable. This value is set automatically by the platform and cannot be edited.

modifiedDate
string <date-time>

ISO 8601 timestamp of the last modification. This value is set automatically by the platform and cannot be edited.

Request samples

Content type
{
  • "name": "MY_VARIABLE",
  • "description": "Updated description",
  • "status": "archived"
}

Response samples

Content type
{
  • "@type": "GlobalVariable",
  • "name": "MY_VARIABLE",
  • "encrypted": false,
  • "initialValue": "defaultValue",
  • "description": "Updated description",
  • "status": "archived",
  • "createdBy": "user@example.com",
  • "createdDate": "2025-01-01T00:00:00Z",
  • "modifiedBy": "user@example.com",
  • "modifiedDate": "2025-06-01T00:00:00Z"
}

Creates a GlobalVariable object

Creates a new Global Variable. The name field is required and serves as the object ID; it must be unique within the account.

Authorizations:
basicAuth
Request Body schema:
optional
name
string

Unique name for the Global Variable within the account. Serves as the object ID in URL paths.

encrypted
boolean
Default: false

Whether the variable's assigned values are stored encrypted. Once set to true, cannot be changed back to false.

initialValue
string

Optional default value automatically assigned to environments that have not yet been explicitly assigned a value.

description
string

Optional human-readable description of the variable's purpose.

status
string
Default: "active"
Enum: "active" "archived"

Lifecycle state of the variable. Archived variables cannot be assigned new values. Re-activating from archived to active triggers a limit check.

Responses

Response Schema:
name
string

Unique name for the Global Variable within the account. Serves as the object ID in URL paths.

encrypted
boolean
Default: false

Whether the variable's assigned values are stored encrypted. Once set to true, cannot be changed back to false.

initialValue
string

Optional default value automatically assigned to environments that have not yet been explicitly assigned a value.

description
string

Optional human-readable description of the variable's purpose.

status
string
Default: "active"
Enum: "active" "archived"

Lifecycle state of the variable. Archived variables cannot be assigned new values. Re-activating from archived to active triggers a limit check.

createdBy
string

Username or email of the user who created the variable. This value is set automatically by the platform and cannot be edited.

createdDate
string <date-time>

ISO 8601 timestamp of when the variable was created. This value is set automatically by the platform and cannot be edited.

modifiedBy
string

Username or email of the user who last modified the variable. This value is set automatically by the platform and cannot be edited.

modifiedDate
string <date-time>

ISO 8601 timestamp of the last modification. This value is set automatically by the platform and cannot be edited.

Request samples

Content type
{
  • "name": "MY_VARIABLE",
  • "encrypted": false,
  • "initialValue": "defaultValue",
  • "description": "A sample global variable"
}

Response samples

Content type
{
  • "@type": "GlobalVariable",
  • "name": "MY_VARIABLE",
  • "encrypted": false,
  • "initialValue": "defaultValue",
  • "description": "A sample global variable",
  • "status": "active",
  • "createdBy": "user@example.com",
  • "createdDate": "2025-01-01T00:00:00Z",
  • "modifiedBy": "user@example.com",
  • "modifiedDate": "2025-01-01T00:00:00Z"
}

Retrieves multiple GlobalVariable objects by identifier

List of GlobalVariable identifiers to retrieve. To learn more about bulk, refer to the topic Bulk GET operations.

Authorizations:
basicAuth
Request Body schema:
optional
Array of objects (BulkId)
type
string
Enum: "CREATE" "DELETE" "GET" "UPDATE"

Responses

Response Schema:
Array of objects
Array
required
object (GlobalVariable)
index
integer <int32>
id
string
statusCode
integer <int32>
errorMessage
string

Request samples

Content type
{
  • "type": "GET",
  • "request": [
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
{
  • "response": [
    • {
      },
    • {
      }
    ]
}

Queries for a GlobalVariable object(s)

Filter criteria for the GlobalVariable query. For general information about the structure of QUERY filters, their sample payloads, and how to handle the paged results, refer to Query filters and Query paging.

Authorizations:
basicAuth
Request Body schema:
optional
required
object
object

Responses

Response Schema:
numberOfResults
integer <int32>
queryToken
string

By default, the queryToken parameter is not available in the query response. It appears only when the query response contains more than 100 results. The maximum number of results returned per query is 100. To retrieve the next set of results, use the queryToken in the queryMore request.

Array of objects (GlobalVariable)

Request samples

Content type
Example
{
  • "QueryFilter": {
    • "expression": {
      }
    }
}

Response samples

Content type
{
  • "@type": "QueryResult",
  • "result": [
    • {
      }
    ],
  • "numberOfResults": 1
}

Retrieves additional results for a GlobalVariable query

To learn about using queryMore, refer to the topic Query paging.

Authorizations:
basicAuth
Request Body schema: text/plain
required
string

Query token from the previous query response used to retrieve the next page of results.

Responses

Response Schema:
numberOfResults
integer <int32>
queryToken
string

By default, the queryToken parameter is not available in the query response. It appears only when the query response contains more than 100 results. The maximum number of results returned per query is 100. To retrieve the next set of results, use the queryToken in the queryMore request.

Array of objects (GlobalVariable)

Request samples

Content type
text/plain
/nd0PlROcmuUK8MV8KPzCVXwA/pgZZ0NfsYjhqLNyothPzrFIh0OQLP6Hq3ERMSAl38Dz3NV5otJ/0+a....

Response samples

Content type
{
  • "@type": "QueryResult",
  • "result": [
    • {
      }
    ],
  • "numberOfResults": 1
}