Seeking Approval - Part 1: The Basics and the Approval - User activity

[russ_sarbora]

Automating an approval process is a common use case for workflow, but can sometimes lead people into difficulties. I thought it would useful to explain how the different approval activities work, and when and how they should be used. Its a big subject, so I expect this will turn into a multi-post series. I'm going to start with some simple examples and digging into the underlying mechanics of how Workflow uses Approvals. But I also want to address issues you're facing with complicated approval processes, so send me your questions and problems, and I'll make them the subject of a later post.

Approvals and Workflows

Many people assume that approvals are a feature of workflow, but that's not actually true. Approvals are an independent part of the product. Workflow integrates with Approvals via several activities that allow authors to incorporate Approvals into their flows. These Approval activities have two jobs:

1) create one or more approvals (records in an approval table)

2) aggregate the resolved (approved or rejected) approvals into a final approve/reject decision.

The diagram attempts to show this in action.   The blue boxes and arrows represent the logic flow of the workflow. When we transition into an Approval activity, the activity creates a set of approval records.This is job #1 and it is now finished. The activity then goes into a wait state. (Technically, it checks for an auto-approve situation first, but we'll talk about that later in the post).     Notice that there is no blue line coming out of the "wait for an event box". That's because the workflow is not

responsible for waking that activity up. As far as workflow is concerned, mission is complete, time to go home for a nap.

Now notice the sun thingy with the dotted line, those aren't gray and dotted just because I have limited diagramming skills. They indicate that the event that will wake this activity back up comes from outside of workflow. (Another technical point, its completely legit to fire the event from a different workflow or even another branch of the same workflow, but the point is, something other than this activity needs to do it) Whenever an approval record changes state, the process changing that state is responsible for firing the event that tells workflow to wake up and get back to work. Out-of-the-box, we ship business rules on the approval tables that take care of firing this event for you.

Only after workflow receives its event will it move on to job #2. Here it uses the state of the approvals it cares about to make a final approve/reject decision. If a decision is possible, the activity is complete and the workflow takes the corresponding transition to the next activity. If it can't, the activity goes back to napping waiting for another wake up call.

When you are designing an approval flow, or troubleshooting one that's not behaving the way you expected, it's helpful to keep these two jobs in mind. Is your activity generating the approval records you expect? If not, that's a workflow problem. Once those records get approved or approved or rejected, is the activity making the final decision that you expected? If not, that's a workflow problem. But if those records aren't getting approved or rejected, or the workflow isn't getting notified that they changed state, that's not a workflow problem. Find out why that event is not getting sent.

Now that we understand how Workflow uses Approvals, Let take a look at some approval activities in action, I'll start with Approval - User.

Workflow Setup Note

When I'm doing stuff like this, I like having a fresh, new table with no existing records, business rules, or other workflows interfering with what I'm working on. So I created a custom table to use for the workflows in this post. Its just a simple extension of the "task" table with no additional columns. I named mine "u_wfapprovals_test". If you are building your own copy of the workflows in this post, you can either:

• create your own custom table
• download and install the update set attached to this post
• use one of the existing task-derived tables

I recommend installing the attached update set. It includes the table, the workflow we're going to build, and a couple extra goodies that make following along with the post easier.   In the rest of the post, I'm going to assume that you've installed this update set.

Approval - User : the Swiss Army knife of approval activities

As I said above, the first part of an Approval activity's job is to create the approvals. In the case of Approval - User, these will be individual approvals, one for each specified user, each carrying equal weight on the final approval decision.

Approval - User is extremely versatile, and gives you several ways to identify the users that will get an approval record. The different config options for doing that are documented in the wiki, so I'm not going to cover them here. Approval - User even allows you to write scripts to control both identifying what users are going to be asked for approval, as well as the logic for determining the final Approved/Rejected decision. Its also available no matter what table your workflow is running on, in other words, Approval - User can be used to add an approval to anything. This why I called it the Swiss Army knife of approval activities.

For now, we're just going to create a very simple scenario in order to understand what happens under the covers in a Workflow Approval activity.   Go into the Workflow Editor, and open the "Seeking Approval - 1. Basic Approval User" workflow. The workflow is very simple, and looks like this.

The configuration for the Approval - User activity is also very simple, selecting a single approving user. It will be whoever is the Assigned To on the record that starts the workflow.

