Can Rock Handle Envelope Numbers? - Yes

  • By Chris Rea 2 Years Ago

AKA - How to Keep Your Arena-Trained Finance Team From Killing You

Rock gives you an abundance of tools to make whatever magic your church uses come to life.   I'm going to steer you through how I implemented this Envelope system for us, but it is far from the only way to do this!  If you haven't read the Workflow documentation at http://www.rockrms.com/Rock/BookContent/12/81 please read through it before reading this tutorial, otherwise you'll likely be confused and frustrated.

I handled this with a Workflow rather than any custom coding.  This Workflow is made in a very unique way, so please don't read too much into how it is constructed when trying to make a "normal" Workflow.  That being said, there are a couple of tricks this Workflow that could help you potentially solve similar design hurdles in some more interesting Workflows.

Don't worry if you get lost or confused.  I recommend reading the whole way through this guide before you try to re-read any of it.  It will make much more sense in it's entirety than it does in part.

Screen Shot 2016-12-06 at 10.07.33 PM.png


1) Where the Envelope Number is Stored

If you already have the Envelope Number as a result of the migration, reading over this section is still largely relevant.

I believe it makes sense to have an Envelope Number stored as a Person Attribute since you have to select a person for creating or matching a transaction.  You should probably also secure this Person Attribute to Financial Workers and up.  You also need to consider if you want to make this attribute a part of an Attribute Category.  This is helpful if you want to display this information with other similar Attributes on the Extended Attributes tab on the Person Profile page.  More on Extended Attributes at  http://www.rockrms.com/Rock/BookContent/5/74#extendedattributestab

But there's one more decision to make, who in a family gets the Envelope Number? Some people would consider adding this number to everyone in the family, but this is unnecessary and extra work for no advantage.  I recommend assigning the Envelope Number to whomever your church considers the head of the household.

In the next point, you'll have to record some information about this attribute that you just created.  If you already had the Envelope Number Attribute created before this tutorial, like as a result of migration or something similar, no worries! These instructions work either way.


2) Finding Some Information On Your Attributes

Your Workflow will need to know that Attribute ID of the Person Attribute where you stored the Envelope Number.  Please navigate to your Person Attributes page (out of box, it's found at Admin Tools -> General Settings > Person Attributes) and find the Attribute you're using to store your Envelope Numbers.  The number to the left of the Person Attribute is it's Attribute ID.  We'll need your specific Attribute ID later.
Screen Shot 2016-12-07 at 8.13.25 AM.png
At my church, they're called Giving Numbers, so you might see some of my configuration reflect that.  You'll also need to know the name of this Person Attribute, since you're going to have to select it to update it in the Workflow later.


3) Now, the Workflow

First you'll want to change the Processing Interval to 0.  This is something that you will frequently want to do with your Workflows.

At this point, you will start creating the Workflow. The Workflow will have two Activities and both of them will be "Activated with Workflow".  But before either Activity, you need to add some Workflow-Level Attributes.

These Attributes will hold onto some information while the Workflow's looping.  This guide will be using the listed Attributes.

Subject - Type: Person
Target - Type: Person
Envelope Number - Type: Integer (Although you can use Text, please use Integer to avoid SQL injection)

Although you don't have to use these exact names, they will be used in the context of this guide.  When you see "Giving#" in my screenshots, just read "Envelope Number" :)

3.5) Activity Attribute

You'll need to hold onto what choice the Financial Worker makes when using this Workflow.  I accomplished this with an Attribute within the Activity because it doesn't need to be permanent.  Activity Attributes are described in the documentation here http://www.rockrms.com/Rock/BookContent/12/81#configuringactivities. As of writing, this is specifically addressed in point 6 on the documentation page.

Selected Command - Type: Text

4) The User Entry Form

The first Activity in the Workflow is the User Entry Form.  This part has the most direct effect on the user.  I used a small amount of CSS/HTML to make my final result have a bit of a smaller footprint, rather than to have all of the attributes stacked on top of each other.

Here is how I set up the User Entry Form.  This is listed in the form of Attribute name, then the boxes that should be checked, and in the case of the Pre/Post HTML, the HTML that I used is also included.

Subject:

    Visible

    Pre-HTML

<div class="row">
<div class="col-md-4">

    Post-HTML

</div>

Target:

    Visible

    Editable

    Pre-HTML

<div class="col-md-4">

    Post-HTML

</div>

Envelope Number:

    Visible

    Editable

    Required -- (potentially, you don't need to make this required)

    Pre-HTML

<div class="col-md-4">

    Post-HTML

</div>
</div>


5) User Entry Form Submission

