feat: workflow template (#28553)

* wip: confirm before existing and disable/enable save button condition

* fix: get correct workflow detail

* wip: add back workflow summary

* wip: add back json editor

* wip: step property badge

* wip: redesign card flow

* wip: redesign card flow

* redesign workflow summary

* wworkflow summary styling

* wip

* drag and drop

* list redesign

* refactor

* refactor

* remove deadcode

* refactor

* insert steps

* push down when dropped

* feat: workflow template

* simplify

* move template to manifest

* feat: hash manifest file

* fix: template column

* fix: migration

* fix: workflow lookup

* chore: clean up

---------

Co-authored-by: Jason Rasmussen <jason@rasm.me>

server/src/controllers/plugin.controller.ts

@@ -6,6 +6,7 @@ import {
   PluginMethodSearchDto,
   PluginResponseDto,
   PluginSearchDto,
+  PluginTemplateResponseDto,
 } from 'src/dtos/plugin.dto';
 import { Permission } from 'src/enum';
 import { Authenticated } from 'src/middleware/auth.guard';
@@ -39,6 +40,17 @@ export class PluginController {
     return this.service.searchMethods(dto);
   }
 
+  @Get('templates')
+  @Authenticated({ permission: Permission.PluginRead })
+  @Endpoint({
+    summary: 'Retrieve workflow templates',
+    description: 'Retrieve workflow templates provided by installed plugins',
+    history: HistoryBuilder.v3(),
+  })
+  searchPluginTemplates(): Promise<PluginTemplateResponseDto[]> {
+    return this.service.searchTemplates();
+  }
+
   @Get(':id')
   @Authenticated({ permission: Permission.PluginRead })
   @Endpoint({

server/src/dtos/plugin-manifest.dto.ts

@@ -1,6 +1,6 @@
 import { createZodDto } from 'nestjs-zod';
 import { JsonSchemaSchema } from 'src/dtos/json-schema.dto';
-import { WorkflowTypeSchema } from 'src/enum';
+import { WorkflowTriggerSchema, WorkflowTypeSchema } from 'src/enum';
 import z from 'zod';
 
 const pluginNameRegex = /^[a-z0-9-]+[a-z0-9]$/;
@@ -23,6 +23,24 @@ const PluginManifestMethodSchema = z
   })
   .meta({ id: 'PluginManifestMethodDto' });
 
+const PluginManifestTemplateStepSchema = z
+  .object({
+    method: z.string().min(1).describe('Step plugin method (pluginName#methodName)'),
+    config: z.record(z.string(), z.unknown()).nullable().optional().describe('Step configuration'),
+    enabled: z.boolean().optional().describe('Whether the step is enabled'),
+  })
+  .meta({ id: 'PluginManifestTemplateStepDto' });
+
+const PluginManifestTemplateSchema = z
+  .object({
+    name: z.string().min(1).describe('Template name (must be unique within the manifest)'),
+    title: z.string().min(1).describe('Template title'),
+    description: z.string().min(1).describe('Template description'),
+    trigger: WorkflowTriggerSchema.describe('Workflow trigger'),
+    steps: z.array(PluginManifestTemplateStepSchema).describe('Workflow steps'),
+  })
+  .meta({ id: 'PluginManifestTemplateDto' });
+
 const PluginManifestSchema = z
   .object({
     name: z
@@ -39,6 +57,14 @@ const PluginManifestSchema = z
     wasmPath: z.string().min(1).describe('WASM file path'),
     author: z.string().min(1).describe('Plugin author'),
     methods: z.array(PluginManifestMethodSchema).optional().default([]).describe('Plugin methods'),
+    templates: z
+      .array(PluginManifestTemplateSchema)
+      .optional()
+      .default([])
+      .refine((templates) => new Set(templates.map((t) => t.name)).size === templates.length, {
+        error: 'Template names must be unique within the manifest',
+      })
+      .describe('Workflow templates'),
   })
   .meta({ id: 'PluginManifestDto' });
 

server/src/dtos/plugin.dto.ts

@@ -1,7 +1,7 @@
 import { createZodDto } from 'nestjs-zod';
 import { JsonSchemaDto } from 'src/dtos/json-schema.dto';
-import { WorkflowTriggerSchema, WorkflowType, WorkflowTypeSchema } from 'src/enum';
-import { asMethodString } from 'src/utils/workflow';
+import { WorkflowTrigger, WorkflowTriggerSchema, WorkflowType, WorkflowTypeSchema } from 'src/enum';
+import { asPluginKey } from 'src/utils/workflow';
 import z from 'zod';
 
 const PluginSearchSchema = z
@@ -43,6 +43,24 @@ const PluginResponseSchema = z
   })
   .meta({ id: 'PluginResponseDto' });
 
