PCO Bot is a bot that integrates with the Planning Center Online API.
PCO Bot is a hobby project. It is not affiliated with the awesome team at Planning Center Online, but they think it's super cool!
It is intended for use with Slack, and it is built upon an extensible and modular framework.
All commands are restricted by planning center App access. When you run a command it will look up your Planning Center permissions. If you have access to that app the command will work.
... !apps *[App Name]*If no app name is provided it will list all the apps you can access.
I need the | Do you know the | Do you have a | Can somebody tell me the...
- 🔒
... number for *[Any Name]* - 🔒
... birthday for *[Any Name]* - 🔒
... email address for *[Any Name]* - 🔒
... address for *[Any Name]*
When was the last time *[Any Name]* was here?Was *[Any Name]* here Sunday?
Show the set list for *[Any future service date]*Show the set list for *[Any future service date]*What is the arrangement for [Any Song]?
This isn't really used in the pcobot but it is used for Will bot commands
- 🔒
!acl(Displays the current access lists.)
To change the access control list, see configuration instructions below and this enhancement
Make a list of your environment variables.
| Env Var | Value | Example |
|---|---|---|
| WILL_PCO_API_SECRET | GET PCO PERSONAL KEY* | AJS7F7ZIJ2... |
| WILL_PCO_APPLICATION_KEY | GET PCO PERSONAL KEY* | X0579RTGV7... |
| WILL_SLACK_API_TOKEN | GET SLACK API TOKEN | xoxb-X3WTL... |
| WILL_SECRET_KEY | Make your own | - |
| WILL_SLACK_DEFAULT_CHANNEL | bot | bot |
| Env Var | Value | Example |
|---|---|---|
| WILL_PUBLIC_URL | The URL of your Heroku App | http://your-app-name.herokuapp.com |
| TZ | IANA tz code | America/Los_Angeles |
Note: The user who owns the PCO Personal Access Key must have permissions to access to all the apps you want the bot to access. You'll also need to ensure that your church has signed up to the People app. (It's free with any other app!) You can use the Personal access key from one of your PCO Organization Administrators, or you may even choose to create a dedicated user just for this bot.
- Fork this repository.
- Get a Heroku account.
- Add a redis add-on from Elements. (e.g. Redis Cloud will work automatically) Note: You will need to verify your account with a credit card even to install a free add-on.
- Enter your config/environment variables on the settings page of your app. (http://dashboard.heroku.com/apps/your_app/settings)
- Choose github as your deployment method in heroku and connect to your fork of pcobot.
- Deploy the master branch.
(example code assumes Debian - including Ubuntu, Mint, KNOPPIX, Raspbian)
Note: If deploying on Rasbian Jessie (Raspberry Pi), you will need to ensure you build your virtual environment with Python3, and you may need to pip install redis-server as well.
- Install virtualenv
pip install virtualenv. - Clone this repository
git clone https://github.com/pastorhudson/pcobot.git - Change to pcobot directory.
cd pcobot - Setup the pcobot folder as a virtualenv using the following command.
virtualenv .(Important: the.references the current folder) - Activate your virtual environment.
source bin/activate. (The name of the current virtual environment will now appear on the left of the prompt to let you know that it’s active. From now on, any package that you install using pip will be installed to the virtual environment, isolated from the global Python installation.) - Get the requirements.
pip install -r requirements.txt - Add your API Keys and environment variables in the start.sh file. This file is just for setting environment variables and executing as sudo user. (Sudo is needed to open port 80.)
- Do
chmod +x ./start.shto make your startup executable. Then run./start.sh
Find more install help here: http://skoczen.github.io/will/
Invite your bot to the #bot and #general channels, and any other channels you'd like. Make sure it has permissions to post. If a channel is restricted to Workspace Owners and Workspace Admins, the bot will not be able to post.
This channel is where webhook announcements will be posted. It can be changed by editing the relevant environment variable. Example webhooks:
####.herokuapp.com/ping "Someone pinged me!"
####.herokuapp.com/say/Cogito Ergo Sum "Cogito Ergo Sum"
This channel is where scheduled announcements will be posted. Optionally, the channel can be configured per announcement in plugins/pco/announcements.py. You'll need to invite the bot to any channel you want it to post.
Most user permissions are inherited directly from Planning Center Online. However, a very limited number of commands are limited to people in the pcobot botadmin group.
In your config.py file you'll find an ACL section. Add the slack handles to this acl list. You can add any other acl groups you'd like. Each entry must be in lower case!
# Access Control: Specify groups of users to be used in the acl=["botadmin"] parameter
# in respond_to and hear actions.
# Group names can be any string, and the list is composed of user handles.
ACL = {
"botadmin": ["johnell", "leigh", "pastorjoe","pastorhudson"]
}
We'd love to have your help building PCO Bot. If there's something you want to add:
- Look to see if your feature is already an issue.
- If it is not then make it an issue and submit it. Ideally, you can take ownership of it and comment that you're working on it!
- Make sure it is clear whether this issue is an Enhancement or Bug and which PCO product(s) it applies to. (People, Services, Check-in, Resources, etc.)
- See the guidelines in CONTRIBUTING.MD, write awesome code, and submit a pull request!
The first version of Will was built by Steven Skoczen while in the Greenkahuna Skunkworks (now defunct), was extended by Ink and Feet and has been contributed to by lots of awesome people.
Will has docs, including a quickstart and lots of screenshots at: http://skoczen.github.io/will/
Pypco is an object-oriented, Pythonic library built by Bill Deitrick.