Skip to main content

Configure an operator

An operator contract has four user-visible parts: identity, execution, methods, and authorization. Configure only runtime types available in the current catalog.

Identity​

Use a stable, unique identifier and a clear action-oriented name.

FieldGuidance
NameDescribe one action, such as “Read customer profile”
IdentifierStable machine name; avoid changing it after use
DescriptionExplain when to use the operator and important exclusions
Category / tagsMake catalog discovery reliable
StatusOnly active operators are available to consumers

Execution​

Built-in Worker operator​

Built-in operators run in GeniSpace Worker. Users select and configure them from the catalog; their runtime implementation is platform-managed. Do not copy a built-in definition to change its code. Configure the exposed method inputs, connections, and permissions instead.

REST API operator​

A REST API operator calls an external HTTPS service. Configure:

  • base or server URL and method path;
  • HTTP method and content type;
  • header, path, query, and body mappings;
  • connection or secret references for authentication;
  • timeout and safe retry policy;
  • expected success status and output mapping.

Use environment variables or ConfigMap references for deployment-dependent values. Do not store access tokens in descriptions, sample values, or exported workflow JSON.

Datasource operation​

Datasource operations execute through a configured connection. The connection owns credentials; the operation owns typed parameters and expected output. Test access in the same Space and role that will run the workflow.

Methods​

An operator can expose one or more methods. Each method should represent one coherent operation and define:

{
  "name": "getCustomer",
  "description": "Read one customer by its platform ID",
  "inputSchema": {
    "type": "object",
    "required": ["customerId"],
    "properties": {
      "customerId": {
        "type": "string",
        "description": "Stable customer ID"
      }
    },
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "required": ["found"],
    "properties": {
      "found": { "type": "boolean" },
      "customer": { "type": ["object", "null"] }
    }
  }
}

Use the editor-generated form where possible. If JSON Schema editing is available, keep it compatible with the validation shown in the UI.

Input Schema rules​

  • Use object as the method input root.
  • Put fields under properties and list truly required fields in required.
  • Use string, number, integer, boolean, array, or object consistently.
  • Add enum for a closed set of valid values.
  • Define array items and nested object properties.
  • Distinguish omitted, null, empty string, and empty array intentionally.
  • Set additionalProperties: false when unknown input should be rejected.
  • Give every business field a description meaningful to workflow authors and agents.

Avoid one untyped “payload” object unless the remote API genuinely has a dynamic contract.

Output Schema rules​

Return facts that downstream nodes or an agent can use. A robust result normally distinguishes:

  • successful result with data;
  • successful result with no match;
  • validation failure;
  • authorization failure;
  • remote or runtime failure.

Do not return only “Operation completed.” Include stable IDs, affected record counts, status, and safe error information when applicable. Exclude secrets and fields the caller is not authorized to see.

Mapping​

In WorkflowStudio, map an upstream output path to each input. The editor validates compatible types, but it cannot guarantee the business meaning. Test nulls, empty arrays, nested objects, dates, and numeric conversions.

For a REST API operator, keep transport concerns separate from business output. For example, map the remote response body into a stable output object rather than requiring every workflow to understand provider-specific envelopes.

Timeout and retry​

  • Set a timeout below the parent task timeout.
  • Retry transient network and 5xx failures only when the operation is safe.
  • Do not automatically retry a non-idempotent write without an idempotency key.
  • Treat validation and authorization errors as final.
  • Return enough error metadata for diagnostics without exposing credentials or confidential payloads.

Authorization​

Operator activation does not bypass access control. The caller must have access to the operator, connection, Dataset or Datasource, and target Space resource. Agent tool catalogs apply additional filtering by agent form, Chat mode, application-local provider, and permissions.

Validation checklist​

  1. Identifier is unique and stable.
  2. Input and output schemas are explicit.
  3. Authentication uses a managed connection or secret reference.
  4. Success, empty, invalid, forbidden, timeout, and remote-failure cases are tested.
  5. Write retries are idempotent.
  6. Logs and results do not expose sensitive values.
  7. Existing workflows and agents have been checked before a breaking contract change.