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

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

@@ -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';
@@ -180,8 +181,9 @@ export declare class WorkflowEngineService {
     private readonly logger;
     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);
+    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;
@@ -362,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[]>;
@@ -394,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;
@@ -424,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;
@@ -530,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;
@@ -600,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
@@ -609,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;
     /**