Skip to content

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

6.0 KB
Raw Blame

icon: 📋

Templates

Templates are a library of reusable flow (and table) blueprints users can browse, import, and build on. Before saving, flows inside a template are validated and their piece names extracted into a searchable pieces array.

Entities & services

  • Template entity: name, summary, description, type, status, platformId (nullable), flows (jsonb FlowVersionTemplate[]), tables, tags, categories (indexed text[]), pieces (indexed text[]).
  • TemplateType: OFFICIAL (AP-curated, platformId=null), CUSTOM (platform-owned, needs manageTemplatesEnabled), SHARED (ad-hoc share URL, not listable).
  • TemplateStatus: PUBLISHED (visible) or ARCHIVED (hidden).
  • Services: template.service.ts (CRUD + list), template-validator.ts, community-templates.service.ts, EE platform-template.service.ts.

How it works

  • Routes under /v1/templates: GET /categories, GET /:id, GET / (public list, official + custom merged), POST /, POST /:id, DELETE /:id (platform-owner only).
  • Official template storage differs by edition: on Cloud they live in the DB with null platformId; on self-hosted (CE/EE) they're proxied at request time from https://cloud.activepieces.com/api/v1/templates via communityTemplates.
  • List filtering: ArrayOverlap for pieces, ArrayContains for categories, ILIKE for search. Only PUBLISHED templates returned.
  • FlowVersionTemplate is a flow version stripped of runtime-only fields (id, flowId, state) for embedding.

Gotchas

  • Custom templates require the manageTemplatesEnabled plan flag (off by default in CE). When disabled, custom listing is skipped silently — returns empty array, no error.

  • OFFICIAL and SHARED templates cannot be updated or deleted via API; ownership is double-checked (template.platformId === principal.platform.id).

  • Flow version migration (migrateFlowVersionTemplateList) runs as a preValidation hook on create/update to handle schema evolution in stored flows.

  • An update only replaces a template's workflow when it carries a non-empty flows. The update preValidation turns an absent flows into [], so templateService.update treats an empty list as "keep what's stored": it validates and prepares flows (against the template's own platform) only when some are sent, then hands those prepared flows and pieces to platformTemplateService.update for CUSTOM. Before GIT-1834 the CUSTOM branch got the raw request instead, so a details-only edit wrote flows: [] over the export, skipped validation, and took pieces from the first flow only.

  • pieces and categories are denormalized + indexed for fast filtering.

  • On CE/EE the official templates are optional data fetched live from cloud.activepieces.com on every request. Air-gapped and egress-restricted installs are supported, so every communityTemplates call goes through fetchFromCloud (safeHttp.axios, 10 s timeout) and degrades to "none" on any failure: categories null, list [], detail 404. A call that throws turns Explore and Automations into a 500 and hides the platform's custom templates too (ENG-829). If DNS sends the host to a private IP (an internal egress proxy), the SSRF filter blocks it until the IP is added to AP_SSRF_ALLOW_LIST.

  • A flow export (GET /v1/flows/:id/template) keeps its connection refs. removeConnectionsFromInput in flow-version.service.ts strips only the old {{connections.x}} dot syntax, and the builder has written {{connections['x']}} since 2023. Import keeps the ref, so a flow re-imported where a connection with that External ID exists just works, and users rely on it. Fixing the regex is a functional breaking change, not a cleanup (GIT-1957).

  • POST /v1/templates-telemetry/event serves two callers, and only one of them is the relay — do not gate it on edition or skip the gate. It is securityAccess.public(), and the local browser posts to it directly for VIEW, INSTALL and EXPLORE_VIEW (packages/web/src/features/templates/api/templates-telemetry-api.ts, four call sites); a self-hosted instance also posts to Cloud's copy of the same route via sendToCloud. Those three event types travel only this path, so treating the route as "the relay hop, already consented upstream" silently un-gates them for every opted-out self-hoster. The controller therefore resolves platformUtils.getPlatformIdForRequest and the service gates on that platform's row when one resolves; a null platform means the genuine relay case (a Cloud request with no principal, whose projectId/templateId belong to the sending deployment's database) and is forwarded. ACTIVATE/DEACTIVATE come from trigger-source-service with a real projectId and are gated through the project. Also note sendToCloud/sendToInternal use raw fetch, not safeHttp/apAxios — pre-existing, and only sound because both URLs are hardcoded.

Editions

CE/EE proxy official templates from cloud; custom needs manageTemplatesEnabled. Cloud stores official in DB directly; custom needs manageTemplatesEnabled.

Key files

Entry point: templateController, registered in template.module.ts under the /v1/templates prefix.

  • packages/server/api/src/app/template/ — controller, module, service, entity, validator, and the community-templates cloud proxy
  • packages/server/api/src/app/ee/template/platform-template.service.ts — EE only, creates and updates CUSTOM templates for a platform
  • packages/core/shared/src/lib/management/template/ — shared types and request schemas (Template, TemplateType, TemplateStatus, FlowVersionTemplate, TableTemplate, TemplateTag, the Create/Update/List request bodies)
  • packages/web/src/features/templates/api/ — frontend API client
  • packages/web/src/features/templates/components/ — browse dialog, use-template import dialog, share dialog, explore card
  • packages/web/src/features/templates/hooks/ — templates data hooks
  • packages/web/src/app/routes/templates/ — public-facing template gallery page

Paths verified 2026-07-17.