pco – TechMinistry

Building a digital roster/serving board using Companion and the Planning Center Services API

If you’re involved in tech ministry and like to tinker, chances are you’ve heard of — and maybe even used — micboard.io.

Straight from their website, “Micboard simplifies microphone monitoring and storage for artists, engineers, and volunteers. View battery, audio, and RF levels from any device on the network.” It’s a neat tool and has helped a lot of teams over the years.

I always liked the idea of Micboard because it would be a great way to show who is serving that day. We tried to implement it at my church but eventually moved away from it, mainly because it hadn’t been updated in quite a while (over 6 years now), and we needed some additional features. Specifically, we were looking for integration with Planning Center Services — something that could automatically pull assignments from an interface our team was already familiar with. And – something we could use for more than just people on stage.

At first, I forked the Micboard repo (since it’s open-source) and started making improvements, cleaning up some code, and tweaking it to run more easily on modern MacOS systems. But pretty quickly, I realized I had too much on my plate to maintain a whole fork long-term.

Fast forward a year or so. I came across a few posts on some Facebook groups that I was in where people were using my ScreenDeck project to essentially create a Micboard style interface using Companion.

What I loved about this approach is that it leveraged something we were already using — Companion — and could still be viewed from anywhere on the network, just like Micboard. Plus, Companion supports a lot more devices beyond just Shure systems.

Even better, this opened the door to that Planning Center integration I had wanted without introducing a bunch of extra overhead — we were already using the PCO module to control our LIVE service plans!

One thing I’ve wanted for a while was a digital roster — something simple to show who’s serving each day, helping everyone put names to faces across band, tech, safety, and more. A “Serving Board,” if you will.

About a year ago, I had modified the PCO module to pull scheduled people into variables — showing their names and assigned roles. I recently took it further by adding a feedback: “Show Person Photo based on Position Name.”

Now, the module pulls the photo from the person’s assignment, converts it into a PNG, and stores it internally as a base64 image — which can be shown directly on a button.

Pretty cool – and it looks like this:

But I didn’t want to stop there — I wanted the person’s status (Confirmed, Unconfirmed, or Declined in PCO) to show too.

Using the companion-module-utils library (thanks to another awesome Companion dev!), I added a simple colored border overlay for statuses.

A few extra lines of code later:

And you can get this look!

At this point, it was looking great — but I started thinking:

What if I don’t want to redo all my buttons every week? What if my teams and roles change?

So I added a new option: a generic “position number” approach.

You can now pick a position number in the plan (or within a specific team) — and the module will automatically pull the right person’s info, week to week, without you having to manually reconfigure anything.

For example:

• Pick any number across the entire plan.

• Or pick a number within a specific team, like Band or Tech.

With this option, you can choose any number, regardless of the team.

This picks the first person scheduled in the band.

I also built some Module Presets to make setting this up super easy:

• Generic Position Number (no specific team)

• Position Number Within a Team (like “Band” only)

In this example, you can choose a number within the Band team.

And here’s where it all comes together:

Let’s say you have a “Wireless Assignments” team in PCO, and you assign a person to a position called “Wireless 4.”

Now, using the Shure Wireless module in Companion, you can match that name and see live RF and battery stats for Wireless 4 — tied directly to the person assigned!

All together, you get a clean, dynamic, reusable Micboard-style dashboard — all inside Companion, no extra tools required.

Here’s a walk through video showing it all in action:

The updated PCO Services Live module is available now in the Companion betas — go check it out if you want to try it!

Controlling Planning Center LIVE with a streamdeck, with timers and other variables

If you use Companion and are in tech ministry, you have probably used my PCO Services LIVE module. While in the process of converting this module to the new API we are using for Companion 3.0, I gave it an overhaul and added lots of new features!

Here is a video that shows how it works:

Go check it out for yourself!

A new Planning Center Online Services Custom Report, supporting Split Teams

One of the first blog posts here was about PCO’s custom reports. I’ve written a lot of them and helped a lot of churches get started with their own.

In anticipation of a possible need for split teams, I’ve now created a new custom report that has several customizable features, enhanced checklists, dynamic notes, and more, without having to write any actual code. Just modifying variables at the top of the report.

This new report supports the following:

Customizable header
Custom print order, with variable plan items as columns and/or rows alongside the plan item description
Dynamic checklists
Automatic highlighting of Plan Item Note changes to signify important information
Ability to display Plan Notes for everyone, by team, or by position
Custom CSS for your own unique look
Ability to show headers in their own row, or inline to save space

Here’s the report with Headers as their own rows.