In Action

Now let's test it out. Create a new u_wfapprovals_test record (if you've installed the accompanying update set, you should have a "WF Approvals" application and "WF Approvals Test" module in your left-hand nav). On the form, the only field you need to complete is the Assigned To. I'm going to pick "Fred Luddy".

After submitting the record, open the workflow execution context that resulted (here's another UI goodie from the update set, there should be a "Workflow Context" UI Action available in both the form and list views of u_wfapprovals_test. In the List view, the action appears on the context menu that pops up when you right-click on a row of the list. In the Form view, the action will show up as a Related Link at the bottom of the form). Then click "Show Workflow" to open the context diagram view in a new browser tab. You should see something like this:

What we're seeing here is that the workflow has transitioned into the Approval - User activity, and is now waiting for that activity to complete. Remember what I said above? Approval activities do 2 things:

1) identify a list of users that need to approve this record and create approval records for them,

2) as those individual approval records are resolved, accumulate them into a final Approved/Rejected decision.

So our activity has completed the first part of its job, creating an approval for the User specified in the activity config (in our case, just Fred Luddy), and is now waiting for that approval to be resolved. To confirm that, go back to the main SNC browser tab and open your test record's form view. You should have an Approvers related list, and there should be one approval in it, for Fred Luddy, in state=Requested.  

Let's give the Approval - User activity what it wants, by approving(or rejecting) Fred's approval request.   Right-click on the request (or open it in form view), and Approve it. The approval's state will change to Approved. That change of state will be detected by a business rule on the approval table, which will in turn wake up the workflow and fire an event to the Approval - User activity to tell it to try and make a final decision. Go back to the tab containing the Workflow Context Diagram and refresh it. The Approval - User activity should have taken the Approved transition and the workflow will be completed. This is the second part of an Approval activities job - checking the state of its approvals, and when possible, make a final Approved/Rejected determination.

For our simple case, Fred's approval is all the activity needed to make a final decision. For more complicated scenarios, Approval - User provides two different fields that let you specify how that final decision is made: Wait For, and When Anyone Rejects. These are also documented pretty well in the wiki, so I don't think I need to go into details on them. And if those two don't meet your needs, you can select the Wait For = Condition based on Script option and provide your own custom approval decision logic.

Auto-Approving

There's one more topic I want to cover in this post: Auto-approving. Insert another test record (u_wfapprovals_test), but this time leave the Assigned To field blank. Then pull up the Context Diagram for that workflow execution. It will have already completed, with the activity taking the Approved transition, even though it never waited for an approval. What happened?

The Approval - User activity in our flow is configured to create an approval for one user, whoever the Assigned To user is on our test record. Because we left that field empty on this particular record, no approval could be generated. You can double-check the Approvals table (sysapproval_approvers) to confirm that there are no requested approvals for our test record. In this situation, the workflow will set the state of the activity to "Skipped", and the Approval - User activity will take the Approved transition.

This auto-approving behavior occasionally trips new workflow authors up if they aren't aware of it, but we've found it makes sense in most situations. If you have a use case where auto-approving is a problem, there is a fairly simple workaround. Configure the Approval - User activity to generate an approval for a hard-coded user account in addition to whatever "real" approvals you need. This extra approval will sit in state=Requested and won't affect the final Approved/Rejected decision as long as you don't select the Wait For Everyone to Approve option in the activity configuration.

Note: There was a bug fix in the Eureka release that affects this area. As of Eureka, approvals will not be created for inactive Users. In previous releases, as long as there was a matching User account, the approval would be created, even if the user was inactive and therefore unable to act on the approval. We figured that would be bad, so we fixed it. but it could mean that after upgrading to Eureka, new workflow contexts from workflows which would wait on approvals from inactive users pre-Eureka will automatically approve after you upgrade.

The End - For Now

That's the meat and potatoes of Workflows and Approvals. In the next post I plan to cover the Approval - Group, Manual Approval, and Approval Coordinator activities. I would also like to do a post with some best-practice patterns for handling difficult real-world approval scenarios. So if you have a specific use case you're struggling with, send it to me.

See Seeking Approval - Part 2: Task vs non-Task approvals and the Approval - Group Activity and Seeking Approval - Part 3 : Manual Approvals and Approval Coordinator for more information.