ConvergeERP.Shared.Workflow.Core 0.0.3-preview

ConvergeERP.Shared.Workflow.Core

Core contracts, DTOs, and interfaces for the ConvergeERP Workflow Runtime SDK. This package provides lightweight, dependency-minimal types for integrating domain services with the centralized workflow system.

Purpose

This package is designed to be referenced by:

• Domain Services (Finance, Procurement, HR) that need to integrate with workflow
• Consumer services that handle workflow events
• API projects that need workflow DTOs
• Test projects that need workflow contracts for mocking

For full SDK functionality (HTTP clients, resilience, caching), reference ConvergeERP.Shared.Workflow instead.

Package Structure

ConvergeERP.Shared.Workflow.Core
├── Abstractions/
│   ├── IWorkflowRuntimeClient.cs   # HTTP client for runtime operations
│   ├── IWorkflowDefinitionClient.cs # HTTP client for definition queries
│   ├── IPostingGateway.cs          # IsPostingAllowed helper
│   ├── IWorkflowEventPublisher.cs  # Event publishing interface
│   └── IWorkflowSubscriber.cs      # Event subscription helper
├── DTOs/
│   ├── WorkflowDefinitionDto.cs    # Definition summary
│   ├── WorkflowInstanceDto.cs      # Instance state
│   ├── InboxItemDto.cs             # My Approvals item
│   └── PostingCheckResult.cs       # Posting check result
├── Requests/
│   ├── CreateInstanceRequest.cs
│   ├── WorkflowActionRequest.cs
│   └── InboxQuery.cs
├── Responses/
│   ├── CreateInstanceResponse.cs
│   ├── WorkflowActionResponse.cs
│   └── InboxResponse.cs
├── Events/
│   ├── WorkflowInstanceCreatedEvent.cs
│   ├── WorkflowStepCompletedEvent.cs
│   └── WorkflowCompletedEvent.cs
├── Domain/
│   ├── Workflow.cs
│   └── WorkflowInstance.cs
└── Enums.cs

Key Interfaces

IWorkflowRuntimeClient

Primary interface for domain services to interact with the workflow runtime:

public interface IWorkflowRuntimeClient
{
    // Instance Management
    Task<CreateInstanceResponse> CreateInstanceAsync(CreateInstanceRequest request, CancellationToken ct = default);
    Task<WorkflowInstanceDto?> GetInstanceAsync(Guid instanceId, CancellationToken ct = default);
    Task<WorkflowInstanceDto?> GetInstanceByDocumentAsync(string documentType, Guid documentId, CancellationToken ct = default);

    // Actions
    Task<WorkflowActionResponse> ApproveAsync(Guid instanceId, WorkflowActionRequest request, CancellationToken ct = default);
    Task<WorkflowActionResponse> RejectAsync(Guid instanceId, WorkflowActionRequest request, CancellationToken ct = default);
    Task<WorkflowActionResponse> CancelAsync(Guid instanceId, WorkflowActionRequest request, CancellationToken ct = default);

    // Inbox
    Task<InboxResponse> GetMyApprovalsAsync(InboxQuery? query = null, CancellationToken ct = default);
}

IPostingGateway

Critical helper for domain services to check if posting is allowed:

public interface IPostingGateway
{
    Task<PostingCheckResult> IsPostingAllowedAsync(
        string documentType,
        Guid documentId,
        Guid? workflowInstanceId = null,
        CancellationToken ct = default);
}

Usage Examples

Submit Document for Approval

using ConvergeERP.Shared.Workflow.Core.Abstractions;
using ConvergeERP.Shared.Workflow.Core.Requests;

public class InvoiceService
{
    private readonly IWorkflowRuntimeClient _workflowClient;

    public async Task SubmitForApprovalAsync(Invoice invoice)
    {
        var response = await _workflowClient.CreateInstanceAsync(new CreateInstanceRequest
        {
            DocumentType = "Invoice",
            DocumentId = invoice.Id,
            DocumentRef = invoice.InvoiceNumber,
            Metadata = new Dictionary<string, string>
            {
                ["Amount"] = invoice.TotalAmount.ToString("C"),
                ["Vendor"] = invoice.VendorName
            }
        });

        if (response.Success)
        {
            invoice.WorkflowInstanceId = response.InstanceId;
            await SaveAsync(invoice);
        }
    }
}

Check Posting Allowed

public async Task<bool> CanPostInvoiceAsync(Invoice invoice)
{
    var result = await _postingGateway.IsPostingAllowedAsync(
        "Invoice",
        invoice.Id,
        invoice.WorkflowInstanceId);

    return result.IsAllowed;
}

Consume Workflow Events

using ConvergeERP.Shared.Workflow.Core.Events;
using MassTransit;

public class WorkflowCompletedConsumer : IConsumer<WorkflowCompletedEvent>
{
    public async Task Consume(ConsumeContext<WorkflowCompletedEvent> context)
    {
        var evt = context.Message;

        if (evt.IsPostingAllowed && evt.DocumentType == "Invoice")
        {
            // Auto-post or notify user
            await NotifyUserAsync(evt.DocumentId, "Invoice approved - ready to post");
        }
    }
}

Dependencies

• ConvergeERP.Shared.Domain - Base entity types with multi-tenant support

Related Packages

• ConvergeERP.Shared.Workflow - Full SDK implementation with HTTP clients and resilience