Here’s the exact same report, but with headers inline for a cleaner look.

Here’s a video that shows how it all works:

Because of the substantial amount of work I have put into creating and coding this report, I have chosen to make this report available for purchase. I’m pricing it at a point that is affordable for most churches, at $45. Once payment is received, I will send over the report code and help you install it, if needed.

PCO Services Matrix Report with Split Teams, Fully Customizable

This custom report will revolutionize the way you share information with your team! Report code will be sent to the email address provided once payment is received.

$45.00

Click here to purchase.

If you have a need for a custom report beyond this, contact me! I’m always available for hire for your custom PCO reporting projects, or whatever other custom coding needs your ministry or organization may have.

Custom Reports in Planning Center Online, Part 2

At my church, we have two venues where we run worship services simultaneously. This means that when I am running reports and printing paperwork for all the teams, there’s a lot to print! Using the PCO custom reporting tool is great because it saves so much time.

If you didn’t read Part 1 where I first talked about this, hop on over and check that out.

Lately, rather than printing reports one at a time with each plan, I’ve been using the matrix view in Planning Center to view multiple plans at once and print reports all at the same time.

Screen Shot 2019-09-26 at 9.26.05 AM — The matrix view in PCO is very powerful and helps when you want to look at several plans at once.

My custom matrix report is similar to the normal plan report, but this one supports multiple plans, obviously. It loops through every plan, and then every position in the plan (based on the teams I have chosen), and then generates a sheet for that position, customized with their checklists, notes, etc.

My most recent edit includes a custom array for sort order, because the default is to print the position reports alphabetically. Rather than rename my positions, I opted for the custom sort.

Screen Shot 2019-09-26 at 9.26.49 AM.png — The print order array can be customized so that reports are sorted in the order you want.

This saves time every week because now they print out in the order I need to pass them out!

If you’d like to get a copy of this custom report, head on over to the GitHub repository I set up for it: https://github.com/josephdadams/PlanningCenterServicesReports

Controlling Planning Center LIVE with a Stream Deck

In my last post, I mentioned a great tool, Companion, that integrates with the Elgato Stream Deck. I’ve had the opportunity to write a few modules for it to extend its control capabilities, like controlling a CueServer, or my own software, ProTally.

If you work in tech for a church, chances are that you use or have at least heard of Planning Center Online to manage your worship services and people. PCO has a feature for their Services product called Services LIVE that allows you to designate where you are at in a service flow while a service is ongoing, which updates anyone who may be watching. It also records the times so you can look back later and see things like “Did that song we said would take 5 minutes actually take more like 6 minutes and 30 seconds?” It’s a very useful tool.

The interface to advance a LIVE plan, however, has not been the best for our volunteers. Even within the PCO app, the buttons to advance a plan to the next item are rather tiny, and some of my team have trouble knowing whether or not they hit the button.

This is the standard PCO Live interface. The small double arrows at the bottom left and right of the screen are the controls. Our volunteers have a hard time pressing these.

One thing that makes Planning Center Online great is that they love developers, and they’ve made a very extensive Application Programming Interface (API) available for anyone to use. This means you can get access to your service and plan data without having to actually click and browse the website.

I delved into that API this past week and used it to create a new module for Companion. One of the caveats of using the API is that in order to advance a live plan, you have to know both the service type ID and the plan ID. This requires traversing the API data some and making multiple requests. If you’re a programmer, this makes sense. If you’re just an end-user, it may not be as straightforward. So, I set out to make something easy enough for anyone to use.

Here is a walkthrough video on how the module works:

[wpvideo hyQpcLnH]

What it actually does:

When you first load the module and supply it with the authentication tokens, it requests all of the available service types and stores that internally.
```
https://api.planningcenteronline.com/services/v2/service_types
```
Then it asks for the next 7 upcoming plans for each service type based on the list that was just retrieved. This is then used to build the drop down list so you can choose your plan.
```
https://api.planningcenteronline.com/services/v2/service_types/${serviceTypeId}/plans?filter=future&per_page=7
```
When you send a “Previous” or “Next” command, it first asks for the LIVE information for that selected plan.
```
https://api.planningcenteronline.com/services/v2/service_types/${serviceTypeId}/plans/${planId}/live
```
It checks for who the current controller of the plan is, and compares that to an internal variable in Companion that represents the owner of the authentication token.
If the current controller is null, a command is sent to toggle control to the token owner, and the returning value of the current controller is stored in that internal variable so we know who “we” are for next time.
```
https://api.planningcenteronline.com/services/v2/service_types/${serviceTypeId}/plans/${planId}/live/toggle_control
```
If the current controller is not null, a toggle command is sent to release control of the plan to no one, and then a toggle command is immediately sent again so that control is toggled to us. The reason for this is that if our authentication key is not the current controller, the API will return an error when we try to advance the plan.
Now that we know we are in control, the current controller value returned by the API is stored as an internal variable, and then the next or previous command is sent to advance the plan.
```
https://api.planningcenteronline.com/services/v2/service_types/${serviceTypeId}/plans/${planId}/live/go_to_next_item
```

