search

pastorhudson / pcobot

PCO Bot is a bot that integrates with the Planning Center Online API. It's built on Will Bot.
MIT License
14 stars 12 forks source link
church-management

readme

Build Status

PCO Bot:

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.

Accounts you will / may need:

Usage

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.

Check your permissions

People

I need the | Do you know the | Do you have a | Can somebody tell me the...

Check-ins (Attendance)

Services (Plans)

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.

Access Control Lists

This isn't really used in the pcobot but it is used for Will bot commands

To change the access control list, see configuration instructions below and this enhancement

Before You Install

  1. Create a #bot and # general channel.

  2. Verify Slack account(s) Profile Names Slack accounts should match name / email of your PCO users accounts.

  3. Create a Slack Bot and generate an API Token *Keep this Token handy, you'll need it when installing your app.

  4. 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.

  5. Make a list of your environment variables listed below.

All Installs

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

Heroku-Only

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.

Installation

Install on Heroku

Click the button!

Deploy

If everything goes well, you will have your own instance of pcobot running.

Update existing One-Click Heroku Deployment

Prepare for updates:

Create local repo pointing to the Heroku remote

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.

Attach the GitHub repository of pcobot as a new remote

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

Install on Linux

(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.

  1. Install virtualenv pip install virtualenv.
  2. Clone this repository git clone https://github.com/pastorhudson/pcobot.git
  3. Change to pcobot directory. cd pcobot
  4. Setup the pcobot folder as a virtualenv using the following command. virtualenv . (Important: the . references the current folder)
  5. 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.)
  6. Get the requirements. pip install -r requirements.txt
  7. 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.)
  8. Do chmod +x ./start.sh to make your startup executable. Then run ./start.sh

Find more install help here: http://skoczen.github.io/will/

Configuration

Slack Channels

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.

announcements

This channel is where scheduled announcements will be posted. You can change this using the !achannel command.

WebHooks

Some announcements like "New Person Created" need to have Planning Center webhooks configured.

Current webhooks PCObot will need:

Create the webhook:

Bot Admins

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"]
}

Contribute!

We'd love to have your help building PCO Bot. If there's something you want to add:

  1. Look to see if your feature is already an issue.
  2. 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!
  3. 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.)
  4. See the guidelines in CONTRIBUTING.MD, write awesome code, and submit a pull request!

PCO Bot is built on Will Bot and PyPCO

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.

PCO-BOT - Development instructions

Setup your Dev environment:

Using Docker Exclusively

Docker / Local Hybrid

Final Instructions