Make a Notification Card

You may wish to create a Card which notifies the user of important information when it is available, and dismisses itself when this information is no longer relevant. We can accomplish this with a Notification Card.

An example of such a Card would be one which shows notifications for each of your open GitLab issues, automatically displaying a Notification Card when a new issue is opened, and dismissing it when the issue is closed.

If you haven't already, follow the guide to create a Connector with oauth for your GitLab account, which will help you to build a regular Card that fetches and displays all of your open issues. We will use that card as the basis for the notification card in this guide.

Modify Card metadata to act as a notification

In order for the Card to function as per-issue notifications rather than a list of all issues, we need to modify the Card's metadata. Navigate to Content Manager → Now Cards and click Edit on the GitLab Card you created in the previous guide. There are a few small tweaks that we need to make here.

The three alterations we need to make to the Card's metadata

  1. Scheduling

    Firstly, we want the Card to automatically refresh itself at a certain interval to retrieve issues that are still open or new, so that those which have closed will disappear from your Now tab. The simplest way to do this is via polling, by assigning a schedule to the Card. Find the Schedule section of the Edit Now Card screen, and change the schedule from none to a desired interval, for example every 15 minutes.

    Webhooks

    It is also possible to use push instead of polling by enabling a webhook for the Card. This way it will receive a trigger from GitLab every time an issue is opened or changes status, so the Card only refreshes when necessary. If you have many Cards which are polling via schedules, it is preferable to use webhooks instead to reduce the load on your server.

    For GitLab, you can configure webhooks in the Integrations settings of a GitLab project. Selecting Enable Web Hook on the Now Card edit screen will display the trigger URL to use in your GitLab webhook settings. For more information on using webhooks with GitLab please refer to their webhook documentation.

  2. Collection Mode

    Secondly, we need to change the collection mode of the Card, so that rather than one Card displaying all of the retrieved GitLab issues, it will separate each issue into its own Card. To accomplish this, we simply need to scroll a little further down the Now Card edit screen to Collection Mode and select isolated rather than aggregated from the drop-down.

  3. Card title (optional)

    In the next step we will be altering the appearance of the Card slightly to suit the display of single issues rather than a list, so you may want to change the title of the Card to something more descriptive, depending on what you called the card when following the previous guide.

    Something like GitLab Issues will serve as an adequate description of the Card contents, so that we can minimise the content in the body of the Card and improve its appearance and readability. This can be done in the same Now Card edit screen by editing the Title field.

    Be sure to press save before leaving the edit screen for the next section.

Update Card styling

The Notification Card is now functional, but we could make it look a little neater. Navigate to Development → Manage Spaces → Global → Components, enter the folder for your GitLab Card, and enter the designer for default.card.

Go to the Elements tab and select the content element. In the view markup editor, remove the following line:

<h2>My open Gitlab issues:</h2>

Now that the Card only displays a single issue, this heading no longer makes sense. It can therefore be removed, and the context of the Card will instead be indicated by the title we set earlier. This leaves the Card body to contain just the issue heading and text. Save these changes and leave the editor.

Test your Notification Card

The Notification Card is now complete, so let's try it out. Navigate to Now Workplace → My Cards and find your GitLab Issues Card. Enable it by selecting Show Now notification card.

Here's what you should see in your My Cards screen

Next, navigate to the Now tab. Provided you have open issues on your GitLab account, you should see each of them appear within their own Notification Card.

Completed GitLab Issues Notification Card in the Now Workplace

Try opening some new issues on a test project in GitLab to see them appear, and disappear again as you close them. Remember the Cards will only refresh based on the schedule you set for them, so unless you configured webhooks, they will not update immediately.