Because Node.js is an asychronous programming language, all of this is done through Promises, which is similar in concept to a callback function, however it allows for cleaner and easier to read code.

So, stay tuned for this module to become available in the next stable release of Companion, and if you’re willing to try it out in development mode, it’s available now!

Custom Reports in Planning Center Online

If you work or serve in a church, chances are you use Planning Center Online a lot. We use their Services product to plan and organize our weekend services, schedule volunteers, etc.

Even though they have a mobile app and desktop interface, we still rely on printed reports on the weekend. It’s simple, fast, we don’t have to worry about the internet going down, the team members can write all over them, etc.

Out of the box, Planning Center comes with some great reports that you can print out. They can somewhat tailored to your organization with your church’s name or logo, etc.

Screen Shot 2018-05-02 at 8.33.53 AM — Here’s an out of the box standard report. It gets the job done but it could be better.

In addition to their standard reports, they also support custom reporting. If you know a little HTML, CSS, and are ready to learn some custom tags, it’s pretty easy to jump right in.

Screen Shot 2018-05-02 at 9.29.14 AM — Here is a screenshot of a custom report. You can see the HTML and CSS, along with the custom tags that help to generate the report. You can see that some variables have been created and are then referred to later in the document.

The reporting language that PCO uses is called Liquid. If you want a good resource to read that is outside of what PCO offers, here is one.

Liquid is an open source templating language that allows you to do simple conditional and iteration along with filters to parse and control the page as it loads. What this means for you as a user is that you have a lot of simple power at your fingertips to create custom reports designed for exactly what you need!

So, with these tools, I have created several custom reports that our teams use when it is time to print out paperwork for weekend services.

The report I use most often is for our tech team. It prints out a customized version for every person serving on the team that weekend, with their name, the general service flow, and information just for their position, notes, checklists, etc.

Screen Shot 2018-05-02 at 8.35.16 AM — Here is an example page from the report. Every team member gets a page (or pages as needed) with their name and customized information for their position.

The nice thing about this report is that I only have to run it once and print once. It creates a new page for every person on the team, so I don’t have to remember how many copies I need to print – I just print the whole file and it has exactly what each person/position needs!

This report includes custom plan item notes per position. To add those, just add a plan item with an item note named:

Position Name

The name has to match exactly. The report also includes overall plan notes per position. To add those, just add plan notes like this:

Team Name – Position Name

When you add your plan notes or plan item notes, just type something specific in that field and only that position will see it when it prints. We like this a lot on our teams because it keeps the report looking a lot simpler for those who don’t need all the extra detail.

One thing you may not have noticed is that I include checklists, customized for each position on the team. We have found checklists to be very helpful so we don’t miss any of the mundane stuff, especially when volunteers may only be serving once a month.

If you use my custom report file, all of the checklist code is already created for you. You just need to create the Plan Note fields to correspond with each position. Each position that has a checklist item should have a Plan Note Field like this:

Checklist – Team Name – Position Name

Any item in the list that begins with a “*” (asterisk) will be printed in a “DURING REHEARSAL” section, and only printed once. Any item that begins with a “~” (tilde) will be printed in an “AFTER EACH SERVICE” section for each service time and will include a small blank line for notes. Any other item will be printed in a “BEFORE SERVICE” section and will be printed once for each service time.

So, for example, a plan note in the field “Checklist – Tech Team – Stage Manager”:

*Take out trash

This would only print one time in the checklist, in the “During Rehearsal” section. You can edit the report to rename that header if you’d like.

~Shut all doors

This would print multiple times, once for each service time, in the “After Each Service” section.

Check for presentation

This would print multiple times, once for each service time, in the “Before Each Service” section. This is likely going to be the most-used field, so it is the one with the simplest formatting requirements.

I like to keep all of my checklists in a Template Plan (with no other items or people) within PCO, and just import them each week to the plan before printing. This allows me to update the checklists from time to time without hardcoding it into the report file, and I can customize it per-plan if needed.

I hope this is helpful to you! You can download all of my custom reports here: https://github.com/josephdadams/PlanningCenterServicesReports/