ftw.slacker 1.1.0

Introduction

The ftw.slacker is a Plone addon that provides an easy to use api to post messages into a Slack channel through Slack’s webhooks api.

For more information about slack webhooks see Slack’s documentation about Incoming Webhooks

Installation

Add the package as dependency to your setup.py:

setup(
      # ...
      install_requires=[
        'ftw.slacker',
      ])

or to your buildout configuration:

[instance]
eggs += ftw.slacker

and run buildout

bin/buildout

Usage

from ftw.slacker import notify_slack

notify_slack('https://hooks.slack.com/services/xxx',
             text="my first post")

from ftw.slacker import notify_slack

notify_slack(webhook_url='https://hooks.slack.com/services/xxx',
             timemout=10,
             verify=False,
             text="my first post")

from ftw.slacker import notify_slack

notify_slack('https://hooks.slack.com/services/xxx',
             text="my first post",
             attachments=[
                 {
                     "title": "Slack API Documentation",
                     "title_link": "https://api.slack.com/",
                     "text": "Optional text that appears within the attachment"
                 }
             ])

Webhook URL by environment variables

Normally you don’t want to store your webhook-url in your application code.

ftw.slacker supports configuration through environment-variables:

Set your environment variable:

export STANDARD_SLACK_WEBHOOK='https://hooks.slack.com/services/xxx'

or through buildout:

[instance]
environment-vars +=
    STANDARD_SLACK_WEBHOOK https://hooks.slack.com/services/xxx

and call the api-function without webhook_url parameter:

from ftw.slacker import notify_slack

notify_slack(text="my first post")

export STANDARD_SLACK_WEBHOOK='https://hooks.slack.com/services/default-channel-id'

from ftw.slacker import notify_slack

# Post message to service default-channel-id
notify_slack(text="my first post")

# Post message to service specific-channel-id
notify_slack('https://hooks.slack.com/services/specific-channel-id',
             text="my first post")

Deactivate Slack notification

Let’s imagine, you have a server with multiple deployments and all deployments should push to the same Slack webhook.

You can either configure the standard slack webhook envoronment variable through buildout for each deployment, or you just define the default webhook url once in your server environment:

export STANDARD_SLACK_WEBHOOK='https://hooks.slack.com/services/xxx'

Each application will post messages to this slack webhook.

[instance]
environment-vars +=
    DEACTIVATE_SLACK_NOTIFICATION deactivate

export STANDARD_SLACK_WEBHOOK='https://hooks.slack.com/services/xxx'
export DEACTIVATE_SLACK_NOTIFICATION deactivate

[instance]
environment-vars +=
    DEACTIVATE_SLACK_NOTIFICATION

Advance usage

Perhaps you’ve got different external modules using the ftw.slacker implementation and all of this modules providing a different default slack webhook url.

Let’s imagine, we have a module calling ftw.logger which logs all userlogins within your plonesite to a slack-channel.

It provides an additional environment variable called FTW_LOGGER_SLACK_WEBHOOK to post the logging-activities to a separate channel. So the implementation of this module may look like this:

from ftw.slacker import notify_slack
import os

def notify_user_login(user):
    notify_slack(os.environ.get('FTW_LOGGER_SLACK_WEBHOOK'),
                 text='User {} logged in'.format(user.username))

If you don’t set the FTW_LOGGER_SLACK_WEBHOOK variable, ftw.slacker will post the user login to the default channel. If you set FTW_LOGGER_SLACK_WEBHOOK, ftw.slacker will use this more specific channel for notifications.

Deactivating the whole notification system through the DEACTIVATE_SLACK_NOTIFICATION environment variable is not desired, because you still want to post other notifications, i.e. from your application which uses the standard slack webhook url.

For this puropose, you can just deactivate this specific notification branch by setting the environment variable FTW_LOGGER_SLACK_WEBHOOK to deactivate (see the static variable NOTIFICATION_DEACTIVATION_VALUE).

[instance]
environment-vars +=
    STANDARD_SLACK_WEBHOOK https://hooks.slack.com/services/xxx
    FTW_LOGGER_SLACK_WEBHOOK deactivate

Threading

All requests to the Slack-API will be handled within its own threads. All messages are sent in a separate thread so that it is non-blocking and does not crash the application on an error.

The function notify_slack returns the thread-object for further thread handlings (i.e. in testing) or none.

Links

• Main project repository: https://github.com/4teamwork/ftw.slacker

• Issue tracker: https://github.com/4teamwork/ftw.slacker/issues

Copyright

This package is copyright by 4teamwork.

ftw.slacker is licensed under GNU General Public License, version 2.

1.1.0 (2019-11-27)

• Remove support for Plone 5.0. [mbaechtold]

• Test against Plone 5.1. [mbaechtold]

• Test against Plone 5.2 and Python 3.7. [ericof]

1.0.2 (2017-07-31)

• Use unittest instead unittest2 in tests. [elioschmutz]

1.0.1 (2017-07-27)

• Fix README.rst errors. [elioschmutz]

1.0.0 (2017-07-27)

• Initial release.