Project Management

Version 2.2.1

Last Updated Oct 13, 2018

Table Of Contents


Overview

The Project Management system is designed to give you an easy way to quickly enter and track simple task-based projects. But it also provides the power to expand into more comprehensive project management with sub-projects, blocked tasks and a powerful comment system.

Each project is requested by a single person but can be assigned to multiple people. A project can have tasks that each can be assigned to a single person. Projects can also have sub-projects associated with them if a task to be completed is complex enough to warrant sub-dividing it further. Finally, each type of project can have custom attributes associated with it. This gives you the ability to customize your projects and provide the information you need in order to efficiently complete the project.

E-mail notifications are also built in to keep you up to date when: a project is assigned to you; a task is assigned to you; a new comment on a project you are involved with; a project is marked as completed. This e-mails allow you to easily keep two-way communication open between the requester and those working to accomplish the request.

Project types allow you to define custom attributes, e-mail templates and other settings for the project. A project is also assigned to a category. These categories allow you to organize and group similar projects together, even if they are of different project types.

Quick Start

While you will want to look over the configuration section to understand how to get the most out of Projects, out of the box this plugin is ready to go. A category, project type and project entry button have been configured for you so you can start entering test projects right now.

Project Detail Page

To get started you will want to navigate to the Tools > Project Entry page. This is where most of your staff will be entering new projects from. Click on the General Project button and you can enter a name for the project as well as some details. Details and Comments are written in something called Markdown. But don't worry about that now. Just type text like you normally would and it generally will figure out what you want. You can always click the Preview button to see what it's going to look like. If you want to add an attachment you can use the upload button, or simply drag the file into the editor and it will upload it for you.

