Overview
========

Each badge is a key-value pair. For example, one badge might have a key of "fruit" and a value of "apple".

Filtering Clouds With Badges
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To filter your list of clouds by badge, navigate to the Clouds section of the site and click on the "Search Badge(s)"
text box.

.. figure::  /images/badges/overview5.png
   :align:   center

A drop-down list will appear. Select the badges which you want to match in your list of clouds.

.. figure::  /images/badges/overview6.png
   :align:   center

By default, results shown match at least one badge in your provided criteria. To show only those results which match all
selected badges, check the "Must Have All Badges" checkbox.

.. figure::  /images/badges/overview7.png
   :align:   center

Adding/Removing Badges
~~~~~~~~~~~~~~~~~~~~~~

To add/remove a badge to/from a cloud, navigate to the "Clouds" page in your account from the left-hand menu, and then
find the "# Badges" column for the cloud to/from which you want to add/remove badges. Click on the number in that
column.

.. figure::  /images/badges/overview0.png
   :align:   center

The "Add Cloud Badges" dialog window will appear. In this dialog, click the plus icon (+) to create a line for
your new badge.

.. figure::  /images/badges/overview1.png
   :align:   center

In the new, blank space, add the name of your new badge. Badge names have no restrictions. Both badge keys and badge
values are case-sensitive. Repeat this process for as many new badges as you like.

.. figure::  /images/badges/overview2.png
   :align:   center

To remove any user-created badges, click the minus icon (-) next to each entry you wish to remove.

.. figure::  /images/badges/overview3.png
   :align:   center

When you are finished adding and removing badges, click the "SUBMIT" button to save your changes.

.. figure::  /images/badges/overview4.png
   :align:   center

Badges in Messages
~~~~~~~~~~~~~~~~~~

You can also use this information in messages. For example, you could use the following message, which uses Jinja2
templating and Slack formatting, to send an alert via Slack when a resource is created without tags mandated by policy.
Suppose a given cloud has a tag of ``owner: jane.doe@acme.com``. Then the value returned in the example below for
``{{event.resource.get_badge_value_by_key_for_parent_cloud('owner')}}`` will be ``jane.doe@acme.com``.

  .. code::

      A resource of type `{{event.resource.get_resource_type()}}` was discovered
      at `{{event.resource.common.creation_timestamp}}` without the required _owner_
      or _contact-email_ tags. The resource name is `{{event.resource.get_resource_name()}}`.
      It lives in account `{{event.resource. get_organization_service_name()}}`,
      which is owned by {{event.resource.get_badge_value_by_key_for_parent_cloud('owner')}}`.\n---