Truto connector

The Truto connector gives Envoy tasks access to Truto integrated accounts. Use unified methods when you want a stable model across providers, proxy methods when you need provider-specific endpoints, and custom methods for an approved endpoint not covered by the standard helpers.

Prerequisites

You need:

• a Truto API token stored as a secret;
• the Truto API base URL used by your environment;
• at least one active integrated account;
• the target account ID;
• permission for the resources and operations the task will use.

Create the connector from Connectors, test it, then use discovery to verify the account and resource before authoring a task.

Keep account selection explicit

The connector can access more than one integrated account. Pass integrated_account_id on calls:

arguments:
  integrated_account_id:
    type: string
    required: true
 
steps:
  - name: list_tickets
    type: call_method
    config: |
      {
        "connector": "truto",
        "method": "list",
        "args": {
          "integrated_account_id": arguments.integrated_account_id,
          "resource": "tickets",
          "unified_model": "ticketing"
        }
      }

Use a connector-backed template argument to let the job creator choose an account from a searchable list.

Unified methods

Use unified operations when the resource exists in a Truto unified API:

• list and get common resources;
• create, update, or delete supported records;
• keep task mappings stable when changing integration providers.

Every unified call requires unified_model. Consult that model for supported fields. Provider-specific fields can differ even when the unified resource name is the same.

Proxy methods

Use proxy methods when you need the third-party provider's native resource or shape:

- name: list_native_tickets
  type: call_method
  config: |
    {
      "connector": "truto",
      "method": "proxy_list",
      "args": {
        "integrated_account_id": arguments.integrated_account_id,
        "resource": "tickets",
        "query": {
          "status": "open"
        }
      }
    }

Proxy task logic is provider-specific. Document the provider and API version assumptions and retest after provider changes.

Pagination and streaming

List methods expose a streaming cursor to call_method. Let the step consume it with backpressure. Do not collect all pages with $callMethod() inside a transform.

For discovery pickers, request one page and return its next_cursor. Search on the server rather than filtering a complete account or resource list in the browser.

Custom operations

A custom operation can describe an approved HTTP request through method configuration. Use it only when a unified or proxy helper is insufficient.

Mutating custom_create, custom_update, custom_request, and custom_upsert calls require a methodConfig object inside args.data. Without an appropriate body_format, the provider can receive an empty request body:

- name: create_custom_record
  type: call_method
  config: |
    {
      "connector": "truto",
      "method": "custom_create",
      "args": {
        "integrated_account_id": arguments.integrated_account_id,
        "path": arguments.custom_path,
        "data": $merge([
          input,
          {
            "methodConfig": {
              "method": "POST",
              "body_format": "json"
            }
          }
        ])
      }
    }

Keep:

• the integrated account ID explicit;
• the HTTP method and path fixed by authored configuration;
• secrets in the connector;
• pagination bounded;
• write payloads validated;
• response extraction documented.

Do not expose free-form method configuration to untrusted dashboard users.

Writes and retries

Before enabling writes:

1. verify the integrated account points to the intended tenant;
2. run a bounded read;
3. confirm required scopes;
4. send one test write;
5. inspect the provider response and Truto request identifiers;
6. retry only after reconciling ambiguous outcomes;
7. use a stable external or mapping key to avoid duplicates.

Provider rate limits and error shapes vary. Keep concurrency conservative and use idempotent migration patterns.

Troubleshooting

• Account not listed: verify it is active and visible to the token.
• Unauthorized: verify token, account ID, and scopes without logging the token.
• Resource not found: confirm unified versus proxy resource naming.
• No more records: preserve and pass the returned cursor exactly.
• Unexpected shape: inspect a bounded response and update the mapping; do not assume provider-native fields match a unified model.

See Connector catalog and connected accounts and Connector reference.