Now that we have some details typed in, click Save and you will be taken to the Project Details screen. On this screen you can see the full details of the project. On the right you will be able to see (and add) individual tasks as well as sub projects. The last box on the right shows you everybody that has participated in the project (that is, the requestor, those assigned to it and anybody that has left a comment. Try adding a few tasks and assign them to various people.

Comments work with the same editor as the details. Something we didn't mention above is, well, mentions. You can mention somebody by preceding their name with the @ symbol. This will send them an e-mail if they are not already part of the discussion. Try adding a comment and mention somebody so you can see the e-mail they recieve.

Before we go marking the project as completed, go to the Tools > Projects menu and and you can see all the project types. Click the "Basic Project" button and you should then see a grid, with the project you just created. You can do various filters here, such as limiting the list only to projects assigned to a specific person. Clicking on a project will take you back to the details screen. And on the details screen you can click the Complete button to mark the project as completed.

Configuration

Out of the box, no configuration is necessary to begin entering projects. A default category and project type is created for you to use. But not to worry, you can create as many or as few categories and project types as you need.

Categories

Categories are only used for organizing projects of varying types into a single view. You may, for example, want to have a category for all Media projects. Even though the different projects in that category might be of different project types. Another example, Video Requests and Graphics Requests might be two different project types, but the projects for all of those may get put in the same Media category.

Categories can be added through the Installed Plugins > Project Management > Project Categories page.

Project Types

Project Type configuration is done through the Installed Plugins > Project Management > Project Types page. From here you can add, edit and remove project types from the system. You can also view a list of all projects for a given project type.

Add Project Type

If you have used Rock for any period of time, you should be familiar with these various fields. The name is what will be displayed in the UI whenever this project type is referenced. A project type can be marked not-active and this will prevent users from being able to create new projects of this type. The icon class is used on various pages to help identify projects of this type visually. Finally the description is an internal field that you should use to describe in as much detail as you can when this project type is to be used.

Add Project Type

Anytime a file is uploaded and attached to a project description or a comment it will be saved using the file type that is specified here. This does not set the file type of any attributes you add below. This is only for files that are attached via the text editors.

The four e-mail fields let you specify the system e-mails to use for any projects of this type. If you leave the field blank then that specific e-mail will not be sent for this project type.

The Child Project Types behaves similar to the child group types with your group structure. This field specifies which project types can be made sub projects to a project of this type. Sub projects will be discussed in more detail further below in the documentation.

Add Project Type

You know about properties. You've made a few. You probably even wish you hadn't made some of the attributes you've made. Project attributes work just like attributes on any other entity. The only thing you will probably notice different is the additional checkbox for "Entry Form". Any attribute that is flagged for "Entry Form" will be visible on the project entry screens. This allows you to have attributes that are available to the user when they enter a new project and other attributes that are only available to those that can edit an existing project.

Project Entry

Project entry normally happens through a dedicated page. This page hides a number of fields that normally shouldn't be visible to the requester. A few examples are the project type, category and due date to name a few.

Project Entry List

To enter new projects, you should direct users to the Tools > Project Entry page. This pages shows any configured projects that can be requested by the users. Each button is essentially a combination of the Category, Project Type and Default Assignees. For example, you may have multiple buttons for the project type of General Projects, but each button creating the project in a different category and a different person assigned by default.

Project Entry List Settings

The list of which buttons are available is available in the block settings. The settings allows you to specify the Lava Template used to render the buttons, in case you want to override the default layout. Finally, each button is configured as a line item in the settings. You can have a project automatically assigned to either an individual person or a group of persons. Because this is all done as a block setting it means you could create additional pages to further divide up the buttons.

Project Entry List Item

Adding a new item to the project entry list is straightforward. Give the button a title, project type and a category. By default the button will use the icon from the project type, but you can provide your own icon class for this button.

If the project should be automatically assigned to a person then you can select the person here. They will be assigned and receive an e-mail (if configured) automatically. If you need to assign multiple people you can place them in a group and select the group. Each member of the group will be assigned to the project.

Note: A project can only be assigned to people. When using the Default Assignee Group then the project gets assigned to any active members of the group when the project is created.

Dashboard Blocks

There are two blocks that can be added to your users' dashboard page if you want to put them in. One shows projects for the user and the other shows tasks.

My Projects

My Projects

The My Projects block allows the user to view three different collections of projects: Assigned to them, Requested by them, and Followed by them. Clicking on the project name will take them to the project detail page. Each item contains a summarized version of the details of the project:

  • Project Name
  • Number of completed/total tasks
  • Description of project (by hovering over the info circle)
  • If project is currently blocked
  • Due date (if any)
  • Who project is assigned to

My Tasks

My Tasks

The My Tasks block alows the user to view two different collections of projects: Assigned to them, and Followed by them. Clicking on the task name will take them to the project detail page for that task. Each item contains a summarized version of the details of the task:

  • Task Name
  • Description of project (by hovering over the info circle)
  • Name of project this task belongs to
  • If task is currently blocked
  • Due date (if any)
  • Who project is assigned to

Email Notifications

Leaving Comments By Email

If you use either Mailgun or SendGrid then you can configure Rock to let you leave comments on a project simply by replying to the e-mail notification. The only configuration in Rock you need to do to support this is to ensure that your e-mail templates have the correct subject line (see templates below) and then to set a From Address for each template.

The From Address can be anything, but it must correlate to the address you setup in either Mailgun or SendGrid. So for example, if you setup Mailgun and use project-comment@mg.rocksolidchurchdemo.com as the e-mail address, then you will need to update the four out-of-the-box System Emails as well, as any custom system e-mails you setup, to use project-comment@mg.rocksolidchurchdemo.com as the From Address.

After ensuring the e-mails are being processed correctly, we recommend one final change to the e-mail templates. Telling users by word of mouth that they can reply to an e-mail and have the comment saved is all well and good, but wouldn't it be easier to just include that information in the e-mail itself? Out of the box, the e-mail templates contain this at the end of the messages:

<small><a href="{{ Project.Id | BBM_ProjectRoute }}">view it online</a>.</small>

We suggest changing it to the following to make it clear to the user they can just hit reply:

<small>Reply to this email directly or <a href="{{ Project.Id | BBM_ProjectRoute }}">view it online</a>.</small>

Mailgun

Mailgun allows you to configure individual e-mail addresses to be delivered to different API endpoints. You will need to configure a single e-mail address and have it deliver those to Rock. We suggest something simple, such as project-comment@mg.rocksolidchurchdemo.com, but you can use anything you want as long as it gets to Rock. The important part is the Subject line. When you configure the API endpoint you should enter the following (putting your Rock domain name instead):

https://rock.rocksolidchurchdemo.com/Webhooks/ProjectCommentMailgun.ashx

To configure Mailgun, go to your Routes menu and add a new route. Expression Type should be Match Recipient. Next put the e-mail address you want to use in the Recipient text box. Finally turn on the Forward action and enter the URL to the Rock Webhook (see above).

Mailgun Comment Config

SendGrid

SendGrid forwards all e-mails to a specific domain to a single API endpoint. This means you will need to configure a subdomain to use for project comments. For example, we would recommend that you use something like projects.rocksolidchurchdemo.com for the domain and then comment@projects.rocksolidchurchdemo.com for the actual e-mail address. The important tracking details are in the Subject line so you can use any e-mail address and domain name you want as long as it's configured correctly in SendGrid to send those to Rock. When you configure the API endpoint you should enter the following (putting your Rock domain name instead):

https://rock.rocksolidchurchdemo.com/Webhooks/ProjectCommentSendGrid.ashx

To configure SendGrid, go to your Settings > Inbound Parse and add a new entry. Select your verified domain name and enter the subdomain you want to use, then enter the URL to the Rock Webhook (see above).

SendGrid Comment Config
Remember you will need to setup your DNS to have MX records for the subdomain selected and point them to SendGrid.

Lava Fields

Out of the box, you are provided with a system e-mail for each of the four e-mail types below. Hopefully these will provide everything you need. The lava fields available in each e-mail are below.

Available to all e-mails:

"Project": {
    "Id": 3,
    "Name": "Light Switch Broken",
    "Description": "The plastic plate for the light switch has cracked.",
    "RequestDate": "2018-03-17 13:42:36",
    "RequestedByPersonAliasId": 7,
    "RequestedByPersonAlias": { ... },
    "ProjectTypeId": 2,
    "ProjectType": { ... },
    "ParentProjectId": null,
    "ParentProject": null,
    "DueDate": null,
    "CompletedDateTime": null,
    "CancelledDateTime": null,
    "BlockedDateTime": null,
    "CategoryId": 1,
    "Category": { ... },
    "Projects": [ ],
    "ParentProject": null,
    "Assignees": [ { ... } ], /* PersonAlias records */
    "BlockingProjects": [ ],
    "BlockedProjects": [ ],
    "Watchers": [ { ... } ],
    "Tasks": [ { ... } ],
    "IsBlocked": false,
    "IsActive": true,
    "ProjectAttributes": [
        {
            "Name": "test",
            "Key": "test",
            "RawValue": "Test value 1",
            "Value": "Test value 1",
            "IsEntryForm": true,
            "IsRequired": false,
            "Url": null
        },
        ...
    ]
},
"Person": { ... } /* The person object who is receiving the e-mail. */
"CurrentPerson": { ... } /* The person object who initiated this action, if known. */

Project Assigned

No extra fields.

Task Assigned

"Task": {
    "Id": 1,
    "Name": "Order New Plate",
    "Description: "",
    "ProjectId": 3,
    "Project": { ... },
    "AssignedToPersonAliasId": null,
    "AssignedToPersonAlias: null,
    "Order": 0,
    "DueDate": "2018-03-24 00:00:00",
    "CompletedDateTime": null,
    "CancelledDateTime": null,
    "BlockedDateTime": null,
    "BlockingTasks": [ ],
    "BlockedTasks": [ ],
    "IsBlocked": true,
    "IsActive": true
}

Project Comment

"Comment": {
    "Id", 1823,
    "NoteTypeId": 92,
    "NoteType": { ... },
    "EntityId": 3,
    "Text": "@Cindy Decker[15] can you check if this is a single or double wide plate?"
}
This e-mail type is also used when a project is first created if there was a mention to a person that would not otherwise receive an e-mail (such as project assigned). In these cases the Comment variable will be null.

Project Completed

No extra fields.

Templates

Occasionally the standard e-mail templates are updated. We will only modify them if you have not made changes yourself already. If you have made changes but want to incorporate the latest e-mail templates then you can find their contents below.

The subject for each template is as follows. There is some special syntax at the end which includes the Project Id and the Primary Alias Id of the person receiving the e-mail. This is required to support leaving comments by replying to a notification e-mail.

[Project] {{ Project.Name }} (#{{ Project.Id }}/{{ Person.PrimaryAliasId }})

Project Assigned

{{ 'Global' | Attribute:'EmailHeader' }}

<p>Hello {{ Person.NickName }},</p>

<p>
    The project <a href="{{ Project.Id | BBM_ProjectRoute }}">{{ Project.Name }}</a>
    was just assigned to you{% if CurrentPerson %} by {{ CurrentPerson.NickName }}{% endif %}.
</p>

<div>
    <strong>Details:</strong>
    <br />
    {{ Project.Description | BBM_FromProjectMarkdown }}
</div>

<hr />

{% for attribute in Project.ProjectAttributes %}
    {% if attribute.Value != '' %}
        <div>
            <strong>{{ attribute.Name }}:</strong><br />
            {% if attribute.Url and attribute.Url != '' %}
                <a href="{{ attribute.Url }}">{{ attribute.Value }}</a>
            {% else %}
                {{ attribute.Value | NewlineToBr }}
            {% endif %}
        </div><br />
    {% endif %}
{% endfor %}

<p>
    &mdash;<br />
    <small><a href="{{ Project.Id | BBM_ProjectRoute }}">view it online</a>.</small>
</p>

{{ 'Global' | Attribute:'EmailFooter' }}

Task Assigned

{{ 'Global' | Attribute:'EmailHeader' }}

<p>Hello {{ Person.NickName }},</p>
<p>
    The task <a href="{{ Project.Id | BBM_ProjectRoute }}">{{ Task.Name }}</a>
    was just assigned to you{% if CurrentPerson %} by {{ CurrentPerson.NickName }}{% endif %}.
</p>

{{ Task.Description | BBM_FromProjectMarkdown }}

<p>
    &mdash;<br />
    <small><a href="{{ Project.Id | BBM_ProjectRoute }}">view it online</a>.</small>
</p>

{{ 'Global' | Attribute:'EmailFooter' }}

Project Comment

{{ 'Global' | Attribute:'EmailHeader' }}

{% if Comment %}
    <p>New comment by @{{ Comment.CreatedByPersonAliasId | PersonByAliasId | Property:'FullName' }}:</p>
    <div>
        {{ Comment.Text | BBM_FromProjectMarkdown }}
    </div>
{% else %}
    <div>
        {{ Project.Description | BBM_FromProjectMarkdown }}
    </div>
{% endif %}

<p>
    &mdash;<br />
    <small><a href="{{ Project.Id | BBM_ProjectRoute }}">view it online</a>.</small>
</p>

{{ 'Global' | Attribute:'EmailFooter' }}

Project Completed

{{ 'Global' | Attribute:'EmailHeader' }}

<p>Hello {{ Person.NickName }},</p>
<p>
    The project <a href="{{ Project.Id | BBM_ProjectRoute }}">{{ Project.Name }}</a>
    has been completed {% if CurrentPerson %} by {{ CurrentPerson.NickName }}{% endif %}.
</p>

<p>
    &mdash;<br />
    <small><a href="{{ Project.Id | BBM_ProjectRoute }}">view it online</a>.</small>
</p>

{{ 'Global' | Attribute:'EmailFooter' }}

Working With Projects

Entering Projects

Project Entry

Once you click one of the buttons on the Tools > Project Entry page you will be on this page to actually enter a new project. If you compare this page to the Project Edit page we will talk about later, you can more readily see the fields that are hidden from the requester. Specifically, take note that earlier we had defined two attributes for this Maintenance Request project type. However, only the one flagged for "Entry Form" actually shows up on this page.

When entering a new project, the requesting user normally only gets to enter a Name for the project and a description of the project. Plus any attributes that were flagged as "Entry Form". This keeps the page very easy to understand for the user and allows them to quickly enter in new requests without having to wade through a cluttered screen.

Browsing Projects

You can browse projects in one of two ways. First, by using the "Projects" menu which presents projects in a manner similar to how Content Channels are organized and viewed. The second option is the way projects were viewed in version 1.x, which was via the category viewer.

The category viewer is the "Project Tree" page. It lets you view all the projects associated with a single category. That is the benefit it has. However, the downside is its a bit harder to quickly get an overall view of projects, what is assigned to you, etc.

The recommended way to view projects in version 2.0 is to use the new "Projects" page:

Projects View

If you are familiar with content channels, this will look very similar. But lets cover a few of the features real quick. First, because you are looking at a single project type at a time the Show on Grid flag of custom attributes is honored. This means you can see those attributes on the grid and even filter them.

The second major feature is the little buttons in the panel header. There are two sets. The first lets you switch between viewing All projects, just those Requested By Me (you), or those Assigned To Me (you). This provides quick filtering to see both the list of projects and the number of projects as these selection also change the bubble counts on the project type buttons.

The second grouping of buttons lets you switch between viewing Projects and viewing Tasks. Yep, you can quickly switch your bubble counts and grid list to show tasks instead of projects.

Viewing Projects

The project screen is broken up into different sections:

  • Project Details
  • Tasks
  • Sub Projects
  • Participants
  • Comments

Project Details

This section contains what you would expect, the general details of the project. We won't bore you with covering every item, but here is a quick overview of what each piece is for.

Project View Detail
  1. The title of the project.
  2. Identifier of the project. This can be used to reference the project when leaving comments.
  3. State of the project: Active, Cancelled, Completed.
  4. Watching project indicator. When highlighted you will receive e-mail notifications for this project.
  5. Follow project. You can flag a project so that it will show up in the followed section of the My Projects dashboard block.
  6. Contains the basic details of the project.
  7. Any custom attributes for the project will show up here.

Tasks

A project can contain any number of tasks, each of which can be individually assigned to a single person and have their own due dates. By doing this you can have a single project with a final due date and then smaller tasks with staged due dates. Additionally, you can mark one task as being blocked by another task. In this way you only need to worry about tasks that are ready to be worked on. An example of this would be one task to order parts followed by a second task to install the parts. The second task cannot be be started until the first has been completed. So the install parts task would be marked as blocked by the order parts task.

Tasks can be ordered one of two ways. The first and default ordering method is manually. You can drag the tasks into any order you wish. The second is to order the tasks by due date.

Project View Tasks
  1. Add a new task to this project.
  2. Configure task view options. This lets you change ordering options and show completed tasks.
  3. Complete a task. If checked this indicates that a task has been completed. Clicking on it will toggle the completed state.
  4. Follow task. When a solid icon then this task is being followed. Clicking on it will toggle the followed state.
  5. Edits the task.
  6. When manually ordering tasks, you can grab the hamburger icon and drag it to change the order.
  7. The caution icon indicates that the task is blocked by another task. Hovering over this icon will give a list of tasks that are currently blocking this task.
  8. Task Due Date. If the task has a due date then it will show here.
  9. If the task is assigned to a person, their name will show up here.

Sub Projects

A project can have any number of sub projects. When a task becomes too complex you may wish to convert it into a sub project so that it can have tasks of it's own. In this way you can manage extremely large and complex projects.

Project View Sub Projects
  1. Add a new sub project to the main project.
  2. View options to the sub project list. Currently allows viewing completed sub-projects.
  3. Title of sub project.
  4. The number of completed tasks and the total number of tasks in the sub project.
  5. The due date of the sub project.
  6. Indicates the sub project has a description, on mouse over shows a snippet of the description.
  7. Who the sub project is currently assigned to.

Participants

The list of participants simply shows everybody who has participated in the project. This is a summation of the requester, assigned persons and anybody who has commented on the project.

Project View Participants

Comments

A rich commenting and discussion system has been built into projects.

Project View Comments
  1. Each comment shows the picture and name of the person that left it. The date and time the comment was left is also shown above the text of the comment itself.
  2. Comments can contain rich text, including images and file attachments as seen here.
  3. Switch between editing the new comment and previewing what the comment will look like when saved.

As we just mentioned, comments can contain rich text. This is done using what is called Markdown Syntax. We chose markdown because of it's ease of use for simple formatting. When having a discussion of this nature usually the only formatting is bolding some text and maybe some bullet lists. But markdown does allow for some fancier editing that even a novice user can quickly learn. In addition, the editor has some buttons for some of the most common formatting choices.

While markdown has specific syntax for creating links to web pages, you do not need to strictly use this syntax. The markdown syntax allows for having custom text associated with the link. However, if you simply type in a URL it will be rendered as a clickable link.

The editor also supports uploading images and files as attachments. You can use either the upload button in the editor or simply drag a file into the editor to upload. Images are rendered inline and non-images are rendered as links to download the files.

Finally, the editor also supports mentioning other users. When you mention somebody who is not already receiving notifications for this project they will receive a special e-mail so that they can see they were mentioned. This allows you to bring people into the conversation without having to assign them to the project itself. To mention a person simply type the @ symbol followed by their name. You must enter at least 2 characters of both their first and last name to begin the matching.

Project View Comment Mention A Project View Comment Mention B

As you can see, you will get a small popup that will contain the full name found and their e-mail address (if available) to help identify the correct person. Once you accept the match it will replace the text you have already typed with their full name followed by a number in brackets. This number is their person alias identifier and is used to track specifically which person you mentioned.

You can also reference other projects by typing the # character followed by the project identifier.

Note: Everything we have discussed regarding the editor for comments also applies to the editor for project details.

Editing Projects

By clicking the Edit button on the project details page you can make changes to the project itself, including the internal fields.

Project Edit
  1. The top section allows for editing the normal information about a project. The things you would normally edit would be the Due Date and possibly the Name to make it more clear.
  2. Next comes the assignment and blocked by controls. These allow you to add or remove people to the list of those assigned to this project. The blocked by control allows you to add or remove other projects that are blocking this project from being worked on.
  3. Any attributes defined on the project type will show up here to be edited. Unlike the Project Entry screen, this screen allows you to edit all attributes.

When saving the project, any new assignees will automatically be e-mailed that they have been assigned to the project, assuming the e-mail template has been configured.

Security

Projects

The order of security authority is checked in the following order:

  1. The project itself (not yet implemented).
  2. The parent project.
  3. The project type of the top-most project in the inheritence tree.

Additionally, a "pre-check" is done on the project type first to ensure they can view the project type. Consider this example. You have Project A of type General Projects. General Projects can be viewed by all staff. You have a sub-project setup of this project as Project B, and it is of type "Pastoral Visit". Pastoral Visit projects can only be viewed by pastors. If Ted is both a staff member and a pastor, he can view both projects. If Cindy is a staff member but not a pastor then she can only view "Project A".

Tasks

Tasks inherit their security from the project they are a part of. They also follow the same pattern of doing a pre-check on the project type of the project they are associated with.

Workflow Actions

A rich set of workflow actions are available for working with projects. By using the various actions you should be able to create, assign and complete projects and tasks. This allows automated project creation via methods such as text messages, person profile actions as well as many other possibilities.

The following actions are installed along with the project management system:

  • Create Project
  • Create Task
  • Assign Project
  • Assign Task
  • Add Project Comment
  • Set Project State
  • Set Task State
  • Follow Project
  • Follow Task
  • Watch Project

Upgrading

Version 2.0

The major change this version is in how you browse projects. The existing Tools > Projects page was renamed to Tools > Project Tree. A new page was added to take it's place that provides a, we hope, more unified and Rock-like view of your projects. Because your users may not know how to immedietly find their existing projects you may want to be sure they know they can go to the Tools > Project Tree page to find them until they are used to the new look.

Version 1.6

Nothing you need to worry about.

Version 1.5

  • Version 1.5 added a couple new features to the e-mail system. E-mails can now include the attributes of the project (similar functionality to how Workflow Notification e-mails work) and have had the templates updated. You may want to check your own System Email templates against the stock templates to be sure you are using the latest version.
  • Support for allowing users to reply to an e-mail to leave a comment on the project has been added. This requires some configuration to enable so be sure to check out the configuration section on that.