Skip to main content

ApprovalPlugin

The Plugin implements functions for handling the Approval history of your document and Inbox/Outbox.

The ApprovalPlugin main actions, conditions, rules and API.

Terms

Approval history

A list of completed and possible approvals for the given document.

Approval history: how to fill

  1. In the Pre-execution mode, for each activity, a record is created without any user info (IdentityId, TransitionTime, Commentary, TriggerName)
  2. In the Execution mode, the record is updated with filling the info about the transition and the user (IdentityId, TransitionTime, Commentary, TriggerName).

Stored in the WorkflowApprovalHistory table.

Approval history: structure

public class ApprovalHistoryItem
{
// record Id
public Guid Id { get; set; }
// Id of the process (document) to be approved
public Guid ProcessId { get; set; }
// Id of the user already approved the document at the current stage
public string IdentityId { get; set; }
// list of users who can approve the document at the current stage
public List<string> AllowedTo { get; set; }
// time of the document approval
public DateTime? TransitionTime { get; set; }
// sequential number of the approval stage
public long Sort { get; set; }
// state prior to the approval
public string InitialState { get; set; }
// state after the approval
public string DestinationState { get; set; }
// name of the approval that already done
public string TriggerName { get; set; }
// user's comment specified during the approval
public string Commentary { get; set; }
}

Approval history: how to get

  1. Use PersistenceProvider:

    // get by IdentityId
    var approvalHistory = await runtime.PersistenceProvider
    .GetApprovalHistoryByIdentityIdAsync(myIdentityId,
    Paging.Create(pageIndex, pageSize));
    // get count for paging
    var approvalHistoryCount = await runtime.PersistenceProvider
    .GetApprovalHistoryCountByIdentityIdAsync(myIdentityId);

    // get by ProcessId
    var approvalHistory = await runtime.PersistenceProvider
    .GetApprovalHistoryByProcessIdAsync(myProcessId,
    Paging.Create(pageIndex, pageSize));
    // get count for paging
    var approvalHistoryCount = await runtime.PersistenceProvider
    .GetApprovalHistoryCountByProcessIdAsync(myProcessId);
  2. Use action: GetApprovalHistory:

    Add the action to the activity or drag the specified custom activity from the Elements panel.

Inbox

For the current stage of approval, gives the list of users and the command available for execution.

Inbox: how to fill

When ProcessStatusChanged event in WorkflowRuntime is triggered, the table is cleared and refilled. Read about it here.

Stored in the WorkflowInbox table.

Inbox: structure

public class InboxItem
{
// record Id
public Guid Id { get; set; }
// Id of the process (document) to be approved
public Guid ProcessId { get; set; }
// Id of the user who can approve the document
public string IdentityId { get; set; }
// date of the record
public DateTime AddingDate { get; set; }
// list of approvals available to the user
public List<CommandName> AvailableCommands{ get; set; }
}

Inbox: how to get

  1. Use PersistenceProvider:

    // get by IdentityId
    var inbox = await runtime.PersistenceProvider
    .GetInboxCountByIdentityIdAsync(myIdentityId,
    Paging.Create(pageIndex, pageSize));
    // get count for paging
    var inboxCount = await runtime.PersistenceProvider
    .GetInboxCountByIdentityIdAsync(myIdentityId);

    //get by ProcessId
    var inbox = await runtime.PersistenceProvider
    .GetInboxByProcessIdAsync(myProcessId,
    Paging.Create(pageIndex, pageSize));
    // get count for paging
    var inboxCount = await runtime.PersistenceProvider
    .GetInboxCountByProcessIdAsync(myProcessId);
  2. Use action: GetInbox:

    Add the action to the activity or drag the specified custom activity from the Elements panel.

Outbox

A list of documents agreed upon by the user (or his deputies).

Outbox: how to fill

Formed by a request from the WorkflowApprovalHistory table.

Outbox: structure

public class OutboxItem
{
// Id of the process (document) already approved by the user
public Guid ProcessId { get; set; }
// date and time of the first approval of this document by the user
public DateTime? FirstApprovalTime { get; set; }
// date and time of the last approval of this document by the user
public DateTime? LastApprovalTime { get; set; }
// total number of approvals of this document by the user
public int ApprovalCount { get; set; }
// name of the last approval of this document by the user
public string LastApproval { get; set; }
}

Outbox: how to get

  1. Use PersistenceProvider:

    // get by IdentityId
    var outbox = await runtime.PersistenceProvider
    .GetOutboxByIdentityIdAsync(myIdentityId, Paging.Create(pageIndex, pageSize));
    // get count for paging
    var outboxCount = await runtime.PersistenceProvider
    .GetOutboxCountByIdentityIdAsync(myIdentityId);
  2. Use action: GetOutbox:

    Add the action to the activity or drag the specified custom activity from the Elements panel.

