Slack Private Group Clusters
============================

membership tools for private groups
-----------------------------------

Slack channels are great, anyone who is a member of your team can join
or leave a channel as they want. Slack also supports private groups (aka
private channels) which are invite-only. These private groups are
invisible to anyone who is not a member of the group, and are
appropriate for subsets of the team who need to work on particular
projects.

Unfortunately, there's nothing in-between team-wide public channels and
single private groups.

For example, you may have a subset of the team, such as "finance" who
may want to be able to leave or join any of a number of private groups
relating to finance. However, unless they've been manually invited to
all of the private "finance" groups, and added to any new finance groups
that may be created in the future, there is a chance they can be kept in
the dark about the activites of their own team.

One way to solve this would be to create a finance-only Slack team for
just the finance department. Another way, while definitely not perfect,
is to use a custom integration to create "private-group-clusters."

For example, one can add all the members of the finance department to a
private group, such as "finance-department" and they may join any other
private group matching a regular expression or expressions (e.g.
"finance-.\*" and "sales-forecast").

Audience
--------

Be familiar with Apache, CGI programs, Python, and JSON, and creating
Slack integrations before attempting this.

Installation
------------

    pip3 install slack-groupmgr

will create three new commands, `groupmgr`, `groupmgr-cgi`, and
`groupmgr-flask`.  They are, in turn, the commandline, CGI, and
a standalone Flask/WSGI debugging server.

In production, we strongly reccomand using the WSGI version of
group manager, and running it under Apache or ngnix or gunicorn
or one of the many WSGI capable webservers out there.

The CGI version is legacy and might be abandoned in the future.

Configuration:
--------------

Create a "Group Manager" account, it does not need special privileges,
but it must have access to the Web API. At this time it cannot be a
"bot" account, it must be a regular account to use the API's group
invite mechanism.

Invite this "Group Manager" account to all of the private groups you
want it to manage. Slack users, even team owners, do not have any
visibility into groups that they are not a member of, and "Group
Manager" is no different.

Acquire a WEB API token for the Group Manager account.
``https://api.slack.com/docs/oauth-test-tokens``

Create a custom slash command integration for your copy of Group Manager
with the following parameters:

-  Command: /groupmgr (or whatever you want to call it)
-  URL: point to your server hosting groupmgr
-  Method: POST
-  Token: (generated by Slack, record this, you'll need it below
   (SLASH-TOKEN)
-  Customize Name: "Group Manager"
-  Customize Icon: (your choice)
-  Autocomplete Description: Add yourself to semi-private groups
-  Autocomplete Help: Use 'list', 'add', and 'help' for more info

Configure your webserver to execute the groupmgr python script as CGI at
the URL you chose above.

Note: Python 3 has some issues with Unicode encoding if the ``LANG``
environment variable is not set properly before the interepreter
executes code. Make sure that ``LANG`` is set to a utf-8 encoding such
as ``C.utf-8`` or ``EN_us.utf-8``.

Finally, configure the script itself, look at ``examples/config.json``

The script, by default, will look for config.json in
``$HOME/.config/groupmgr/config.json``

-  ``default-team`` is only used when using the command line
-  ``team_id`` is the Slack ID (starts with T0.....) of your team
-  ``api_token`` is the Slack Web API token that groupmgr will use to
   control Slack
-  ``inbound_tokens`` are a list of valid SLASH-TOKENs from the slash
   commands
-  ``administrators`` are the names of users who can use groupmgr admin
   commands

Finally, configure your groups, the dictionary is indexed by a master
group followed by a list of regular expressions. See the example file
for the format.
