---

name: shesha-workflow description: Generates Shesha workflow artifacts for .NET applications using ABP framework with NHibernate. Creates workflow instances, definitions, managers, service tasks, extension methods, and FluentMigrator database migrations. Use when the user asks to create, scaffold, or update workflow-related classes, workflow steps, workflow conditions, or workflow database tables in a Shesha project.

Shesha Workflow Code Generation

Generate workflow artifacts for a Shesha/.NET/ABP/NHibernate application based on $ARGUMENTS.

Instructions

• Inspect nearby files to determine the correct namespace root.
• Use Guid as entity ID type. All domain properties must be virtual.
• Every workflow requires at minimum: Workflow Instance + Workflow Definition (domain layer).
• Generate a new GUID for [DiscriminatorValue] attributes.
• Place files according to the folder structure below.

Artifact catalog

| # | Artifact | Layer | Template | |---|----------|-------|----------| | 1 | Workflow Instance | Domain | domain-artifacts.md §1 | | 2 | Workflow Definition | Domain | domain-artifacts.md §2 | | 3 | Workflow Manager | Domain | domain-artifacts.md §3 | | 4 | Lifecycle Operations (Suspend/Resume/Cancel/Start) | Domain | domain-artifacts.md §4 | | 5 | Batch Workflow Manager (cycle-based bulk initiation) | Domain | domain-artifacts.md §5 | | 6 | Service Task | Application | service-tasks.md §1 | | 7 | Service Task with Typed Arguments | Application | service-tasks.md §2 | | 8 | Generic Base Service Task | Application | service-tasks.md §3 | | 9 | External-System Await / Auto-Completion Helper | Application | service-tasks.md §4 | | 10 | Workflow Extensions | Application | service-tasks.md §5 | | 11 | Hangfire Background Job for Batch Initiation | Application | service-tasks.md §6 | | 12 | Database Migration | Domain | migrations.md |

When generating multiple artifacts, always create the Instance + Definition pair first, then add Service Tasks per workflow step.

Folder structure

{Module}.Domain/
  Domain/{WorkflowName}Workflows/
    {WorkflowName}Workflow.cs                   ← Instance (§1)
    {WorkflowName}WorkflowDefinition.cs         ← Definition (§2)
    {WorkflowName}WorkflowManager.cs            ← Manager + lifecycle ops (§3, §4)
    {WorkflowName}BatchWorkflowManager.cs       ← Batch manager when needed (§5)
  Migrations/
    M{YYYYMMDDHHmmss}.cs

{Module}.Application/
  Jobs/
    Initiate{WorkflowName}WorkflowsJob.cs       ← Hangfire background job (§6)
  Services/
    {ExternalSystem}/
      {ExternalSystem}WorkflowHelper.cs         ← External-trigger helper (§4)
  Workflows/
    Common/
      {TaskName}ServiceTaskBase.cs              ← Generic base task (§3)
    {WorkflowNamePlural}/
      {TaskName}ServiceTask.cs                  ← Service task (§1 or §2)
      {WorkflowName}WorkflowExtensions.cs       ← Extension methods (§5)

Quick reference

Base classes

| Artifact | Base Class | |----------|-----------| | Workflow Instance | WorkflowInstanceWithTypedDefinition<TDefinition> (Shesha.Workflow.Domain) | | Workflow Definition | WorkflowDefinition | | Workflow Manager | DomainService | | Batch Workflow Manager | DomainService with generic params <TDef, TInstance, TModel> | | Service Task | AsyncServiceTask<TWorkflow> + ITransientDependency | | Service Task with Args | AsyncServiceTask<TWorkflow, TArgs> + ITransientDependency | | Generic Base Task | AsyncServiceTask<TWorkflow> where TWorkflow : WorkflowInstance | | Gateway condition ext. | static class on WorkflowInstance → returns bool | | Action ext. methods | static class on typed {WorkflowName}Workflow → returns Task | | Background Job | ITransientDependency (NOT ScheduledJobBase) | | DB Migration | Migration or OneWayMigration |

Key dependencies

| Interface / Class | Namespace | Use | |-------------------|-----------|-----| | ServiceTaskExecutionContext<T> | Shesha.Workflow.Tasks | Service task RunAsync parameter | | ServiceTaskExecutionContext<T, TArgs> | Shesha.Workflow.Tasks | Typed-args task RunAsync parameter | | IProcessDomainService | Shesha.Workflow.DomainServices | Start by name, complete user tasks | | ProcessAppService | Shesha.Workflow.AppServices.Processes | Suspend / Resume / Cancel | | IWorkflowHelper | Shesha.Workflow | Resume user task, emit message, get variables | | WorkflowExecutionLogItem | Shesha.Workflow.Domain | External-trigger auto-completion | | IRepository<WorkflowInstance, Guid> | Abp.Domain.Repositories | Manager manual instance creation | | ILogger<T> | Microsoft.Extensions.Logging | Structured logging in service tasks |

