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.

IMG_9032
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:

What it actually does:

  1. 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
  2. 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
  3. 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
  4. 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.
  5. 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
  6. 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.
  7. 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!

IMG_9035
The PCO Live module in action!

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/