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
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, needsmanageTemplatesEnabled),SHARED(ad-hoc share URL, not listable). - TemplateStatus:
PUBLISHED(visible) orARCHIVED(hidden). - Services:
template.service.ts(CRUD + list),template-validator.ts,community-templates.service.ts, EEplatform-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/templatesviacommunityTemplates. - List filtering: ArrayOverlap for
pieces, ArrayContains forcategories, ILIKE forsearch. Only PUBLISHED templates returned. FlowVersionTemplateis a flow version stripped of runtime-only fields (id, flowId, state) for embedding.
Gotchas
Custom templates require the
manageTemplatesEnabledplan 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 apreValidationhook 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 updatepreValidationturns an absentflowsinto[], sotemplateService.updatetreats 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 preparedflowsandpiecestoplatformTemplateService.updatefor CUSTOM. Before GIT-1834 the CUSTOM branch got the raw request instead, so a details-only edit wroteflows: []over the export, skipped validation, and tookpiecesfrom the first flow only.piecesandcategoriesare denormalized + indexed for fast filtering.On CE/EE the official templates are optional data fetched live from
cloud.activepieces.comon every request. Air-gapped and egress-restricted installs are supported, so everycommunityTemplatescall goes throughfetchFromCloud(safeHttp.axios, 10 s timeout) and degrades to "none" on any failure: categoriesnull, 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 toAP_SSRF_ALLOW_LIST.A flow export (
GET /v1/flows/:id/template) keeps its connection refs.removeConnectionsFromInputinflow-version.service.tsstrips 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/eventserves two callers, and only one of them is the relay — do not gate it on edition or skip the gate. It issecurityAccess.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 viasendToCloud. 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 resolvesplatformUtils.getPlatformIdForRequestand 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, whoseprojectId/templateIdbelong to the sending deployment's database) and is forwarded. ACTIVATE/DEACTIVATE come fromtrigger-source-servicewith a realprojectIdand are gated through the project. Also notesendToCloud/sendToInternaluse rawfetch, notsafeHttp/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 proxypackages/server/api/src/app/ee/template/platform-template.service.ts— EE only, creates and updates CUSTOM templates for a platformpackages/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 clientpackages/web/src/features/templates/components/— browse dialog, use-template import dialog, share dialog, explore cardpackages/web/src/features/templates/hooks/— templates data hookspackages/web/src/app/routes/templates/— public-facing template gallery page
Paths verified 2026-07-17.