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]?
Who is *[serving|scheduled]* *[on|for]* the *[Any Services team]* team *[Any future day/date/time]*?
[!serving|!scheduled] *[Any Services team]* *[Any future day/date/time]*
!serving 'Downtown Band' Sunday
!notify-team *[Any Services team]* in channel [channel name]
!team-notifications
!remove-notification *[Services team set up with notifications]*
If you specify a time, it will try to find the team for that precise service time—if you do not, it will simply try to match the team for the day provided.
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
Create a #bot and # general channel.
Verify Slack account(s) Profile Names Slack accounts should match name / email of your PCO users accounts.
Create a Slack Bot and generate an API Token *Keep this Token handy, you'll need it when installing your app.
Create API Keys for PCO To Create an PCO API Key, log on here. Click on ‘Create Personal Access Token’ Create a Name for the Token, i.e. PCO Slack Bot, etc. *Keep these tokens handy; you will need the PCO API Token and Secret key for your environment variables.
Make a list of your environment variables listed below.
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.
Click the button!
If everything goes well, you will have your own instance of pcobot running.
Prepare for updates:
heroku git:clone --app YOUR_HEROKU_APPNAME && cd YOUR_HEROKU_APPNAME
It may tell you that you've cloned an empty repository. That is fine.
git remote add origin https://github.com/pastorhudson/pcobot
From now on you can simply update your Heroku instance by running:
cd YOUR_HEROKU_APPNAME
git pull origin master # pull down the latest version from GitHub
git push heroku master # push all updates back to your Heroku app instance
(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.
pip install virtualenv
.git clone https://github.com/pastorhudson/pcobot.git
cd pcobot
virtualenv .
(Important: the .
references the current folder)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.)pip install -r requirements.txt
chmod +x ./start.sh
to make your startup executable.
Then run ./start.sh
Find more install help here: http://skoczen.github.io/will/
Invite your bot to the #announcements 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 scheduled announcements will be posted. You can change this using the !achannel command.
:lock:!achannel
Responds with the current announcement channel
:lock:!achannel [any channel]
Sets the announcement channel for all announcements.
You'll need to invite the bot to any channel you want it to post.
:lock:!toggle
Responds with a list of the current announcement toggles.
:lock:!toggle <announcement name>
Turns announcements on and off.
:lock:!twipe
Clears and revitalizes the announcement toggles. Use this after you upgrade if you are missing new toggles.
Some announcements like "New Person Created" need to have Planning Center webhooks configured.
Current webhooks PCObot will need:
https://<your-app-name>.herokuapp.com/pco/webhook
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:
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.
sudo apt-get install docker-ce docker-compose
should work.pcobot/docker-dev
folder.docker-compose up
to start pcobot!python -m venv .
source bin/activate
pip install -r requirements.txt
apt install build-essential python-dev libxml2-dev libxslt1-dev zlib1g-dev
docker-dev
folder there is a redis-only
folder.docker-compose up
and that
will run redis in a container ready to accept connections on localhost:6379start.sh
in the pcobot folder.
chmod +x ./start.sh
./start.sh
it should run. If not then work through the errors.