@rytass/bpm-core-nestjs-module 0.15.0 → 0.17.0

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

@@ -26,7 +26,7 @@ import { ApprovalInstanceEntity } from './approval-instance.entity';
 import { TaskDecisionEntity } from './task-decision.entity';
 import { TaskCandidateEntity } from './task-candidate.entity';
 import { TaskEntity } from './task.entity';
-import { ApprovalInstanceListViewEnum, ApprovalInstanceStateEnum } from './workflow-engine.enums';
+import { ApprovalInstanceListViewEnum, ApprovalInstanceStateEnum, MemberTaskRoleEnum, TaskCandidateStatusEnum, TaskReassignmentErrorCodeEnum, TaskReassignmentOutcomeEnum } from './workflow-engine.enums';
 import { WorkflowDryRunResultObject } from './workflow-dry-run.object';
 import { BPMWorkflowServiceTaskDispatcher } from './workflow-service-task-dispatcher.token';
 import { WorkflowTokenEntity } from './workflow-token.entity';
@@ -60,10 +60,54 @@ export declare const MAX_APPROVAL_INSTANCE_BUSINESS_KEY_LENGTH = 200;
  * opposed to {@link SLA_ESCALATION_DELEGATION_REASON}.
  */
 export declare const MANUAL_TRANSFER_DELEGATION_REASON = "MANUAL_TRANSFER";
+/**
+ * Delegation-chain reason for a seat an administrator moved to another member
+ * (see {@link WorkflowEngineService.reassignTask}). The step's `actorMemberId`
+ * names the administrator and `comment` carries the reason they typed.
+ */
+export declare const ADMIN_REASSIGN_DELEGATION_REASON = "ADMIN_REASSIGN";
+export interface TaskReassignmentResult {
+    readonly errorCode: TaskReassignmentErrorCodeEnum | null;
+    readonly instanceId: string;
+    readonly message: string | null;
+    readonly nodeId: string;
+    readonly outcome: TaskReassignmentOutcomeEnum;
+    readonly taskId: string;
+}
+export interface ReassignTaskOptions {
+    readonly actorMemberId: string;
+    readonly dryRun?: boolean | null;
+    readonly fromMemberId: string;
+    readonly reason: string;
+    readonly toMemberId: string;
+}
+export interface MemberOpenTaskRecord {
+    readonly candidateStatus: TaskCandidateStatusEnum | null;
+    readonly createdAt: Date;
+    readonly decisionPolicyType: string;
+    readonly businessKey: string | null;
+    readonly instanceId: string;
+    readonly instanceTitle: string;
+    readonly memberRole: MemberTaskRoleEnum;
+    readonly nodeId: string;
+    readonly nodeLabel: string | null;
+    readonly slaDueAt: Date | null;
+    readonly taskId: string;
+    readonly templateId: string;
+    readonly templateName: string | null;
+}
 /**
  * Engine-internal decision knobs that are deliberately kept out of
  * {@link DecideTaskInput} so they never reach the GraphQL schema.
  */
