GraphQL connector (Early Access)
Early Access. The GraphQL connector is released as Early Access. Functionality and field names may change before general availability.
The GraphQL connector enables you to execute GraphQL queries and mutations against any GraphQL API endpoint from within a Boomi Integration process. Communication takes place over HTTPS using JSON, and every request is sent as an HTTP POST to a single endpoint URL, as the GraphQL specification requires.
Unlike connectors built for one application, the GraphQL connector is generic: it is not bound to a fixed catalog of objects. You supply the GraphQL query or mutation text yourself, and the connector parses that text during the import wizard to generate the request and response profiles for you. The same text is stored on the operation and executed at run time.
Connector configuration
To configure a connector to communicate with a GraphQL API, set up two components:
- GraphQL connection — the endpoint URL, the authentication method, and the HTTP behavior (custom headers, timeouts, and connection pooling) used for every request.
- GraphQL operation — the GraphQL query or mutation text to execute, and the request and response profiles generated from it.
Supported operation
The connector exposes a single operation.
| Operation | Type | Description |
|---|---|---|
| Execute | Outbound | Sends an HTTP POST to the configured GraphQL endpoint containing the query or mutation text, the variable values taken from the input document, and the name of the operation. Returns the GraphQL response envelope as the output document. |
During the import wizard you choose whether the operation executes a query or a mutation using the Execute type field. This selection determines the object type presented by the wizard — Custom GraphQL Query or Custom GraphQL Mutation.
Prerequisites
To implement a connection to a GraphQL API, have the following ready:
- The full URL of the GraphQL endpoint, for example
https://your-store.myshopify.com/admin/api/2024-10/graphql.json. - The credentials required by the endpoint. Where the API uses OAuth 2.0 client credentials, have the client ID, client secret or signing certificate, access token URL, and scopes available. Where the API uses an API key or a static token, know the header name and value the API expects.
- The text of the query or mutation you intend to run, with every input value declared as a GraphQL variable in the operation signature, for example
query GetOrder($id: ID!). - Network access from the Runtime (Basic, Cluster or Cloud) that runs the process to the GraphQL endpoint.
Schema introspection is used during the import wizard to type the generated profiles accurately. Introspection is not required — see Endpoints with introspection disabled — but profiles are noticeably more accurate when it is available.
Supported GraphQL features
| Feature | Supported | Detail |
|---|---|---|
| Queries |  | Executed as an HTTP POST with the query text in the request body. |
| Mutations | | Executed the same way; select Mutation as the Execute type. |
| Variables | | Variables declared in the operation signature become the fields of the generated request profile, and are populated from the input document at run time. |
| Named operations | | The operation name is sent in the request body as operationName. |
| Fragments | | Named fragment spreads and inline fragments are resolved and flattened into the generated response profile. |
| Aliases | | An alias is used as the JSON property name in the response profile. |
__typename | | Emitted as a string field in the response profile when selected. |
| Custom scalars | | Typed as string in the generated profiles. |
| Subscriptions |  | Rejected during import and at run time with an explicit message. There is no streaming transport in a Boomi Connector step. |
| Multiple operations per document | | The document must contain exactly one operation definition. Fragment definitions in the same document are permitted. |
| Automatic pagination | | Cursor or page handling must be modelled in the process, for example with a Flow Control or looping pattern. |
| File uploads (multipart) | | Only application/json request bodies are sent. |
Endpoints with introspection disabled
Many production GraphQL APIs disable or restrict schema introspection. The connector does not fail in that case. When the schema cannot be retrieved, the import wizard falls back to a degraded profile derived from the structure of the operation text alone, and both generated profiles carry a description recording that they are approximate.
In a degraded profile:
- Every leaf field is typed as string, because the real scalar type is unknown.
- A field that the endpoint actually returns as a list is modelled as an object.
- Fields with a sub-selection still become nested objects, and fragments are still resolved.
Correct list fields in the generated response profile before you map them.
Error processing
A GraphQL endpoint commonly answers with HTTP 200 even when the operation failed, placing the failure detail in an errors array in the response body. The connector therefore classifies each response on both the HTTP status and the body content, and reports the outcome as follows.
| Response | Outcome | Document status |
|---|---|---|
| HTTP 2xx, data present, no errors | Success | The output document is returned with status code 200. |
| HTTP 2xx, both data and errors present | Partial success | The output document is returned with status code 206 and carries data, errors, and extensions so the process can inspect both. |
| HTTP 2xx with errors and no usable data, or any non-2xx status | Application error | The document is marked as an application error, carrying the actual HTTP status code returned by the endpoint. The payload contains errors and extensions so the failure can be routed or mapped downstream. |
| Variable validation failure before the request is sent | Failure | The document fails with a message naming the variable at fault. |
| Transport failure, or a response that cannot be read | Failure | The document fails with the underlying cause in the message. |
Where the endpoint answers with something other than a GraphQL envelope — an HTML error page from a proxy, an OAuth 2.0 token error, or a top-level array of error objects from an API gateway — the connector recovers the diagnostic text and rewrites it into the standard errors shape, so the cause reaches the process instead of being discarded. Recovered messages are truncated at 2,000 characters so a large error page cannot flood the process log.
Document tracking
The connector tracks user-defined document properties. The document tracked ID and any tracked fields configured on the operation are visible in Process Reporting for each document processed by the Connector step.
