shesha-workflow

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
13	Dashboard / Admin Queries	Application	querying-and-dashboards.md §5–§6
14	View Entities (pre-built)	Domain (read-only)	querying-and-dashboards.md §2

When generating multiple artifacts, always create the Instance + Definition pair first, then add Service Tasks per workflow step. When building dashboard or admin views, consult the querying-and-dashboards.md reference for pre-built view entities, query patterns, and application service examples. When debugging a running workflow instance, use the /analyze-workflow-state skill instead — it parses ProcessState XML, fetches live data from the backend API, and diagnoses execution issues.

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
WorkflowInstanceDashboardItem	Shesha.Workflow.Domain.ViewEntities	Dashboard listing view entity
WorkflowStatisticsItem	Shesha.Workflow.Domain.ViewEntities	Step-level statistics with timing and decisions
WorkflowInboxItem	Shesha.Workflow.Domain.ViewEntities	User inbox (pending tasks)
WorkflowSentItem	Shesha.Workflow.Domain.ViewEntities	Completed tasks sent by user
ProcessProgressItem	Shesha.Workflow.Domain.ViewEntities	Step progress indicator for a workflow
WorkflowTimelineItem	Shesha.Workflow.Domain.ViewEntities	Timeline/audit trail view

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