Skip to main content
Feedback

GraphQL operation (Early Access)

The GraphQL operation defines how to interact with the GraphQL endpoint configured on the connection. It holds the query or mutation text that executes at run time, together with the request and response profiles generated from that text.

Create a separate operation for each query or mutation you want to run. All operations that target the same endpoint can share one connection.

Import wizard

Click Import Operation on the operation component to open the import wizard, then:

  1. Select the Runtime (Atom, Molecule, or Cloud) and the GraphQL connection to browse with.
  2. Select the Execute type — Query or Mutation. This determines the object type offered in the next step and is checked against the text you paste.
  3. Paste the operation text into the GraphQL Query or Mutation field.
  4. Select the object type — Custom GraphQL Query or Custom GraphQL Mutation — and finish the wizard.

The connector parses the text, introspects the endpoint schema where it is available, and generates the request and response profiles. It also writes the text into the Custom GraphQL field on the operation, which is the text that executes at run time.

Example operation text

query GetOrder($id: ID!, $withLineItems: Boolean = true) {
  order(id: $id) {
    id
    name
    totalPrice
    lineItems(first: 10) @include(if: $withLineItems) {
      edges { node { title quantity } }
    }
  }
}

Declare every input value as a variable in the operation signature. Values inlined directly in the operation text are fixed for every execution and do not appear in the request profile.

Options tab

FieldDescription
Execute typeQuery or Mutation. Used during import only, to label the object type and to validate the operation text you paste. The default is Query.
GraphQL Query or MutationThe query or mutation text used during import to generate the request and response profiles and to populate the Custom GraphQL field. This field is read only during import — it is never used at run time. Required for import.
Custom GraphQLThe query or mutation text that executes at run time. It is created and pre-filled by the import from the GraphQL Query or Mutation text, and remains editable so you can hand-tune the executed text without repeating the import. Importing again overwrites this field.
Request ProfileThe JSON profile generated from the variables declared in the operation signature. Map to it to supply variable values at run time.
Response ProfileThe JSON profile generated from the operation's selection set, shaped as the GraphQL response envelope: data, errors, and extensions.
important

Editing Custom GraphQL changes what executes, but it does not regenerate the profiles. Changing the GraphQL Query or Mutation field alone changes nothing at run time. To update the profiles after changing the shape of the operation — adding a variable, adding or removing a selected field — run the import again.

Generated profiles

Request profile

The request profile is built from the variables declared in the operation signature. Each variable becomes a top-level field, typed from the schema where introspection is available.

GraphQL typeJSON profile type
IDstring
Stringstring
Intinteger (format int32)
Floatnumber (format float)
Booleanboolean
Enumstring
Custom scalar, for example DateTime or URLstring
Input objectobject, with its input fields expanded
List type, for example [String!]! or [[Int]]array, nested once per list level

A variable is marked as required in the profile only when it is non-null and has no default value. A non-null variable that declares a default may be omitted, because the server supplies the value.

Response profile

The response profile mirrors the GraphQL response envelope, so partial-success and error payloads are mappable with the same profile as a successful one:

{
  "data":       { "<the fields selected by the operation>": "" },
  "errors":     [ { "message": "...", "locations": "...", "path": "...", "extensions": "..." } ],
  "extensions": { "<endpoint-specific metadata, for example rate-limit cost>": "" }
}

Within data, each selected field becomes a property. Aliases are used as the property name in place of the field name, fragments are flattened into the parent, and __typename is emitted as a string. A field the connector cannot resolve against the schema is emitted as a string with a note in its description.

Run-time behavior

For each input document, the Connector step:

  1. Reads the input document as JSON. An empty input document is treated as an empty set of variables.
  2. Extracts and validates the variable values against the variables declared in Custom GraphQL.
  3. Builds the request body and sends it as an HTTP POST to the endpoint URL, with the connection's custom headers and authentication applied.
  4. Classifies the response, and returns one output document per input document.

The request body has the following shape. operationName is included only when the operation is named:

{
  "query":         "query GetOrder($id: ID!) { order(id: $id) { id name } }",
  "variables":     { "id": "gid://shopify/Order/123" },
  "operationName": "GetOrder"
}

Variable handling

Variable values are coerced according to the GraphQL specification before the request is sent:

  • A field that is absent from the input document is omitted from variables, so the server applies its own default. A field present with an explicit null is sent as null — this is how a mutation clears a value.
  • A single value supplied for a list variable is wrapped into a one-element list, recursively for nested list types.
  • Int, Float, and Boolean values are coerced from their textual forms and rejected locally when they cannot be coerced. This matters most for degraded profiles, where every field is typed as string.
  • Custom scalars, enums, and input objects are forwarded unchanged — the server is the authority on those.
  • A required variable that is missing or null, or a value that cannot be coerced to its declared type, fails the document before the request is sent.

