Approval Plugin

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

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

Approval history

Inbox

For Manager:

For Boss:

Outbox

For Manager:

For Boss:

Current state: Manager signed (After manager approve)

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

Approval history

Inbox

For Manager:

For Boss:

Outbox

For Manager:

For Boss:

Current state: boss signed (After boss approve)

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

Approval history

Inbox

For Manager:

For Boss:

Outbox

For Manager:

For Boss:

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);
}