========
Alerting
========


Setting up alerts
=================

calcite can communicate and send notifications through various channels.
To configure alerts, simply visit the ``Alerts`` page of your project.

Connectors
----------

You can create alerts using the following connectors:

- pull request comments (WIP, depends on your repository :doc:`provider </usage/providers/index>`)
- email
- slack
- webhooks (WIP)

Tags
----

Each alert that you configure can have a list of tag conditions that act as filters.
This is a semicolon-seperated list (``cond1;cond2;cond3...``) and each condition is made of one or multiple tags, seperated by the character ``&`` (*and*).

Examples
   - ``(empty)`` an empty list will trigger the connector only if no tag is specified.
   - ``master;dev`` will trigger the connector only if the tags ``master`` or ``dev`` are present.
   - ``master&IndividualCI;dev&PullRequest`` will trigger only if the tags ``master`` and ``IndividualCI`` are present, or if the tags ``dev`` and ``PullRequest`` are present.

.. warning::
   | The only exception right now is the pull requests connector, which is disabled if no tag is listed.
   | This will be changed in an upcoming version.

Triggering a workflow
=====================

Once all your datasets are :doc:`uploaded </usage/upload>`, it is possible to trigger a :term:`workflow <Workflow>` using the calcite :doc:`/usage/cli`. 

.. hint::
    | ``npx @siliceum/calcite-cli [command arguments]`` allows you to quickly test the calcite CLI.
    | Similarly to ``calcite upload``, you will need to provide the project token.

Then you can use the following command:

``calcite trigger <baseline commit id>``.

This will trigger a workflow against the provided baseline commid it.

.. note::
   For now, the baseline commit id must be the full commit id, not an alias or the abbreviated version.
   In the future, you will be able to use any git reference.

   - ✅ ``be790bd7340d39fcb29077234e75ddf19df14696`` works
   - ❌ ``be790bd73`` does NOT work 
   - ❌ ``v1.2.0`` does NOT work
   - ❌ ``refs/heads/master`` does NOT work
   - ❌ ``master`` does NOT work


You can also specify more information via additional arguments:

calcite trigger [options] <baseline_id> [target_id]
   Triggers a calcite workflow for the given baseline (previous) and target (new) commits, using their full commit sha.
   This is used once all datasets were uploaded to trigger notifications.

   -u, --url <server url>        Set the target server url, for preview and enterprise users. The `CALCITE_URL` environment variable can also be used, otherwise it will be set to the public server.
   -t, --token <token id>        Set the project token. By default the `CALCITE_TOKEN` environment variable is used.
   -tt, --triggertags <taglist>  Comma seperated list of tags for this workflow. This is used as a filter for alerts.
   -PR, --pullRequestId <id>     Specify the pull request number.
   -h, --help                    display help for command