Zulip Integration
=================

`Zulip <https://zulipchat.com/>`_ is a team chat tool, in context of DevOps it can be used for sending various events of intenrest. Some of these event include:

1. Generate Trello Application Key and User Token
2. Running of a cron job {or in case of Django a Management Command}
3. Notify ops team when someone logs onto server
4. Notify development team when customer files a bug on issues tracking sytem {E.g. `Trello`} 

Trello
``````

`Trello <https://trello.com/>`_ is a good productivity that gets all stake holder on to a single platform. Following notes suggests how to integrate Trello with Zulip

Obtain Trello's Keys, you need to obtain

1. `Board ID`: Go to your Trello board. The URL should look like

.. code-block:: sh

    https://trello.com/b/<BOARD_ID>/<BOARD_NAME>.

Note down the  `<BOARD_ID>`

2. `API Key`: Go to 

.. code-block:: sh

    https://trello.com/1/appkey/generate

Note down the key listed under Developer API Keys.

3. `User Token`: Go to 

.. code-block:: sh

    https://trello.com/1/appkey/generate

Under Developer API Keys, click on the Token link. Click on Allow. Note down the token generated.

Once this is done, you need to 

1. Create the stream on Zulip where you'd like to use for Trello notifications
2. Create topic in that stream
3. Construct the URL for integration using the bot's API key and the desired stream name

.. code-block:: sh

    https://XXX.zulipchat.com/api/v1/external/trello?api_key=XXXXXXX&stream=<STREAM_NAME>&topic=<TOPIC_NAME>

4. Create `zulip_trello_config.py` file with following contents

.. code-block:: python

    TRELLO_API_KEY = "XXX"
    TRELLO_TOKEN = "XXXXXXXXX"
    ZULIP_WEBHOOK_URL = "https://XXX.zulipchat.com/api/v1/external/trello?api_key=XXXXXXX&stream=<STREAM_NAME>&topic=<TOPIC_NAME>"

5. Download and run `zulip_trello.py <https://github.com/zulip/python-zulip-api/blob/master/zulip/integrations/trello/zulip_trello.py>`_

.. code-block:: sh
    
    python zulip_trello.py --trello-board-name <trello_board_name> --trello-board-id   <trello_board_id>

CLI integration
````````````````

Lets say you want to send messages from command lines {e.g. via Python app}, following are the steps to do it

1. Install `zulip client <https://github.com/zulip/python-zulip-api/tree/master/zulip>`_ package

.. code-block:: sh

    pip install zulip

2. Get Zuplip keys by following these `instructions <https://zulipchat.com/api/api-keys>`_

3. Create `~/.zuliprc` file and use following configuration

.. code-block:: ini

    [api]
    email=<your_email_address@domain.com>
    key=<your_zulip_api_key>
    site=<https://your_zulip_domain.zulipchat.com>

4. Check if you're able to send messages using `zulip-send` command

.. code-block:: sh

    zulip-send --stream YourStream --subject YourSubject --message "This is awesome message from zulip" --config-file ~/.zuliprc

Sending message to specific user can be achieved using

.. code-block:: sh

    zulip-send users_email@domain.com --message "This is awesome message from zulip" --config-file ~/.zuliprc