PermuteDocs
Go to Permute

Actions and automation

Call the SDK from a Business Action

Declare platform methods and resource permissions, use stable step IDs, and send operational email through an approved action.

Before you start

Workflow

  1. 1Declare the exact platform methods and permissions with the action definition. Saving requires source Read; publication requires authority to delegate the declared access.
  2. 2Use the handler examples below with matching input and output schemas. The upload example expects fileName, contentType, and sizeBytes; the email example expects recipient and the workspace emailSender binding.
  3. 3Assign a stable ID to each logical SDK step. Test successful, rejected, and uncertain outcomes before authorizing real effects.

Call the SDK from an action

Declare platform.methods and platform.permissions in the action definition. The handler receives platform.withStep(stepId) with the existing SDK method signatures. The server runs the SDK itself (returned dataset helpers become plain data). For datasets.create with type: file, omit data and provide sizeBytes to create a dataset and return its signed upload target. Providing data also uploads the bytes inside the action.

For workspaceMembers.list, declare { resourceType: 'membership', resourceId: '*', level: 'read' } in platform.permissions. The API evaluates this action grant only within the action workspace, independently of later creator access.

Give every SDK call a distinct, stable step ID, including reads. Step IDs belong to the action, caller, and requestId combination; different invocations can reuse the same names. Use deterministic IDs such as upload_sales or upload_<recordId>, not random values or counters that change when branches change.

Saving requires Read on each declared resource (resource-type Read for wildcards). Publishing requires Admin to delegate those permissions (resource-type Admin for wildcards). Callers need the action’s invocation permission. Each SDK request uses only the selected action revision’s declared grants, with current session, key, app, and action-access checks. Workspace overrides are rejected.

An SDK write can succeed before the action finishes, so retrying the whole action must not repeat that write. A completed step with the same SDK method and arguments returns its saved result; reusing its ID for a different call returns request_conflict. Reads also replay saved results. A failed call or lost result returns outcome_unknown and blocks automatic resend until external state is checked. SDK effects cannot roll back with local database changes. Queued operations recheck action scope before input access and output publication.

Use workspace SDK methods within the action’s 15-second budget, 100-step limit, 1 MB request limit per step, and 1 MB aggregate stored-result limit. Organization/global routes, nested actions, answer jobs, and Write Sync are excluded. Large files can use an action to approve metadata and return an upload target; the browser sends bytes directly to storage using the returned method and every returned header. Poll processing status outside that invocation through an authorized API read or a separate status action if the caller lacks direct dataset access.

typescript
// Add this to the action definition, then publish:
// platform: { methods: ['datasets.create'], permissions: [
//   { resourceId: '*', resourceType: 'dataset', level: 'write' },
// ] }
exports.handler = async ({ input, platform }) => {
  const dataset = await platform.withStep('upload').datasets.create({
    type: 'file', fileName: input.fileName, contentType: input.contentType,
    sizeBytes: input.sizeBytes,
  });
  return { datasetId: dataset.id, upload: dataset.upload };
};

Send operational email

Workspace Settings → Email shows your automatically provisioned sending address. An email-ready connected delegated domain supplies noreply@your-domain; otherwise the workspace uses the Permute default. DNS records and verification are managed automatically, with no second setup form or TXT step. Wait for Ready to send before invoking an action. No mailbox is created. Get the current address and permission resource ID with client.emails.get().

Declare emails.send in platform.methods and Write on the workspace emailSender resource in platform.permissions. Draft authors need sender Read; publishers need sender Admin to delegate sending. Callers need the action’s Run permission. The permission covers automatic address changes when a domain is connected or removed. Direct REST or SDK sends outside an action are denied, so each send stays inside the action’s durable step ledger.

The handler controls the subject, required text fallback and optional HTML without a forced wrapper. Escape values substituted into HTML. Keep templates in published action code so changes receive the same review as its other effects. The From address follows the workspace’s automatic address.

Use a stable step ID for each logical message. Accepted means SES accepted the request, not that the recipient received it. Successful steps replay, while uncertain sends block automatic retries. Emails cannot be rolled back when a later database write or output validation fails. Each message allows up to 10 visible To recipients and 200 KB; each workspace has a fixed 1,000-recipient-attempt budget per UTC day.

typescript
// Definition fragment, reviewed and published with the handler:
// platform: {
//   methods: ['emails.send'],
//   permissions: [{ resourceId: senderId, resourceType: 'emailSender', level: 'write' }],
// }
exports.handler = async ({ inputs, platform }) => {
  const message = await platform.withStep('send-order-update').emails.send({
    to: [inputs.recipient],
    subject: 'Order ready',
    text: 'Your order is ready for collection.',
  });
  return { messageId: message.id, status: message.status };
};