Key attributes

| Attribute | Used On | |-----------|---------| | [JoinedProperty("TableName")] | Instance, Definition | | [Prefix(UsePrefixes = false)] | Instance | | [Entity(TypeShortAlias = "...")] | Instance | | [DiscriminatorValue("slug")] | Definition | | [ServiceTaskArguments("slug")] | Typed-args service task class | | [Display(Name, Description)] | Definition, Service Task | | [Migration(YYYYMMDDHHmmss)] | Migration class |

Service task method signature

// CORRECT — override RunAsync, return Task (void), access workflow via context
public override async Task RunAsync(ServiceTaskExecutionContext<{WorkflowName}Workflow> context)
{
    var workflow = context.WorkflowInstance;  // typed workflow instance
    // context.Pvc  →  IReadWriteVariables (process variable container)
    await _workflowRepository.UpdateAsync(workflow);
}

// With typed arguments:
public override async Task RunAsync(
    ServiceTaskExecutionContext<{WorkflowName}Workflow, {TaskName}Args> context)
{
    var workflow = context.WorkflowInstance;
    var args = context.Arguments;  // populated by the BPMN designer
}

Common patterns

Refresh workflow (NHibernate stale state fix):

var sessionProvider = StaticContext.IocManager.Resolve<ISessionProvider>();
sessionProvider.Session.Refresh(workflow);

Sync SubStatus to Model Status:

workflow.Model.Status = ({RefListStatusEnum}?)workflow.SubStatus;

Resolve dependency in extension methods:

var repo = IocManager.Instance.Resolve<IRepository<{Entity}, Guid>>();

Check definition config in a service task:

if (workflow.Definition?.{ConfigFlag} != true)
    return; // feature disabled — skip silently

Suspend a workflow:

await _processAppService.SuspendAsync(new SuspendProcessInput
{
    WorkflowInstanceId = workflowInstance.Id,
    Comments = "Paused pending external action"
});

Resume a workflow:

await _processAppService.ResumeAsync(new ResumeProcessInput
{
    WorkflowInstanceId = workflowInstance.Id,
    Comments = "Resumed after external action completed"
});

Cancel a workflow:

await _processAppService.CancelAsync(new CancelProcessInput
{
    WorkflowInstanceId = workflowInstance.Id,
    Comments = "Cancelled — reason here"
});

Start a workflow by name (programmatic):

await _processDomainService.StartByNameAsync<{WorkflowDefinition}, {WorkflowInstance}>(
    new WorkflowDefinitionIdentifier({ModuleName}.Name, "{discriminator-slug}"),
    async (instance) =>
    {
        instance.Model = myEntity;
        instance.Subject = "Workflow subject text";
    });

Auto-complete a workflow step from an external trigger:

// Find the active log item by step name, then complete it:
var logItem = _logItemRepo.GetAll()
    .FirstOrDefault(i => i.WorkflowTask.ActionText == stepName
                      && i.CompletedOn == null
                      && i.IsLast == true
                      && i.Status == RefListWorkflowLogItemStatus.Active);
if (logItem != null)
    await _workflowHelper.ResumeUserTaskAsync(logItem.WorkflowTask,
        new UserTaskResponse { Decision = "{decision-uid}", Comment = "Auto-completed" });

Check active workflow guard:

var hasActive = await _workflowRepo.CountAsync(w =>
    w.Model.Id == modelId &&
    w.Status == RefListWorkflowStatus.InProgress) > 0;
if (hasActive)
    throw new UserFriendlyException("An active workflow already exists.");

Enqueue batch initiation to Hangfire:

BackgroundJob.Enqueue<Initiate{WorkflowName}WorkflowsJob>(
    j => j.ExecuteAsync(initiateDto));

Migration table naming

| Artifact | Table Name | FK Target | |----------|-----------|-----------| | Instance | {Prefix}_{WorkflowName}Workflows | workflow.workflow_instances | | Definition | {Prefix}_{WorkflowName}WorkflowDefinitions | workflow.workflow_definitions |

Use the project's established module prefix (e.g. Leave_, Pmds_, Hcm_) — inspect nearby migrations to determine the correct prefix for the target module.

Now generate the requested workflow artifact(s) based on: $ARGUMENTS