A picture is worth a thousand words... or at least 40ish.  This is the button configuration for the User Entry Form described above.  If you use different Command Labels, you'll need to change the corresponding Action Filters.

Screen Shot 2016-12-06 at 10.44.55 PM.png


6) Clear Subject Before Search

With the next Action, you're going to clear the Subject before you continue.  For the first run of the Workflow, this won't have a value to be cleared, but on subsequent runs it will.  If nothing else, trust me. This makes your Workflow a little cleaner to use.

A518 s1.png

7) Search for Person

Next, you'll be using a Run SQL action with the following SQL with your slight modifications made.  Please make sure to keep an eye on this SQL so in the case that you update a relevant Attribute, that you update the SQL statement accordingly.

The Run SQL command will have this Action Filter.  This is also to help the Workflow run a little cleaner for the person who uses it.

A518 s2.png

In the example below, the Key of my Envelope Number Workflow Attribute is "Giving" and the Attribute ID of my Envelope Number Attribute is "4332".  These bits of information were created in step 3 and found/created in step 2.  If you have too much trouble identifying this information, the Rock community would be glad to help.  The bolded parts of the SQL are what you'll need to replace with your values.

Select Top 1 pa.[Guid] from [Person] p
    Left Join [AttributeValue] av on av.EntityId = p.Id
    Left Join [PersonAlias] pa on pa.PersonId = p.Id

Where av.[AttributeId] = 4332     and av.[Value] = {{ Workflow | Attribute:'Giving' }}

And don't forget to set the Result Attribute to your "Subject", or this query will accomplish nothing and you'll be confused... Not that... I've... ever... uh... Moving on!


8) The Fun Stuff

The rest of this Workflow is all relatively simple, so you'll see a screenshot of my workflow and a brief explanation of it.

A518 s3.png

This Action actually saves the entered Envelope Number back to the Person put in the Target box.

A518 s4.png

This removes the value from the Envelope Number Attribute and, consequently, the box on the User Entry Form.

A518 s5.png

This clears the value of the "Target" Attribute every time an action is selected by the user.

A518 s6.png

This restarts the Activity so that the user can view the results and choose further actions if necessary.


9) You Said There Were Two Activities?

I did say that, thanks for remembering!  No worries though, this second activity is pretty easy to implement, but requires more explanation.  Don't forget to make sure this second activity also is "Activated with Workflow".  Without this second Activity, you'd just pile a bunch of running Workflows every time the Workflow was started.  We need to have a way to make the Workflow end.

The First Action is a Delay. I set mine to 10 minutes. The objective on how long you set the delay for is to think how long your users could sit on a single transaction before switching pages.

The Second Action is a Delete Workflow Action

These two combined make sure you don't have a pile of Zombie Workflows (Workflows that are dead but act like they're alive).  Zombie Workflows can be a huge drain on your Workflow Engine resources.

10) Test the Workflow

When you save the Workflow, you'll end up on a page that lets you hit a play button and you can check out your Workflow to make sure it works the desired way.  You should try making a few of them and leaving them in different steps in the Workflow.  Then check to make sure that they're deleting themselves.  Just so you know, it can and will take longer than the Delay timer for the Workflow to Delete because of the Process Workflow Job.

Workflows can take up to 10 minutes longer (by default settings) to delete, and if they don't delete automatically, check to make sure your "Process Workflow" job is running before you go on a bug hunt.  Hopefully your Workflow looks really similar to the one pictured below.

A518 s7.png

A518 s8.png


11) But Now What Do I Do With This Workflow?

You could put this block anywhere in Rock, but it makes the most sense to put it in the transaction matching and/or the transaction detail page directly below the primary block on the page.  This allows your financial worker to use this in their normal workflow with no extra tabs or pages open.


12) Making the Tool is Half the Battle

Worse than not making a tool that someone requests is having a tool that you put effort into that then gets added to a graveyard of things people have asked for but don't use.  Please make sure that you work with your Financial team to get them comfortable and excited to use this feature!

Unfortunately, it's impossible to address every possible question that could arise when building this for any interested church in a single blog post.

If you have additional questions, please let me know!  You can reach me in the Rock RMS Slack channel @chrisrea.  If you aren't a part of the Rock RMS Slack team, I highly recommend checking it out.  I'm a one man show at my church, and some days I can feel like I'm in over my head, but I know these guys willing to help you as much and more than I hope this article has helped you. You can join the Rock RMS slack at rockrms.com/Slack.

I'm glad to help you out with this guide!  Please consider paying it forward by sharing your expertise with those around you (when applicable).


@chrisrea
Life.Church