@rytass/bpm-core-nestjs-module 0.20.1 → 0.21.1

package/src/lib/workflow-engine/workflow-engine.service.d.ts

@@ -1,4 +1,4 @@
-import { MemberMetadata } from '@rytass/bpm-core-shared';
+import { MemberMetadata, type ApprovalInstanceFieldFilter, type ApprovalInstanceSort } from '@rytass/bpm-core-shared';
 import { WorkflowWebhookDeliveryService } from '../workflow-webhook/workflow-webhook-delivery.service';
 import { Repository } from 'typeorm';
 import { AttachmentService } from '../attachment/attachment.service';
@@ -29,6 +29,7 @@ import { TaskCandidateEntity } from './task-candidate.entity';
 import { TaskEntity } from './task.entity';
 import { ApprovalInstanceListViewEnum, ApprovalInstanceStateEnum, MemberTaskRoleEnum, TaskCandidateStatusEnum, TaskReassignmentErrorCodeEnum, TaskReassignmentOutcomeEnum } from './workflow-engine.enums';
 import { WorkflowDryRunResultObject } from './workflow-dry-run.object';
+import { BPMInitiatorCustomFieldsResolver } from './initiator-custom-fields-resolver.token';
 import { BPMWorkflowServiceTaskDispatcher } from './workflow-service-task-dispatcher.token';
 import { WorkflowTokenEntity } from './workflow-token.entity';
 import { BPMRootRuntimeOptions } from '../bpm/bpm-root-options';
@@ -140,10 +141,14 @@ export interface DecideTaskOptions {
      */
     readonly transferReason?: string;
 }
