Index of every page on this site: llms.txt
All skills
twentyhq avatar

/syncable-entity-runner-and-actions

@13c9027
by Twentytwentyhq/twenty61k stars
10,139
Run it yourself

Contributing to the Twenty codebase itself (twentyhq/twenty server internals), not for building apps on top of Twenty. Implement action handlers for executing workspace migrations in Twenty. Use when creating database operations for syncable entities, implementing universal-to-flat entity transpilation, or handling create/update/delete actions in the runner layer.

Use this Skill: https://skilld.dev/gh/twentyhq/twenty/syncable-entity-runner-and-actions

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈101 tokens for metadata: the name and description. ≈3k when used: this file.

Description uses 5.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈403 characters, or 5.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Syncable Entity: Runner & Actions (Step 4/6)

Purpose: Execute migration actions against the database with proper transpilation from universal to flat entities.

When to use: After completing Steps 1-3 (Types, Cache, Builder). Required before integration.


Quick Start

This step creates:

  1. Create action handler
  2. Update action handler
  3. Delete action handler
  4. Universal-to-flat conversion utilities

Key pattern: Each handler has two phases:

  1. Transpilation: Universal action → Flat action
  2. Execution: Flat action → Database operation

Step 1: Create Action Handler

File: src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/services/create-my-entity-action-handler.service.ts

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';