How it works

For example, consider a simple 3-step process:

  1. Request - the document is created and ready for approval.
  2. Manager signed - the document is approved by a manager.
  3. Boss signed - the document is approved by the boss.

Current state: request

1

At this stage, the ApprovalHistory, Inbox, Outbox tables look as follows:

Approval history

2

Inbox

For Manager:

3

For Boss:

4

Outbox

For Manager:

5

For Boss:

5

Current state: Manager signed (After manager approve)

6

After the first approval, the ApprovalHistory, Inbox, Outbox look as follows:

Approval history

7

Inbox

For Manager:

8

For Boss:

9

Outbox

For Manager:

10

For Boss:

11

Current state: boss signed (After boss approve)

12

At the final stage, the ApprovalHistory, Inbox, Outbox tables look as follows:

Approval history

13

Inbox

For Manager:

08

For Boss:

08

Outbox

For Manager:

10

For Boss:

14

Installation and settings

Add the following namespaces to the section of the using statements:

using OptimaJet.Workflow.Plugins;

Create a plugin object and specify the necessary settings:

var approvalPlugin = new ApprovalPlugin();

// Here are your settings

// approvalPlugin.GetUserNamesByIds += GetMyUserNamesByIds;
// approvalPlugin.AutoApprovalHistory = false;
// NameParameterForComment = "Comment";

Connect the plugin to WorkflowRuntime:

var runtime = new WorkflowRuntime()...

runtime.WithPlugin(approvalPlugin);

Read about Settings.

Cases

How to get list of users who can approve document

  1. Install and configure plugin.

  2. Get inbox:

    // get by ProcessId
    var inbox = await runtime.PersistenceProvider
    .GetInboxByProcessIdAsync(myProcessId, Paging.Create(pageIndex, pageSize));
    // get count for paging
    var inboxCount = await runtime.PersistenceProvider
    .GetInboxCountByProcessIdAsync(myProcessId);
  3. Get users:

    // get employee for every one inbox item
    var identityIdS = inbox.Select(x => x.IdentityId).ToList();
    var identities = employeeRepository.GetByIds(identityIdS);

    // or

    var identities = new List<Employee>();
    foreach (InboxItem inboxItem in inbox)
    {
    Employee employee = employeeRepository.Get(inboxItem.IdentityId);
    identities.Add(employee);
    }

How to get list of documents that can be approved by user

  1. Install and configure plugin.

  2. Get inbox:

    // get by IdentityId
    var inbox = await runtime.PersistenceProvider
    .GetInboxCountByIdentityIdAsync(myIdentityId,
    Paging.Create(pageIndex, pageSize));
    // get count for paging
    var inboxCount = await runtime.PersistenceProvider
    .GetInboxCountByIdentityIdAsync(myIdentityId);
  3. Get documents:

    // get document for every one inbox item
    var processIds = inbox.Select(x => x.ProcessId).ToList();
    documentRepository.GetByIds(processIds);

    // or

    var documents = new List<Document>();
    foreach (InboxItem inboxItem in inbox)
    {
    Document document = documentRepository.Get(inboxItem.ProcessId);
    documents.Add(document);
    }

How to get approval history of document

  1. Install and configure plugin.

  2. Get approvalHistory:

    // get by ProcessId
    var approvalHistory = await runtime.PersistenceProvider
    .GetApprovalHistoryByProcessIdAsync(myProcessId,
    Paging.Create(pageIndex, pageSize));
    // get count for paging
    var approvalHistoryCount = await runtime.PersistenceProvider
    .GetApprovalHistoryCountByProcessIdAsync(myProcessId);

How to get list of documents approved by user

  1. Install and configure plugin.

  2. Get outbox:

    // get by IdentityId
    var outbox = await runtime.PersistenceProvider
    .GetOutboxByIdentityIdAsync(myIdentityId,
    Paging.Create(pageIndex, pageSize));
    // get count for paging
    var outboxCount = await runtime.PersistenceProvider
    .GetOutboxCountByIdentityIdAsync(myIdentityId);
  3. Get documents:

    // get document for every one outbox item
    var processIds = outbox.Select(x => x.ProcessId).ToList();
    documentRepository.GetByIds(processIds);

    // or

    var documents = new List<Document>();
    foreach (OutboxItem outboxItem in outbox)
    {
    Document document = documentRepository.Get(outboxItem.ProcessId);
    documents.Add(document);
    }