39  Automations Admin Guide

39.1 Overview

This guide covers how to enable and configure Sophea Automations for your workspace, including Portal setup, email configuration, and model routing.

39.2 Enabling Automations in Portal

39.2.1 Prerequisites

  • Sophea platform deployed and running (Nous, Portal, RAG service)
  • Portal admin access
  • At least one workspace created

39.2.2 Steps

  1. Log in to the Portal admin console
  2. Navigate to the workspace settings
  3. Enable the “Automations” feature toggle
  4. The automations builder will be available at /automations in the Nous web UI

39.2.3 Shell mode

Shell mode restricts the available pieces to a vetted allowlist. This is recommended for production environments. To enable shell mode:

  1. Set NOUS_AUTOMATIONS_SHELL=true in the Automations API server environment
  2. Add NOUS_AUTOMATIONS_SHELL to AP_SANDBOX_PROPAGATED_ENV_VARS so pieces can read it inside the sandbox
  3. Verify that only allowlisted pieces appear in the builder

The shell mode allowlist includes 18 vetted pieces: - @activepieces/piece-sophea (all Sophea actions and triggers) - @activepieces/piece-manual-trigger (manual trigger) - @activepieces/piece-schedule (time-based triggers) - @activepieces/piece-webhook (HMAC-signed webhook trigger) - @activepieces/piece-tables (data tables) - @activepieces/piece-forms (forms and human input) - @activepieces/piece-file-helper (file operations) - @activepieces/piece-csv (CSV operations) - @activepieces/piece-data-mapper (data transformation) - @activepieces/piece-data-summarizer (data summarization) - @activepieces/piece-date-helper (date utilities) - @activepieces/piece-delay (delay step) - @activepieces/piece-math-helper (math operations) - @activepieces/piece-pdf (PDF operations) - @activepieces/piece-qrcode (QR code generation) - @activepieces/piece-store (key-value storage) - @activepieces/piece-text-helper (text utilities) - @activepieces/piece-xml (XML operations)

39.3 Configuring Workspace Email

Sophea Automations can send emails on behalf of workspace members. The send_workspace_email action uses the platform’s email provider.

39.3.1 Prerequisites

  • SMTP server configured in the Nous backend
  • Workspace email settings enabled in Portal

39.3.2 Configuration

  1. Configure the SMTP server in the Nous backend deployment
  2. Set the following environment variables on the Nous backend:
    • SMTP_HOST: SMTP server hostname
    • SMTP_PORT: SMTP server port (usually 587 for TLS)
    • SMTP_USER: SMTP username
    • SMTP_PASSWORD: SMTP password
    • SMTP_FROM_EMAIL: From email address
    • SMTP_FROM_NAME: From display name
  3. Verify email delivery by running a flow with the send_workspace_email action

39.3.3 Email behavior

  • Emails are sent as the workspace, not as individual users
  • The recipientMode can be RUN_USER (send to the person who ran the flow) or WORKSPACE_MEMBERS (send to selected workspace members)
  • Email body can be plain text or markdown (converted to HTML)

39.4 Setting Up Model Routing

Sophea Automations uses the same visible CHAT model and Workspace default configured for Nous. Runtime actions call the Nous broker directly. Generate and Refine use the Portal model proxy, but both surfaces enforce the same Workspace authority.

39.4.1 Workspace authority

  1. A platform administrator makes W2, W3, and W4 available to the Workspace.
  2. A Workspace administrator chooses one visible CHAT model as the default for that existing Workspace.
  3. Account-level defaults affect future Workspace provisioning only, unless the administrator explicitly applies a change to existing Workspaces.
  4. Hiding a model removes it from chat, action, Generate, and Refine selectors without physically deleting the catalog row.

39.4.2 Available models

The model selector lists Workspace default plus the visible explicit models available to the Workspace. workspace_default remains stored in the flow and resolves the live default every time the flow runs, so changing W3 to W4 updates unchanged flows without a restart.

Generate with Nous model action settings with Workspace default selected as sophea-w4

Automations action settings showing the live Workspace default model

A saved explicit model that is later hidden runs on the current Workspace default and records the requested model, executed model, and fallback reason in the run audit. A missing, deleted, malformed, non-CHAT, or different-Workspace model ID fails before a provider call.

Generate and Refine refresh the catalog when opened and again before submission. If an explicit selection disappears before the click completes, the operation stops, refreshes the selector, and waits for the user to choose or retry.

39.4.3 Model parameters

The ask_workspace_model action accepts: - prompt: The text prompt (required) - systemPrompt: System instructions (optional) - modelId: Model alias (default: workspace_default) - temperature: Sampling temperature (0-1, default varies by model)

39.5 Configuring Webhooks

39.5.1 HMAC-signed webhooks

The webhook trigger (@activepieces/piece-webhook) supports HMAC signature verification. In shell mode, only HEADER and HMAC auth types are allowed.

39.5.2 Setup

  1. Add a webhook trigger to a flow
  2. Set the auth type to HMAC
  3. Configure the HMAC secret in the webhook piece settings
  4. The webhook URL will be available at /automations/webhooks/{flow-id}
  5. External systems must send the X-Sophea-Signature header with the HMAC-SHA256 signature

39.5.3 Verification

The webhook piece verifies: - The X-Sophea-Signature header matches the HMAC-SHA256 of the request body - The X-Sophea-Timestamp header is within the acceptable time window - In shell mode, AuthType.NONE and AuthType.BASIC are rejected

39.6 Managing Templates

39.6.1 Built-in templates

Sophea ships with 43 domain templates across 9 categories, plus 8 starter templates: - Knowledge (11) - Reports (11) - Research (10) - Review (8) - Approvals (5) - Email (4) - Data (3) - Legal (1) - HR (1)

Some templates appear in more than one category, so the per-category counts sum to more than 43.

The 8 starter templates cover common starting points: asking a workspace model, daily web research email, answering from indexed knowledge, daily knowledge digest email, structured extraction, content review approval, Excel-ready CSV report, and agent web research report.

39.6.2 Custom workspace templates

Workspace admins can create custom templates: 1. Build a flow in the builder 2. Save it as a template from the flow settings 3. The template will be available in the template gallery for all workspace members

39.6.3 Template categories

Templates are organized by category. The category carousel in the template gallery shows all available categories. Custom templates appear in the “My Templates” section.

39.7 Monitoring and Debugging

39.7.1 Run history

The run list sidebar shows all flow runs with: - Status (running, succeeded, failed, paused) - Duration - Start time - Error message (if failed)

39.7.2 Step inspection

Click any run to inspect step inputs, outputs, and errors: - Input tab: shows the input data for each step - Output tab: shows the output data and any error messages - Timeline tab: shows execution timeline for agent steps

39.7.3 Loading run data into tests

You can load run data into the test panel: 1. Open a run from the run list 2. Select the step you want to debug 3. Click “Load into test” to populate the test panel with the run’s step data 4. Modify the input and re-test the step