import { WorkspaceCreateActionHandlerService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/workspace-create-action-handler.service';
import { MyEntityEntity } from 'src/engine/metadata-modules/my-entity/entities/my-entity.entity';
import { fromUniversalFlatMyEntityToFlatMyEntity } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/utils/from-universal-flat-my-entity-to-flat-my-entity.util';
import {
  type UniversalCreateMyEntityAction,
  type FlatCreateMyEntityAction,
} from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/my-entity/types/workspace-migration-my-entity-action.type';

@Injectable()
export class CreateMyEntityActionHandlerService extends WorkspaceCreateActionHandlerService<
  'myEntity',
  UniversalCreateMyEntityAction,
  FlatCreateMyEntityAction
> {
  constructor(
    @InjectRepository(MyEntityEntity, 'metadata')
    private readonly myEntityRepository: Repository<MyEntityEntity>,
  ) {
    super();
  }

  // Phase 1: Transpile universal action to flat action
  protected transpileUniversalActionToFlatAction(
    universalAction: UniversalCreateMyEntityAction,
    flatEntityMaps: AllFlatEntityMapsByMetadataName,
  ): FlatCreateMyEntityAction {
    return {
      type: 'create',
      metadataName: 'myEntity',
      flatEntity: fromUniversalFlatMyEntityToFlatMyEntity(
        universalAction.universalFlatEntity,
        flatEntityMaps,
      ),
    };
  }

  // Phase 2: Execute flat action against database
  protected async executeForMetadata(
    flatActions: FlatCreateMyEntityAction[],
  ): Promise<void> {
    const flatEntities = flatActions.map((action) => action.flatEntity);

    await this.insertFlatEntitiesInRepository({
      repository: this.myEntityRepository,
      flatEntities,
    });
  }

  protected async executeForWorkspaceSchema(): Promise<void> {
    // No workspace schema changes needed for metadata-only entity
    return;
  }
}

Key helper methods:

  • transpileUniversalActionToFlatAction: Converts universal → flat
  • insertFlatEntitiesInRepository: Base class helper for inserts
  • executeForMetadata: Metadata database operations
  • executeForWorkspaceSchema: Workspace schema changes (if needed)

Step 2: Update Action Handler

File: src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/services/update-my-entity-action-handler.service.ts

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';

import { WorkspaceUpdateActionHandlerService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/workspace-update-action-handler.service';
import { MyEntityEntity } from 'src/engine/metadata-modules/my-entity/entities/my-entity.entity';
import { fromUniversalFlatMyEntityToFlatMyEntity } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/utils/from-universal-flat-my-entity-to-flat-my-entity.util';
import { resolveUniversalUpdateRelationIdentifiersToIds } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/utils/resolve-universal-relation-identifiers-to-ids.util';

@Injectable()
export class UpdateMyEntityActionHandlerService extends WorkspaceUpdateActionHandlerService<
  'myEntity',
  UniversalUpdateMyEntityAction,
  FlatUpdateMyEntityAction
> {
  constructor(
    @InjectRepository(MyEntityEntity, 'metadata')
    private readonly myEntityRepository: Repository<MyEntityEntity>,
  ) {
    super();
  }

  protected transpileUniversalActionToFlatAction(
    universalAction: UniversalUpdateMyEntityAction,
    flatEntityMaps: AllFlatEntityMapsByMetadataName,
  ): FlatUpdateMyEntityAction {
    const flatEntity = fromUniversalFlatMyEntityToFlatMyEntity(
      universalAction.universalFlatEntity,
      flatEntityMaps,
    );

    // Resolve universal foreign keys in updates to regular IDs
    const flatUpdates = resolveUniversalUpdateRelationIdentifiersToIds({
      metadataName: 'myEntity',
      universalUpdates: universalAction.universalUpdates,
      flatEntityMaps,
    });

    return {
      type: 'update',
      metadataName: 'myEntity',
      flatEntity,
      updates: flatUpdates,
    };
  }

  protected async executeForMetadata(
    flatActions: FlatUpdateMyEntityAction[],
  ): Promise<void> {
    for (const action of flatActions) {
      await this.myEntityRepository.update(
        { id: action.flatEntity.id },
        action.updates,
      );
    }
  }

  protected async executeForWorkspaceSchema(): Promise<void> {
    return;
  }
}

Update-specific helper:

  • resolveUniversalUpdateRelationIdentifiersToIds: Maps universal identifiers back to regular IDs in the updates object

Step 3: Delete Action Handler

File: src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/services/delete-my-entity-action-handler.service.ts

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';

import { WorkspaceDeleteActionHandlerService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/workspace-delete-action-handler.service';
import { MyEntityEntity } from 'src/engine/metadata-modules/my-entity/entities/my-entity.entity';
import { fromUniversalFlatMyEntityToFlatMyEntity } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/utils/from-universal-flat-my-entity-to-flat-my-entity.util';

@Injectable()
export class DeleteMyEntityActionHandlerService extends WorkspaceDeleteActionHandlerService<
  'myEntity',
  UniversalDeleteMyEntityAction,
  FlatDeleteMyEntityAction
> {
  constructor(
    @InjectRepository(MyEntityEntity, 'metadata')
    private readonly myEntityRepository: Repository<MyEntityEntity>,
  ) {
    super();
  }

  protected transpileUniversalActionToFlatAction(
    universalAction: UniversalDeleteMyEntityAction,
    flatEntityMaps: AllFlatEntityMapsByMetadataName,
  ): FlatDeleteMyEntityAction {
    // Use base class helper for delete transpilation
    return this.transpileUniversalDeleteActionToFlatDeleteAction({
      universalAction,
      flatEntityMaps,
      fromUniversalFlatEntityToFlatEntity: fromUniversalFlatMyEntityToFlatMyEntity,
    });
  }

  protected async executeForMetadata(
    flatActions: FlatDeleteMyEntityAction[],
  ): Promise<void> {
    const ids = flatActions.map((action) => action.flatEntity.id);

    await this.myEntityRepository.delete(ids);
  }

  protected async executeForWorkspaceSchema(): Promise<void> {
    return;
  }
}

Delete-specific helper:

  • transpileUniversalDeleteActionToFlatDeleteAction: Base class helper that handles standard delete transpilation

Step 4: Universal-to-Flat Conversion

File: src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/utils/from-universal-flat-my-entity-to-flat-my-entity.util.ts

import { resolveUniversalRelationIdentifiersToIds } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/utils/resolve-universal-relation-identifiers-to-ids.util';
import { type UniversalFlatMyEntity } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/universal-flat-my-entity.type';
import { type FlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity.type';
import { type AllFlatEntityMapsByMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-maps-by-metadata-name.type';

export const fromUniversalFlatMyEntityToFlatMyEntity = (
  universalFlatMyEntity: UniversalFlatMyEntity,
  flatEntityMaps: AllFlatEntityMapsByMetadataName,
): FlatMyEntity => {
  // Resolve universal foreign keys back to regular IDs
  return resolveUniversalRelationIdentifiersToIds({
    metadataName: 'myEntity',
    universalFlatEntity: universalFlatMyEntity,
    flatEntityMaps,
  }) as FlatMyEntity;
};

Key utility:

  • resolveUniversalRelationIdentifiersToIds: Maps universal identifiers → regular IDs (reverse of resolveEntityRelationUniversalIdentifiers)

Action Handler Patterns

Pattern: Create Handler

// 1. Transpile: Universal → Flat
protected transpileUniversalActionToFlatAction(
  universalAction,
  flatEntityMaps,
) {
  return {
    type: 'create',
    metadataName: 'myEntity',
    flatEntity: fromUniversalFlatMyEntityToFlatMyEntity(
      universalAction.universalFlatEntity,
      flatEntityMaps,
    ),
  };
}

// 2. Execute: Flat → Database
protected async executeForMetadata(flatActions) {
  await this.insertFlatEntitiesInRepository({
    repository: this.myEntityRepository,
    flatEntities: flatActions.map(a => a.flatEntity),
  });
}

Pattern: Update Handler

// Transpile with update-specific resolution
protected transpileUniversalActionToFlatAction(
  universalAction,
  flatEntityMaps,
) {
  const flatEntity = fromUniversalFlatMyEntityToFlatMyEntity(
    universalAction.universalFlatEntity,
    flatEntityMaps,
  );

  const flatUpdates = resolveUniversalUpdateRelationIdentifiersToIds({
    metadataName: 'myEntity',
    universalUpdates: universalAction.universalUpdates,
    flatEntityMaps,
  });

  return { type: 'update', metadataName: 'myEntity', flatEntity, updates: flatUpdates };
}

Pattern: Delete Handler

// Use base class helper
protected transpileUniversalActionToFlatAction(
  universalAction,
  flatEntityMaps,
) {
  return this.transpileUniversalDeleteActionToFlatDeleteAction({
    universalAction,
    flatEntityMaps,
    fromUniversalFlatEntityToFlatEntity: fromUniversalFlatMyEntityToFlatMyEntity,
  });
}

// Delete
protected async executeForMetadata(flatActions) {
  const ids = flatActions.map(a => a.flatEntity.id);
  await this.myEntityRepository.delete(ids);
}

Checklist

Before moving to Step 5:

  • Create action handler implemented
  • Update action handler implemented
  • Delete action handler implemented
  • All handlers extend appropriate base class
  • transpileUniversalActionToFlatAction implemented in all handlers
  • executeForMetadata implemented in all handlers
  • executeForWorkspaceSchema implemented (or returns empty)
  • Universal-to-flat conversion utility created
  • Create handler uses insertFlatEntitiesInRepository
  • Update handler uses resolveUniversalUpdateRelationIdentifiersToIds
  • Delete handler uses transpileUniversalDeleteActionToFlatDeleteAction
  • Delete handler uses hard delete (delete())

Next Step

Once action handlers are complete, proceed to: Syncable Entity: Integration (Step 5/6)

For complete workflow, see @creating-syncable-entity rule.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill provides development templates for implementing database action handlers in the Twenty workspace migration engine. It uses standard NestJS and TypeORM patterns and does not contain any security vulnerabilities or malicious instructions.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer9mo

    1/1 file flagged

Signed by skilld at 13c9027. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 16 minutes ago.

Activeupdated 2 months ago

README badge

README badge for twentyhq/twenty/syncable-entity-runner-and-actions