Skip to content

Home

Jump to bottom
vhouchouas edited this page Mar 24, 2022 · 9 revisions

Setup your hosting

You need a PHP web hosting which has php-curl and runs PHP 7.3 or a more recent version. We will assume that your domain name is www.server.com. It is mandatory that your web hosting supports HTTPS.

On your file system, download the app files:

    curl -L https://github.com/Zero-Waste-Paris/slack-agenda-app/zipball/main > slack-agenda-app.zip
    unzip slack-agenda-app.zip
    rm slack-agenda-app.zip
    cd Zero-Waste-Paris-slack-agenda-app-*
    composer install --no-dev

Your web hosting has to serve the directory Zero-Waste-Paris-slack-agenda-app-*. It has to be writable as logs will be also stored in that directory.

If you visit https://www.server.com/.../events.php you should get a blank page, and a log file should have appeared on the filesystem. Its content will be like:

cat app-2022-03-22.log
[2022-03-22T22:29:41.096301+00:00] ConfigReader.ERROR: config.json not found [] []

Create your Slack App

First, we recommend you to create a slack user to install your App. Indeed, the App will send reminders to your slack community through the user that has installed the App. It is better to have a dedicated user for that.

Login from this new user, go to https://api.slack.com/apps, click Create New App and select From an app manifest. Copy the content of the file slack_app_manifest.yaml.sample available here, and paste it on the form displayed on the slack interface. Replace the endpoints:

  • https://www.server.com/events.php,
  • https://www.server.com/commands.php,
  • https://www.server.com/actions.php

with your own and pursue the app creation procedure.

Setup config.json

On your web hosting, copy the config file template like:

cp config.json.sample config.json

... Slack App part

We will now populate the fields slack_signing_secret, slack_bot_token and slack_user_token of this file:

You can run:

./clitools config-read

To check that the file is well formated, and run:

./clitools api-checktokens
[2022-03-22T23:24:53.584357+00:00] CLITOOLS.INFO: Checking Slack user token... [] []
[2022-03-22T23:24:53.758987+00:00] CLITOOLS.INFO: Checking Slack user token - ok. [] []
[2022-03-22T23:24:53.759163+00:00] CLITOOLS.INFO: Checking Slack bot token... [] []
[2022-03-22T23:24:53.927947+00:00] CLITOOLS.INFO: Checking Slack bot token - ok. [] []

To check that tokens are well configured.

Go to the tab Event Subscriptions of the Slack app dashboard, check that slack can reach https://www.server.com/events.php by clicking on retry. It will guarantee that Slack is able to reach the App.

... CalDAV part

We will now populate the fields caldav_username, caldav_password and caldav_url of the file config.json.

Check that credentials are corrects by executing:

./clitools api-checktokens
[2022-03-22T23:38:26.832412+00:00] CLITOOLS.INFO: Checking CalDAV client credentials... [] []
[2022-03-22T23:38:27.344373+00:00] CLITOOLS.INFO: Checking CalDAV client credentials - ok. [] []

If you use

  • owncloud/nextcloud, caldav_url will be like something like https://www.caldavserver.com/remote.php/dav/calendars/username/calendarname;
  • Google calendar, you will need to create an App password. caldav_url will be like https://www.google.com/calendar/dav/[email protected]/events.

... Back-end part

Events will be stored on either a MySQL or SQLite back-end. For performance reasons, we recommend to use the MySQL one.

MySQL

Fill the agenda key of config.json like:

    "agenda" : {
        "db_type" : "MySQL",
        "db_host" : "localhost",
        "db_name" : "slack_app",
        "db_username" : "slack_app_user",
        "db_password" : "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "db_table_prefix": "slack_app_"
    },

You can test that the App is able to reach the MySQL server by running:

./clitools database-checkconnection
[2022-03-23T00:03:29.412473+00:00] CLITOOLS.INFO: Checking database connection...  [] []
[2022-03-23T00:03:29.414320+00:00] CLITOOLS.INFO: Checking database connection - ok. [] []

SQLite

Fill the agenda key of config.json like:

    "agenda" : {
        "db_type" : "sqlite",
        "path" : "/.../.../database.sqlite",
        "db_table_prefix": "slack_app_"
    },

Create tables

Once config.json is configured, you can create the SQL tables:

./clitools database-create
[2022-03-23T00:05:00.504370+00:00] MySQLAgenda.INFO: Create database tables... [] []
[2022-03-23T00:05:00.540826+00:00] MySQLAgenda.INFO: Create database tables - done. [] []

Fetch events

Once everything is configured, you can fetch events from the CalDAV server by running:

./clitools checkAgenda
[2022-03-23T00:05:20.365671+00:00] CLITOOLS.INFO: Checking Agenda...  [] []
[2022-03-23T00:05:21.256754+00:00] MySQLAgenda.DEBUG: local CTag is NULL, remote CTag is http://sabre.io/ns/sync/1094 [] []
[2022-03-23T00:05:21.257030+00:00] MySQLAgenda.DEBUG: Agenda update needed [] []
.
.
.
[2022-03-23T00:05:22.273525+00:00] CLITOOLS.INFO: Checking Agenda - done [] []

Optionals fields

  • prepend_block: fill this key if you want to add static information at the top of the App Home Page. It has to be a json formatted Slack Block. You can make use of the Slack block kit builder;An example of Slack Block is:

     "prepend_block" : {
     "type": "section",
     "text": {
         "type": "mrkdwn",
         "text": "*I will be displayed at the top of the app page in bold !.*"
     }
 }

  • prepend_block: fill this key if you want to add static information at the bottom of the App Home Page;

  • empty_agenda_block: fill this key if you want to add static information that there is no event on the agenda;

  • no_event_block: fill this key if you want to add static information that no event match the filters;

  • error_mail_from and error_mail_to are used to send mail when errors occur. See the monolog PHP logger;

  • logger_level, must be one of these.

The field categories may be used to replace a category name (in the event description), by an emoji. For example:

  "categories": [
    {
      "name": "Urgent",
      "emoji": ":warning:"
    }
  ]
Clone this wiki locally