Output documents

OutcomeStatus codeOutput document
Success200{ "data": {...}, "extensions": {...} }
Partial success206{ "data": {...}, "errors": [...], "extensions": {...} }
Application errorthe HTTP status returned by the endpoint{ "errors": [...], "extensions": {...} }

Because an application error still returns a document that matches the response profile, you can route it with a Decision or Route step and map the error detail rather than losing it in an exception message. To let a process continue past an application error, select Continue on the Connector step's error behavior, or catch it with a Try/Catch step.

Error messages

The following messages are raised by the connector itself, as opposed to being returned by the endpoint.

MessageCause and resolution
GraphQL operation text is required. Paste your Query into the "GraphQL Query or Mutation" field.The import was run with the GraphQL Query or Mutation field empty. Paste the operation text and import again.
GraphQL operation text is required but was not configured on the operationThe operation ran with an empty Custom GraphQL field. Run the import, or enter the text in Custom GraphQL.
Failed to parse GraphQL operation: ...The text contains a syntax error. The message carries the position reported by the parser.
GraphQL subscriptions are not supported by this connector. Only queries and mutations can be executed.Subscriptions require a streaming transport that a Connector step does not provide.
GraphQL document must contain exactly one operation.The text contains more than one operation definition. Split it into one operation per Boomi operation component. Fragment definitions alongside the operation are allowed.
Expected operation type QUERY but found MUTATION in the provided operation textThe Execute type selected in the wizard does not match the text pasted. Change one to match the other.
Required variable 'x' is missing from the input documentA non-null variable with no default was not supplied. Map a value to it in the request profile.
Required variable 'x' must not be null in the input documentA non-null variable was mapped, but the mapped value was null.
Variable 'x' expected Int but got: ...The mapped value cannot be coerced to the variable's declared type.
GraphQL endpoint returned error: ...Raised by Test Connection when the endpoint answers with a GraphQL error that is not about introspection — most often an authentication failure.
Test connection failed with HTTP nnn: ...The endpoint answered with a non-2xx status. Check the URL and the credentials.
Invalid GraphQL endpoint URL: ...The GraphQL Endpoint URL on the connection is not a valid absolute URL.
GraphQL request failed with HTTP nnn and an empty response body (no error details returned)The endpoint returned a failure with no body to report. The HTTP status distinguishes, for example, an authentication failure from a gateway timeout.
Endpoint returned a non-JSON response: ...The endpoint, or a proxy in front of it, answered with something that is not JSON, such as an HTML error page. The recovered text is included in the errors array of the output document.

Appendix: worked example

The following example configures an operation that retrieves a single order and its line items from a GraphQL API.

1. Configure the connection

FieldValue
GraphQL Endpoint URLhttps://example.myshopify.com/admin/api/2024-10/graphql.json
Authentication TypeNone
Custom HeadersX-Shopify-Access-Token = <your access token>
Connection Timeout (ms)30000
Read Timeout (ms)60000
Enable Connection PoolingSelected

Click Test Connection and confirm it succeeds before continuing.

2. Import the operation

Set Execute type to Query, paste the operation text below into GraphQL Query or Mutation, and run the import.

query GetOrder($id: ID!) {
  order(id: $id) {
    id
    name
    totalPriceSet { shopMoney { amount currencyCode } }
  }
}

3. Map the request

The generated request profile has one field, id, marked as required because $id is declared ID!. Map a value to it in the Map step that feeds the Connector step:

{ "id": "gid://shopify/Order/1234567890" }

4. Handle the response

A successful execution returns a document with status code 200:

{
  "data": {
    "order": {
      "id": "gid://shopify/Order/1234567890",
      "name": "#1001",
      "totalPriceSet": { "shopMoney": { "amount": "129.95", "currencyCode": "USD" } }
    }
  },
  "extensions": { "cost": { "requestedQueryCost": 4, "actualQueryCost": 4 } }
}

If the order id does not exist, the endpoint answers HTTP 200 with an errors array and no usable data. The connector marks the document as an application error and returns:

{
  "errors": [ { "message": "Order not found", "path": ["order"] } ]
}

Set the Connector step to continue on error, or wrap it in a Try/Catch step, and route on the errors array to handle the failure within the process.

On this Page