+/** Input of {@link WorkflowEngineService.expireApprovalInstance}. */
+export interface ExpireApprovalInstanceCommand {
+    readonly comment?: string | null;
+    readonly instanceId: string;
+    /** The overdue task's node and the task itself, for the activity record. */
+    readonly nodeId?: string | null;
+    readonly taskId?: string | null;
+}
 export interface DecideTaskOptions {
     /**
      * Reason stamped on the delegation-chain step when the decision is a
@@ -104,6 +148,7 @@ export declare class WorkflowEngineService {
     private readonly slaScheduleService;
     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 serviceTaskDispatcher;
     private readonly organizationTimeZone;
@@ -127,6 +172,16 @@ export declare class WorkflowEngineService {
     processInstance(instanceId: string): Promise<void>;
     decideTask(input: DecideTaskInput, options?: DecideTaskOptions): Promise<TaskDecisionEntity>;
     cancelApprovalInstance(input: CancelApprovalInstanceInput): Promise<ApprovalInstanceEntity>;
+    /**
+     * Ends a running or returned instance because a task on it ran past its SLA
+     * with `onTimeout: 'TERMINATE_INSTANCE'`. It closes the instance exactly as
+     * a cancellation does, but lands in `EXPIRED` and is recorded with no actor:
+     * nobody chose to end it. An instance that is already closed — another
+     * overdue task of it got here first, or someone decided it meanwhile — is
+     * returned unchanged.
+     */
+    expireApprovalInstance(input: ExpireApprovalInstanceCommand): Promise<ApprovalInstanceEntity>;
+    private closeInstance;
     resubmitApprovalInstance(input: ResubmitApprovalInstanceCommand, authContext?: BPMAuthContext): Promise<ApprovalInstanceEntity>;
     requestAdhocCountersign({ comment, requestedByMemberId, target, taskId, }: {
         readonly comment?: string | null;
@@ -226,10 +281,20 @@ export declare class WorkflowEngineService {
         readonly rejectedInstanceCount: number;
         readonly totalInstanceCount: number;
     }>;
+    private readDashboardOpenTasks;
     listLaunchableApprovalTemplates(memberId: string): 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[]>;
+    /**
+     * The open tasks that are this member's own to act on — the single
+     * definition behind both the inbox list and the dashboard counters, so the
+     * two can never disagree. A task is theirs when it is assigned to them, or
+     * when they hold a PENDING or CLAIMED candidate row on it. A sequential
+     * chain's later candidates sit in WAITING until it is their turn, so a task
+     * that has not reached them is not theirs yet.
+     */
+    private readOpenInboxTasks;
     listApprovalHistoryTasks(assigneeMemberId: string): Promise<readonly TaskEntity[]>;
     listTaskDecisions(taskId: string, scope?: WorkflowReadScope): Promise<readonly TaskDecisionEntity[]>;
     listTaskCandidates(taskId: string, scope?: WorkflowReadScope): Promise<readonly TaskCandidateEntity[]>;
@@ -284,6 +349,80 @@ export declare class WorkflowEngineService {
     private resolveActivationDelegation;
     private markTaskCandidateDecision;
     private transferTask;
+    /**
+     * Administrator reassignment of one open task, moved in place: the task keeps
+     * its id, decision policy, SLA and every other seat. Only `fromMemberId`'s
+     * seat (and the assignee field, when it is theirs) moves to `toMemberId`.
+     *
+     * This is not a decision by the holder: it writes no TaskDecision and no
+     * signature. It is recorded as a TASK_REASSIGNED activity and an
+     * {@link ADMIN_REASSIGN_DELEGATION_REASON} delegation step.
+     *
+     * Unlike the holder's transfer, the target is NOT run through the delegation
+     * rules (a rule for `toMemberId` does not apply). The initiator and submitter
+     * exclusions and the grade check of ORG_MANAGER_CHAIN nodes still do.
+     *
+     * A refused reassignment is reported as `REJECTED` with an error code. When
+     * `dryRun` is off, a refusal is thrown as a ConflictException whose message
+     * carries that code.
+     */
+    reassignTask(taskId: string, options: ReassignTaskOptions): Promise<TaskReassignmentResult>;
+    /**
+     * Runs {@link reassignTask} for every open task `fromMemberId` holds, each in
+     * its own transaction, and reports one result per task. A failing task does
+     * not stop the others: a refusal is a REJECTED result, and an unexpected
+     * error is reported as REJECTED with UNEXPECTED_ERROR for that task alone.
+     */
+    reassignMemberTasks(options: ReassignTaskOptions): Promise<readonly TaskReassignmentResult[]>;
+    /**
+     * The open tasks a member holds, for the administrator's reassignment screen.
+     * Same definition as the inbox, plus WAITING sequential seats, restricted to
+     * RUNNING instances.
+     */
+    listMemberOpenTasks(memberId: string): Promise<readonly MemberOpenTaskRecord[]>;
+    /**
+     * The open tasks `memberId` holds on RUNNING instances, with the instance
+     * each belongs to. The instance filter is applied here, not only in the query.
+     */
+    private readRunningMemberTasks;
+    private executeTaskReassignment;
+    /**
+     * Checks every rule of an administrator reassignment under the instance lock,
+     * against the rows as they are now. Writes nothing; a refusal throws
+     * {@link TaskReassignmentRejectedError}.
+     */
+    private planTaskReassignment;
+    private applyTaskReassignment;
+    /**
+     * A holder's transfer of their seat on a group stage (PARALLEL_ALL,
+     * PARALLEL_ANY, QUORUM). The stage stays open: the transferring seat moves
+     * to the target in place, the other seats keep their state, and the task
+     * keeps its id. Unlike transferTask, no replacement SINGLE task is created
+     * and the other voters are not superseded. The transferring member's
+     * decision and signature are kept on the task.
+     */
+    private transferGroupSeat;
+    /**
+     * Moves one open seat from `fromMemberId` to `toMemberId` on the same task.
+     *
+     * With a source candidate row: that row is marked TRANSFERRED, and the target
+     * takes a row with the same sequence, source type and original member. A
+     * WAITING seat stays WAITING; anything else becomes PENDING. A closed row the
+     * target already has (CANCELLED, SUPERSEDED, TRANSFERRED) is reused, because
+     * the database allows one row per (task, member).
+     *
+     * Without one (a direct assignee with no candidate row) only the assignee
+     * field moves. When the source is the assignee, the assignee moves too and
+     * the step is appended to the task's chain.
+     */
+    private replaceOpenSeat;
+    /**
+     * Notifications for a replaced seat: the member who gave it up is resolved as
+     * TRANSFERRED (their notifications on this task only), and the member who
+     * takes it is notified now if the seat is active. A WAITING seat notifies
+     * when its turn comes, through the normal sequential activation.
+     */
+    private notifySeatReplaced;
     /**
      * Resolves who gets the node's task. `null` means the node asked to be
      * skipped (`excludeInitiator.whenEmpty = SKIP_NODE`) because the initiator
@@ -304,8 +443,21 @@ export declare class WorkflowEngineService {
      * constraint.
      */
     private assertTransferTargetGrade;
+    /**
+     * The grade a transfer target must reach, or `null` when the target passes.
+     * Seniority is measured from the member being replaced: the first delegator
+     * on their chain, or that member themselves. Shared by the user transfer
+     * (which throws) and the administrator reassignment (which reports).
+     */
+    private readTransferTargetRequiredGrade;
     private resolveApproverResolver;
     private resolvePositionCandidates;
+    /**
+     * The members who hold the position today (organisation time zone) within
+     * their effective period. Primary memberships come first, then the most
+     * recently started. Empty when nobody holds it; never throws.
+     */
+    private readActivePositionMemberIds;
     private resolveInitiatorManagerCandidates;
     /**
      * Walks up the initiator's manager chain, nearest manager first, until a
@@ -321,6 +473,13 @@ export declare class WorkflowEngineService {
      * requested member is in the map, `null` when they hold no graded position.
      */
     private readMemberPositionLevels;
+    /**
+     * Every member a manager resolver's fallback yields. A `DIRECT` or `NONE`
+     * fallback yields at most one; a `POSITION` fallback yields the position's
+     * current holders, minus the initiator unless the fallback allows self
+     * approval. Failure throws, as the single-member path does.
+     */
+    private resolveFallbackAssignees;
     private resolveFallbackAssignee;
     private resolveManagerMemberIdsFromOrganization;
     private resolveManagerMemberIdsAtLevel;