+const PluginTemplateStepResponseSchema = z
+  .object({
+    method: z.string().describe('Step plugin method'),
+    config: z.record(z.string(), z.unknown()).nullable().describe('Step configuration'),
+    enabled: z.boolean().optional().describe('Whether the step is enabled'),
+  })
+  .meta({ id: 'PluginTemplateStepResponseDto' });
+
+const PluginTemplateResponseSchema = z
+  .object({
+    key: z.string().describe('Template key (unique across all templates)'),
+    title: z.string().describe('Template title'),
+    description: z.string().describe('Template description'),
+    trigger: WorkflowTriggerSchema.describe('Workflow trigger'),
+    steps: z.array(PluginTemplateStepResponseSchema).describe('Workflow steps'),
+  })
+  .meta({ id: 'PluginTemplateResponseDto' });
+
 const PluginMethodSearchSchema = z
   .object({
     id: z.uuidv4().optional().describe('Plugin method ID'),
@@ -61,6 +79,33 @@ export class PluginSearchDto extends createZodDto(PluginSearchSchema) {}
 export class PluginResponseDto extends createZodDto(PluginResponseSchema) {}
 export class PluginMethodSearchDto extends createZodDto(PluginMethodSearchSchema) {}
 export class PluginMethodResponseDto extends createZodDto(PluginMethodResponseSchema) {}
+export class PluginTemplateResponseDto extends createZodDto(PluginTemplateResponseSchema) {}
+
+export type PluginTemplate = {
+  name: string;
+  title: string;
+  description: string;
+  trigger: WorkflowTrigger;
+  steps: Array<{
+    method: string;
+    config?: Record<string, unknown> | null;
+    enabled?: boolean;
+  }>;
+};
+
+export const mapTemplate = (plugin: { name: string }, template: PluginTemplate): PluginTemplateResponseDto => {
+  return {
+    key: asPluginKey({ pluginName: plugin.name, name: template.name }),
+    title: template.title,
+    description: template.description,
+    trigger: template.trigger,
+    steps: template.steps.map((step) => ({
+      method: step.method,
+      config: step.config ?? null,
+      enabled: step.enabled,
+    })),
+  };
+};
 
 type Plugin = {
   id: string;
@@ -101,7 +146,7 @@ export function mapPlugin(plugin: Plugin): PluginResponseDto {
 
 export const mapMethod = (method: PluginMethod): PluginMethodResponseDto => {
   return {
-    key: asMethodString({ pluginName: method.pluginName, methodName: method.name }),
+    key: asPluginKey({ pluginName: method.pluginName, name: method.name }),
     name: method.name,
     title: method.title,
     hostFunctions: method.hostFunctions,

server/src/queries/plugin.repository.sql

@@ -35,6 +35,7 @@ select
   "plugin"."version",
   "plugin"."createdAt",
   "plugin"."updatedAt",
+  "plugin"."templates",
   (
     select
       coalesce(json_agg(agg), '[]')
@@ -60,6 +61,42 @@ from
 order by
   "plugin"."name"
 
+-- PluginRepository.getByHash
+select
+  "plugin"."id",
+  "plugin"."name",
+  "plugin"."title",
+  "plugin"."description",
+  "plugin"."author",
+  "plugin"."version",
+  "plugin"."createdAt",
+  "plugin"."updatedAt",
+  "plugin"."templates",
+  (
+    select
+      coalesce(json_agg(agg), '[]')
+    from
+      (
+        select
+          "plugin_method"."name",
+          "plugin_method"."title",
+          "plugin_method"."description",
+          "plugin_method"."types",
+          "plugin_method"."schema",
+          "plugin_method"."hostFunctions",
+          "plugin_method"."uiHints",
+          "plugin"."name" as "pluginName"
+        from
+          "plugin_method"
+        where
+          "plugin_method"."pluginId" = "plugin"."id"
+      ) as agg
+  ) as "methods"
+from
+  "plugin"
+where
+  "plugin"."sha256hash" = $1
+
 -- PluginRepository.getByName
 select
   "plugin"."id",
@@ -70,6 +107,7 @@ select
   "plugin"."version",
   "plugin"."createdAt",
   "plugin"."updatedAt",
+  "plugin"."templates",
   (
     select
       coalesce(json_agg(agg), '[]')
@@ -105,6 +143,7 @@ select
   "plugin"."version",
   "plugin"."createdAt",
   "plugin"."updatedAt",
+  "plugin"."templates",
   (
     select
       coalesce(json_agg(agg), '[]')

server/src/repositories/database.repository.ts

@@ -274,6 +274,7 @@ export class DatabaseRepository {
       columns: { ignoreExtra: true },
       functions: { ignoreExtra: false },
       parameters: { ignoreExtra: true },
+      extensions: { ignoreExtra: true },
     });
 
     return drift;

server/src/repositories/plugin.repository.ts

@@ -81,6 +81,7 @@ export class PluginRepository {
       'plugin.version',
       'plugin.createdAt',
       'plugin.updatedAt',
+      'plugin.templates',
       jsonArrayFrom(
         eb
           .selectFrom('plugin_method')
@@ -102,6 +103,11 @@ export class PluginRepository {
       .execute();
   }
 
+  @GenerateSql({ params: [DummyValue.STRING] })
+  getByHash(hash: Buffer) {
+    return this.queryBuilder().where('plugin.sha256hash', '=', hash).executeTakeFirst();
+  }
+
   @GenerateSql({ params: [DummyValue.STRING] })
   getByName(name: string) {
     return this.queryBuilder().where('plugin.name', '=', name).executeTakeFirst();
@@ -151,6 +157,8 @@ export class PluginRepository {
             author: eb.ref('excluded.author'),
             version: eb.ref('excluded.version'),
             wasmBytes: eb.ref('excluded.wasmBytes'),
+            templates: eb.ref('excluded.templates'),
+            sha256hash: eb.ref('excluded.sha256hash'),
           })),
         )
         .returning(['id', 'name'])

server/src/schema/migrations/1779806699547-AddPluginTemplates.ts

@@ -0,0 +1,13 @@
+import { Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await sql`ALTER TABLE "plugin" ADD "templates" jsonb NOT NULL DEFAULT '[]';`.execute(db);
+  await sql`ALTER TABLE "plugin" ADD "sha256hash" bytea NOT NULL DEFAULT decode('20464b37ad726d03d878d38d873c40a52d1fdfb754feda956ebb464afd689e2f', 'hex');`.execute(db);
+  await sql`ALTER TABLE "plugin" ALTER COLUMN "sha256hash" DROP DEFAULT;`.execute(db);
+  await sql`ALTER TABLE "plugin" ALTER COLUMN "templates" DROP DEFAULT;`.execute(db);
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await sql`ALTER TABLE "plugin" DROP COLUMN "templates";`.execute(db);
+  await sql`ALTER TABLE "plugin" DROP COLUMN "sha256hash";`.execute(db);
+}

server/src/schema/tables/plugin.table.ts

@@ -8,6 +8,7 @@ import {
   Unique,
   UpdateDateColumn,
 } from '@immich/sql-tools';
+import { PluginTemplate } from 'src/dtos/plugin.dto';
 
 @Unique({ columns: ['name', 'version'] })
 @Table('plugin')
@@ -36,6 +37,12 @@ export class PluginTable {
   @Column({ type: 'bytea' })
   wasmBytes!: Buffer;
 
+  @Column({ type: 'jsonb' })
+  templates!: PluginTemplate[];
+
+  @Column({ type: 'bytea' })
+  sha256hash!: Buffer;
+
   @CreateDateColumn()
   createdAt!: Generated<Timestamp>;
 

server/src/services/plugin.service.ts

@@ -2,10 +2,12 @@ import { BadRequestException, Injectable } from '@nestjs/common';
 import {
   mapMethod,
   mapPlugin,
+  mapTemplate,
   PluginMethodResponseDto,
   PluginMethodSearchDto,
   PluginResponseDto,
   PluginSearchDto,
+  PluginTemplateResponseDto,
 } from 'src/dtos/plugin.dto';
 import { BaseService } from 'src/services/base.service';
 import { isMethodCompatible } from 'src/utils/workflow';
@@ -31,4 +33,9 @@ export class PluginService extends BaseService {
       .filter((method) => !dto.trigger || isMethodCompatible(method, dto.trigger))
       .map((method) => mapMethod(method));
   }
+
+  async searchTemplates(): Promise<PluginTemplateResponseDto[]> {
+    const plugins = await this.pluginRepository.search();
+    return plugins.flatMap((plugin) => plugin.templates.map((template) => mapTemplate(plugin, template)));
+  }
 }

server/src/services/workflow-execution.service.ts

@@ -11,6 +11,7 @@ import { PluginManifestDto } from 'src/dtos/plugin-manifest.dto';
 import {
   BootstrapEventPriority,
   DatabaseLock,
+  ImmichEnvironment,
   ImmichWorker,
   JobName,
   JobStatus,
@@ -43,8 +44,8 @@ export class WorkflowExecutionService extends BaseService {
       // TODO avoid importing plugins in each worker
       // Can this use system metadata similar to geocoding?
 
-      const { resourcePaths, plugins } = this.configRepository.getEnv();
-      await this.importFolder(resourcePaths.corePlugin, { force: true });
+      const { environment, resourcePaths, plugins } = this.configRepository.getEnv();
+      await this.importFolder(resourcePaths.corePlugin, { force: environment === ImmichEnvironment.Development });
 
       if (plugins.external.allow && plugins.external.installFolder) {
         await this.importFolders(plugins.external.installFolder);
@@ -166,7 +167,19 @@ export class WorkflowExecutionService extends BaseService {
   private async importFolder(folder: string, options?: { force?: boolean }) {
     try {
       const manifestPath = join(folder, 'manifest.json');
-      const dto = await this.storageRepository.readJsonFile(manifestPath);
+      const bytes = await this.storageRepository.readFile(manifestPath);
+      const contents = bytes.toString('utf8');
+      const sha256hash = this.cryptoRepository.hashSha256(contents) as Buffer;
+
+      if (!options?.force) {
+        const match = await this.pluginRepository.getByHash(sha256hash);
+        if (match) {
+          this.logger.log(`Plugin up to date (name=${match.name}@${match.version}, hash=${sha256hash.toString('hex')}`);
+          return;
+        }
+      }
+
+      const dto = JSON.parse(contents);
       const result = PluginManifestDto.schema.safeParse(dto);
       if (!result.success) {
         const issues = result.error.issues.map((issue) => `  - [${issue.path.join('.')}] ${issue.message}`).join('\n');
@@ -176,22 +189,21 @@ export class WorkflowExecutionService extends BaseService {
       const manifest = result.data;
 
       const existing = await this.pluginRepository.getByName(manifest.name);
-      if (existing && existing.version === manifest.version && options?.force !== true) {
-        return;
-      }
-
       const wasmPath = `${folder}/${manifest.wasmPath}`;
       const wasmBytes = await this.storageRepository.readFile(wasmPath);
 
       const plugin = await this.pluginRepository.upsert(
         {
+          // NOTE: new properties here need to be added to the on conflict clause in the repository
           enabled: true,
           name: manifest.name,
           title: manifest.title,
           description: manifest.description,
           author: manifest.author,
           version: manifest.version,
+          templates: manifest.templates,
           wasmBytes,
+          sha256hash,
         },
         manifest.methods,
       );

server/src/utils/workflow.ts

@@ -50,8 +50,8 @@ export const resolveMethod = (methods: PluginMethodSearchResponse[], method: str
   return methods.find((method) => method.pluginName === pluginName && method.name === methodName);
 };
 
-export const asMethodString = (method: { pluginName: string; methodName: string }) => {
-  return `${method.pluginName}#${method.methodName}`;
+export const asPluginKey = (method: { pluginName: string; name: string }) => {
+  return `${method.pluginName}#${method.name}`;
 };
 
 const METHOD_REGEX = /^(?<name>[^@#\s]+)(?:@(?<version>[^#\s]*))?#(?<method>[^@#\s]+)$/;

server/test/medium/specs/services/plugin.service.spec.ts

@@ -11,6 +11,7 @@ import { getKyselyDB } from 'test/utils';
 let defaultDatabase: Kysely<DB>;
 
 const wasmBytes = Buffer.from('some-wasm-binary-data');
+const sha256hash = Buffer.from('some-manifest-hash');
 
 const setup = (db?: Kysely<DB>) => {
   return newMediumService(PluginService, {
@@ -46,7 +47,9 @@ describe(PluginService.name, () => {
           description: 'A test plugin',
           author: 'Test Author',
           version: '1.0.0',
+          templates: [],
           wasmBytes,
+          sha256hash,
         },
         [],
       );
@@ -75,7 +78,9 @@ describe(PluginService.name, () => {
           description: 'A plugin with multiple methods',
           author: 'Test Author',
           version: '1.0.0',
+          templates: [],
           wasmBytes,
+          sha256hash,
         },
         [
           {
@@ -130,7 +135,9 @@ describe(PluginService.name, () => {
           description: 'First plugin',
           author: 'Author 1',
           version: '1.0.0',
+          templates: [],
           wasmBytes,
+          sha256hash,
         },
         [
           {
@@ -150,7 +157,9 @@ describe(PluginService.name, () => {
           description: 'Second plugin',
           author: 'Author 2',
           version: '2.0.0',
+          templates: [],
           wasmBytes,
+          sha256hash,
         },
         [
           {
@@ -183,7 +192,9 @@ describe(PluginService.name, () => {
           description: 'Plugin with multiple methods',
           author: 'Test Author',
           version: '1.0.0',
+          templates: [],
           wasmBytes,
+          sha256hash,
         },
         [
           {
@@ -242,6 +253,8 @@ describe(PluginService.name, () => {
           description: 'A single plugin',
           author: 'Test Author',
           version: '1.0.0',
+          templates: [],
+          sha256hash,
           wasmBytes,
         },
         [

server/test/medium/specs/services/workflow.service.spec.ts

@@ -21,6 +21,7 @@ const setup = (db?: Kysely<DB>) => {
 };
 
 const wasmBytes = Buffer.from('random-wasm-bytes');
+const sha256hash = Buffer.from('some-manifest-hash');
 
 beforeAll(async () => {
   defaultDatabase = await getKyselyDB();
@@ -41,7 +42,9 @@ describe(WorkflowService.name, () => {
         description: 'A test core plugin for workflow tests',
         author: 'Test Author',
         version: '1.0.0',
+        templates: [],
         wasmBytes,
+        sha256hash,
       },
       [
         {