-interface ListApprovalInstancesOptions {
+export interface ListApprovalInstancesOptions {
+    /** ADR 25 §7: conditions on form fields. Needs `templateId` when not empty. */
+    readonly fieldFilters?: readonly ApprovalInstanceFieldFilter[];
     readonly page?: number;
     readonly pageSize?: number;
     readonly searchText?: string;
+    /** ADR 25 §7.5: sort keys in order; the list always ends with `id`. */
+    readonly sort?: readonly ApprovalInstanceSort[];
     readonly state?: readonly ApprovalInstanceStateEnum[];
     readonly templateId?: string;
     readonly view?: ApprovalInstanceListViewEnum;
@@ -174,8 +179,11 @@ export declare class WorkflowEngineService {
     private readonly formDataSourceValueResolver?;
     private readonly webhookDeliveryService?;
     private readonly logger;
-    constructor(approvalInstanceRepository: Repository<ApprovalInstanceEntity>, workflowTokenRepository: Repository<WorkflowTokenEntity>, taskRepository: Repository<TaskEntity>, taskCandidateRepository: Repository<TaskCandidateEntity>, taskDecisionRepository: Repository<TaskDecisionEntity>, notificationRepository: Repository<NotificationEntity>, activityLogRepository: Repository<ActivityLogEntity>, adhocDirectiveRepository: Repository<AdhocDirectiveEntity>, approvalTemplateRepository: Repository<ApprovalTemplateEntity>, approvalTemplateVersionRepository: Repository<ApprovalTemplateVersionEntity>, formDefinitionVersionRepository: Repository<FormDefinitionVersionEntity>, attachmentService: AttachmentService, conditionService: ConditionService, delegationService: DelegationService, notificationService: NotificationService, signatureService: SignatureService, slaScheduleService: BPMSlaScheduleService, injectedServiceTaskDispatcher?: BPMWorkflowServiceTaskDispatcher, formDataSourceValueResolver?: BPMFormDataSourceValueResolver | undefined, rootOptions?: BPMRootRuntimeOptions, webhookDeliveryService?: WorkflowWebhookDeliveryService | undefined);
+    private readonly approvalInstanceFieldFilterCompiler;
+    private readonly approvalInstanceFilterableFieldPolicy;
+    constructor(approvalInstanceRepository: Repository<ApprovalInstanceEntity>, workflowTokenRepository: Repository<WorkflowTokenEntity>, taskRepository: Repository<TaskEntity>, taskCandidateRepository: Repository<TaskCandidateEntity>, taskDecisionRepository: Repository<TaskDecisionEntity>, notificationRepository: Repository<NotificationEntity>, activityLogRepository: Repository<ActivityLogEntity>, adhocDirectiveRepository: Repository<AdhocDirectiveEntity>, approvalTemplateRepository: Repository<ApprovalTemplateEntity>, approvalTemplateVersionRepository: Repository<ApprovalTemplateVersionEntity>, formDefinitionVersionRepository: Repository<FormDefinitionVersionEntity>, attachmentService: AttachmentService, conditionService: ConditionService, delegationService: DelegationService, notificationService: NotificationService, signatureService: SignatureService, slaScheduleService: BPMSlaScheduleService, injectedServiceTaskDispatcher?: BPMWorkflowServiceTaskDispatcher, formDataSourceValueResolver?: BPMFormDataSourceValueResolver | undefined, rootOptions?: BPMRootRuntimeOptions, webhookDeliveryService?: WorkflowWebhookDeliveryService | undefined, injectedInitiatorCustomFieldsResolver?: BPMInitiatorCustomFieldsResolver);
     private readonly serviceTaskDispatcher;
+    private readonly initiatorCustomFieldsResolver;
     /** Webhooks each open engine transaction will send once it has committed. */
     private readonly deferredWebhookDispatches;
     private readonly organizationTimeZone;
@@ -310,8 +318,20 @@ export declare class WorkflowEngineService {
      */
     private readDryRunMemberIds;
     getApprovalInstance(id: string, scope?: WorkflowReadScope): Promise<ApprovalInstanceEntity>;
+    /**
+     * ADR 25 §6: a value written to a filterable field must fit its type, on
+     * every path that writes form data. The fields checked are the ones the
+     * template's *current* version marks filterable, not the instance's own
+     * snapshot: an older instance can be re-filled, resubmitted or written by a
+     * service task after a newer version enabled filtering on a field, and the
+     * enable check (ADR 25 §5.4) guarantees the type is the same in every version
+     * that holds instances, so the current definition judges the old value too.
+     */
+    private assertCurrentFilterableFormDataValues;
+    /** The form schema of the template's current version, or `null` when there is none. */
+    private readCurrentFormSchema;
     listApprovalInstances(scope?: WorkflowReadScope, options?: ListApprovalInstancesOptions): Promise<readonly ApprovalInstanceEntity[]>;
-    countApprovalInstances(scope?: WorkflowReadScope, options?: Omit<ListApprovalInstancesOptions, 'page' | 'pageSize'>): Promise<number>;
+    countApprovalInstances(scope?: WorkflowReadScope, options?: Omit<ListApprovalInstancesOptions, 'page' | 'pageSize' | 'sort'>): Promise<number>;
     readApprovalInstancePageInfo(scope?: WorkflowReadScope, options?: ListApprovalInstancesOptions): Promise<{
         readonly hasNextPage: boolean;
         readonly hasPreviousPage: boolean;
@@ -320,7 +340,20 @@ export declare class WorkflowEngineService {
         readonly totalCount: number;
         readonly totalPages: number;
     }>;
-    private createFilteredApprovalInstanceQueryBuilder;
+    private createFilteredApprovalInstanceQuery;
+    /**
+     * The WHERE conditions and sort keys of the field filters and sort on the
+     * approval-instance list (ADR 25 §7). The template's current schema is read,
+     * and the static option lists of every version holding instances, only when
+     * a condition or a non-time sort key needs them.
+     */
+    private compileApprovalInstanceFieldQuery;
+    /**
+     * Static option lists by field path, across the current schema and the form
+     * version of every template version that holds instances (ADR 25 §7.3): a
+     * CONTAINS on a retired option still matches its name.
+     */
+    private readStaticOptionsByPathForTemplate;
     private applyReadableInstanceFilter;
     readWorkflowDashboardSummary(scope?: WorkflowReadScope, options?: WorkflowDashboardSummaryOptions): Promise<{
         readonly activeInstanceCount: number;
@@ -331,7 +364,12 @@ export declare class WorkflowEngineService {
         readonly totalInstanceCount: number;
     }>;
     private readDashboardOpenTasks;
-    listLaunchableApprovalTemplates(memberId: string): Promise<readonly ApprovalTemplateEntity[]>;
+    /**
+     * The active templates `memberId` may start now. `authContext` is handed to
+     * the host's initiator `customFields` resolver; a host calling this without
+     * one gets a bare context for the member, as a submission does.
+     */
+    listLaunchableApprovalTemplates(memberId: string, authContext?: BPMAuthContext): Promise<readonly ApprovalTemplateEntity[]>;
     listWorkflowTokens(instanceId: string, scope?: WorkflowReadScope): Promise<readonly WorkflowTokenEntity[]>;
     listTasks(instanceId: string, scope?: WorkflowReadScope): Promise<readonly TaskEntity[]>;
     listInboxTasks(assigneeMemberId: string): Promise<readonly TaskEntity[]>;
@@ -363,6 +401,54 @@ export declare class WorkflowEngineService {
      */
     private readTaskNodeSummaries;
     private readDefaultInitiatorMetadataSnapshot;
+    /**
+     * The initiator snapshot the engine builds itself: what it knows of the
+     * initiator, with `customFields` filled by the host's resolver when there is
+     * one. Without a resolver this is exactly the default snapshot
+     * (`customFields` is `{}`). A submission (`submission` set) stores it and
+     * judges the initiator policy with it; the launchable template list
+     * (`submission: null`) only judges the policies with it, so both see the same
+     * `customFields` for the same member.
+     *
+     * Only `customFields` comes from the host. The other keys are the engine's
+     * and are written back after the resolver returns, so nothing it does can
+     * change who the initiator is. The resolver gets copies of the snapshot and
+     * of the form data for the same reason; `authContext` is the caller's own
+     * object, as every other host hook receives it.
+     *
+     * The two callers treat a resolver failure (an error, a bad value, the
+     * timeout) differently, on purpose:
+     *
+     * - A submission fails, and no case is created. Its snapshot is stored and
+     *   routes the case from then on, so carrying on with `{}` would start a
+     *   case on data the host never gave. It runs before the engine
+     *   transaction, so a failure leaves nothing behind and a slow lookup holds
+     *   no lock.
+     * - The list carries on with `customFields: {}` and logs a warning: one
+     *   failing lookup must not take the whole list away. That fails closed: a
+     *   policy that reads `initiator.customFields` then throws on the missing key
+     *   and the list's per-template catch leaves that template out, while a
+     *   template whose policy does not read it is listed as usual. Submitting is
+     *   still judged against the resolver's real answer.
+     */
+    private buildInitiatorMetadataSnapshot;
+    /**
+     * Calls the host's initiator `customFields` resolver within
+     * {@link INITIATOR_CUSTOM_FIELDS_RESOLVER_TIMEOUT_MS} and returns what it
+     * gave as the object the snapshot keeps.
+     *
+     * Every failure becomes an `InternalServerErrorException` with a message
+     * meant for the member, and the cause goes to the log only, so nothing of
+     * the host's lookup reaches the client: running out of time, an error that
+     * is not an `HttpException`, and a value that is not a plain JSON object. An
+     * `HttpException` the resolver throws is passed on as it is, because the
+     * host chose that answer for the member.
+     *
+     * A resolver that settles after the time has run out is not waited for; what
+     * it settles with is logged and dropped, so a late rejection is never left
+     * unhandled.
+     */
+    private resolveInitiatorCustomFields;
     listActivityLogs(instanceId: string, scope?: WorkflowReadScope): Promise<readonly ActivityLogEntity[]>;
     private assertTaskReadable;
     private isApprovalInstanceReadableByMember;
@@ -393,10 +479,11 @@ export declare class WorkflowEngineService {
      * Re-resolves the delegation of a candidate whose turn has come. When the
      * delegate already holds another candidate row on the task, the stored values
      * are kept: (task_id, member_id) is unique, and that member signs from the
-     * row they already have. On a node that excludes the initiator the stored
-     * values are kept as well when the new delegation path would run through the
-     * initiator or the submitter: creation already filtered such paths out, and a
-     * delegation added while the candidate waited must not bring them back.
+     * row they already have. On a node that keeps members out (the initiator and
+     * submitter, or the approvers of earlier stages) the stored values are kept
+     * as well when the new delegation path would run through one of them:
+     * creation already filtered such paths out, and a delegation added while the
+     * candidate waited must not bring them back.
      */
     private resolveActivationDelegation;
     private markTaskCandidateDecision;
@@ -499,12 +586,52 @@ export declare class WorkflowEngineService {
      */
     private notifySeatReplaced;
     /**
-     * Resolves who gets the node's task. `null` means the node asked to be
-     * skipped (`excludeInitiator.whenEmpty = SKIP_NODE`) because the initiator
-     * was the only approver — the sole caller creates no task and advances the
-     * token instead.
+     * Resolves who gets the node's task. A {@link SkippedRuntimeTask} means the
+     * node asked to be skipped (`excludeInitiator.whenEmpty` or
+     * `excludeNodeActors.whenEmpty` = SKIP_NODE) because everyone left was kept
+     * out: the sole caller creates no task and advances the token instead.
+     *
+     * With both exclusions set the initiator rule runs first. When it alone
+     * leaves nobody, `excludeInitiator.whenEmpty` decides; when it leaves
+     * somebody and the earlier-stage rule then removes them all,
+     * `excludeNodeActors.whenEmpty` decides.
      */
     private resolveRuntimeTaskCandidates;
+    /**
+     * Everyone `node` keeps out of its approvers, per rule: the initiator and
+     * the submitter for `excludeInitiator`, and everyone who actually approved
+     * one of the listed earlier stages for `excludeNodeActors`. Read through
+     * `manager` so an approval written earlier in this transaction counts.
+     */
+    private readNodeExclusions;
+    /**
+     * The people who approved any of `nodeIds`, each listed node read on its own
+     * with the `NODE_ACTOR` rules ({@link readNodeActorMemberIds}) and the
+     * results combined. A source reads only the most recent of its listed nodes;
+     * an exclusion must cover every listed node, so it asks one node at a time.
+     *
+     * There is no round boundary here: a node's newest batch is what counts. The
+     * publish lint makes that the right batch, since every listed node runs and
+     * is signed by a person on every path to this node (a return to the start
+     * runs it again; a return to a stage below it leaves its earlier approval
+     * standing, and the exclusion with it).
+     */
+    private readExcludedNodeActorMemberIds;
+    /**
+     * Whether `targetMemberId` may not take a seat on `node` under
+     * `excludeNodeActors`, checked the way task creation checks a candidate: the
+     * target is one of the excluded members, or one end of a delegation between
+     * the target and an excluded member is on the path. A delegation is read in
+     * both directions, since the target may be the delegate of an excluded
+     * member, or delegate an excluded member's seat onward.
+     */
+    private isExcludedNodeActorTarget;
+    /**
+     * The principals the approvals stand for: a delegate who approved counts as
+     * the member who delegated to them, read from the candidate row each approval
+     * was signed on (see {@link readRuleDelegatorMemberIds}).
+     */
+    private readApprovalPrincipalMemberIds;
     private resolveInitiatorManagerReplacements;
     private buildDelegationContext;
     private delegateResolvedCandidates;
@@ -569,6 +696,12 @@ export declare class WorkflowEngineService {
      * tasks and approvals the SLA timeout made do not count.
      */
     private readNodeActorMemberIds;
+    /**
+     * The real approvals (earliest first) of the most recent batch among
+     * `nodeIds`: the rows {@link readNodeActorMemberIds} reads the approvers from.
+     * Kept as decisions so the exclusion can also reach each decision's task.
+     */
+    private readNodeActorApprovals;
     private resolvePositionCandidates;
     /**
      * The members who hold the position today (organisation time zone) within
@@ -578,12 +711,27 @@ export declare class WorkflowEngineService {
     private readActivePositionMemberIds;
     private resolveInitiatorManagerCandidates;
     /**
-     * Walks up the initiator's manager chain, nearest manager first, until a
-     * manager whose position level reaches `minPositionLevel` is added. The
-     * list is returned nearest manager first. Members in `skippedMemberIds` are
-     * walked past without joining the chain or counting as the stopping point.
+     * Walks up a manager chain, nearest manager first, until a manager whose
+     * position level reaches `minPositionLevel` is added. The chain starts at
+     * the initiator unless `startFrom` names someone else, and the start person
+     * is never on it: the walk begins at their direct manager. The list is
+     * returned nearest manager first. Members in `skippedMemberIds` are walked
+     * past without joining the chain or counting as the stopping point, and so
+     * are managers below `startPositionLevel`, until the first one at or above
+     * it starts the chain.
      */
     private resolveOrgManagerChainCandidates;
+    /**
+     * Whose manager an `ORG_MANAGER_CHAIN` starts from. `memberId` is `null`
+     * when the start names nobody (an empty form field, an earlier stage nobody
+     * approved), with `missingReason` saying why; `description` is the lead-in
+     * of the "no manager reaches the level" reason, empty for the initiator so
+     * a chain without a start keeps today's wording.
+     *
+     * A start that picks more than one person is refused rather than guessed,
+     * the same as a manager rule that names several managers at one priority.
+     */
+    private resolveOrgManagerChainStart;
     /** Highest position level over the member's active memberships, or `null`. */
     private readMemberPositionLevel;
     /**