Configuring Channels in Alert

Alert channels are how Alert sends notifications. Alert supports the following channels:

Before using Alert, you must configure at least one channel in Alert. This section explains the prerequisites for configuring a channel and describes the configuration of each channel.

Because Alert Channels channels are configured in Distributions, no configuration or MS Teams is required.

 

The configuration for Providers (Black Duck) and Channels are called global configurations that can be used in Distribution jobs.

 

 

If you try to create a Distribution job without configuring a Channel, you will get a warning similar to the following:

Warning: <Channel Name> global configuration missing.

Adding issues in Black Duck for issues found by Alert channels

Alert adds issue links in Black Duck f” and "App ID" are used interchangeably to refer to the value of the field App ID found in the Azure Client Application settings.

Configure Azure Boards

Before you configure the Azure Boards channel in Alert, you must do the following:

  1. When installing Alert, ensure that the ALERT_HOSTNAME is set to the hostname where Alert is accessed because the OAuth handshake has to redirect to the Alert server.

    1. For docker swarm, update the docker-compose.local-overrides.yml

    2. For Helm, update the hostname property in values.yml

  2. Follow the instructions to create a client application in Azure.

    1. Assign the following scopes to the application.

      • Project and team (read)

      • Work items (full)

    2. Assign the redirect URL that the application requires, which is a specific Alert URL.

      • https://<ALERT_HOSTNAME>:<ALERT_SERVER_PORT>/alert/api/callbacks/oauth/azure
        For example, https://localhost:8443/alert/api/callbacks/oauth/azure
        If the Redirect URL in the client application does not match the URL for Alert, then when you click the Authenticate button, Alert can't retrieve the OAuth tokens.

    3. Copy the client ID and the client secret to use when configuring the Alert Channel.

Configure the Azure Boards channel

  1. Navigate to Channels > Azure Boards, and provide values for these fields:

    • Organization Name: Name of Azure DevOps organization

    • Client ID: The Client ID created for Alert when registering the client application.

    • Client Secret: The Client secret created for Alert when registering the client application.
       

  2. Click Authenticate to be redirected to Microsoft's OAuth login, which starts the process of allowing access to the application created in Azure and fetching the OAuth tokens. 
    (If the scopes assigned to the client application are anything other than project and team (read) and Work items (full), Alert will not be able to retrieve OAuth tokens.)
    NOTE: When you click the Authenticate button, Alert validates the configuration and saves it if it's valid, so you don't need to click the Save button first and then the Authenticate button.

    1. When you click Authenticate, the configuration is saved, and you are redirected to the Azure login page if you're not already logged in.

    2. When you're logged in with your Azure credentials, you may be asked to allow access to the client application.

    3. When you allow the client application access, Azure redirects to Alert via the redirect URL, and Alert starts acquiring the OAuth tokens.

    4. You are redirected to the Alert user interface when Alert has the OAuth tokens. 

      NOTE: When you click the  Authenticate button, you are redirected to Microsoft's OAuth login.
      You remain logged in; you might want to log out of your Microsoft account after authenticating to the application for security reasons.

  3. To test the configuration, click Test Configuration

  4. Click Save.

  5. Optional: To delete the current configuration, click the Delete button

You remain logged into Azure after authentication. You might want to log out for security reasons after authenticating the application.

Configuring Email

Configure the email server to which Alert sends emails.

Prerequisites for email:

  • SMTP host

  • SMTP from email address

  • If SMTP authentication is enabled, the SMTP username and password authenticate to the SMTP host.

Configure email

  1. Navigate to Channels > Email, and provide values for these fields:
    SMTP Host: The hostname of the SMTP server.
    SMTP From: The email address to use in the From field.
    SMTP Auth: Select this checkbox if your SMTP server requires authentication; then complete the SMTP User and SMTP Password fields.
    SMTP User: The username to authenticate with the SMTP server.
    SMTP Password: The password to authenticate with the SMTP server.
    Add Additional Email Properties: Use to further configure the SMTP server and provide values for the fields described on this page using the field name for the left-side value.

  2. Clicking Test Configuration opens a Test Your Configuration dialog box containing an email address field for a test email. This enables you to validate your email configuration, as a test email sends a test message.

  3. In the Email address field, type the email address to which you want the test email sent.

  4. Click Send Test Message.
    If there are errors in your configuration, an ERROR message displays at the top of the page. If successful, a confirmation of Test successful displays.

  5. Check your email for the test message.

  6. Optional: To delete the current configuration, click the Delete button.

  7. Click Save.

About using email for Project and Project Version notification types

Project and project version notification types do not work well for the email channel. If the project is new, it usually does not initially have any users assigned to it. When projects are deleted, email addresses associated with the project are also deleted, so there are no users to notify.

When projects are deleted, you might receive an email stating that a project has been removed even if you are not a member of that project. This might occur if a distribution job has multiple projects associated with the job and you are a member of one of those projects.

Alert removes the project data from Alert one or two minutes after deletion when a project is deleted. There are no email addresses associated with that project in Alert when this happens. This means that Alert treats this case like a system-wide notification and sends the notification to all other email addresses for the projects associated with the job. This happens when the distribution job is configured for a Daily frequency. For distribution jobs with Real Time frequency, this does not occur. 

Using Slack and MsTeams channels

The Slack and MsTeams channels work better for Project and Project Version notification types because they can send these updates without any issues. These notification types are also used in the Jira Cloud and Jira Server channel; when you configure a Distribution Job in Alert for the Jira Cloud and Jira Server channels, the Project and Project Version deletions are used to help determine which Jira issues to resolve.

Alert only sends messages to the channels for new notifications. Messages are not sent for existing projects until a change triggers a notification. There is no retroactive look back for past notifications.

Configuring Jira Cloud

Configure the Jira Cloud server to which Alert sends updates.

Prerequisites for Jira Cloud:

  • URL

  • Email of the Jira Cloud user

  • API token for the specified Jira user

Configure Jira Cloud channel

  1. Navigate to Channels > Jira Cloud, and provide the following values:

  2. URL: The URL of the Jira Cloud server.

  3. Email Address: The email address of the Jira Cloud user. This user must be a Jira admin unless the Disable Plugin Check checkbox is selected.

  4. API token: The API token of the specified Jira Cloud user.
    You must have administrative privileges to generate a valid API token.

  5. Disable Plugin Check: Select this option to disable checking whether the Alert Issue Property Indexer plugin is installed on the Jira instance. You must ensure that the plugin is manually installed before using Alert with Jira. If you don't do this check, issues created by Alert in Jira will not be updated correctly, and duplicate issues may be created.

  6. Configure Jira Cloud plugin: Select this option to disable checking whether the Alert Issue Property Indexer plugin is installed on the Jira instance. You must ensure that the plugin is manually installed before using Alert with Jira. If you don't do this check, issues that Alert creates in Jira will not be updated correctly.

  7. Click Test Configuration to validate your Jira Cloud configuration.

  8. Optional: To delete the current configuration, click the Delete button.

  9. Click Save.

 

Jira Cloud environment variables

In Alert versions 5.0.0 and later, you can configure your Jira Cloud environment through the user interface or by using the environment variables in the blackduck-alert.env file.

You can set your Jira Cloud environment variables as follows.

  1. ALERT_CHANNEL_JIRA_CLOUD_JIRA_CLOUD_URL= URL for your Jira Cloud server

  2. ALERT_CHANNEL_JIRA_CLOUD_JIRA_CLOUD_ADMIN_EMAIL_ADDRESS= Email address for your Jira Cloud administrator

  3. ALERT_CHANNEL_JIRA_CLOUD_JIRA_CLOUD_ADMIN_API_TOKEN= Jira Cloud API token (token generated by a Jira Cloud user through the Jira cloud server)
    To learn more about generating a Jira Cloud token, refer to Atlassian API tokens.

In Alert 5.3.0 and later, you can delete the channel configuration for Email and Jira Cloud Channels by clicking the Delete button.

Configuring Jira Server

Configure the Jira server to which Alert sends updates.

Prerequisites for Jira server:

  • URL for Jira server

  • Username and password for Jira server user

Alert versions 5.2.0 and later, Jira Server was added to Channels. Using the Jira Server channel, you can configure the Jira Server instance to which Alert sends issue updates. The Jira Server channel works similarly to the Jira Cloud channel.

As of Alert 6.10.0 and later, support for multiple Jira Server channels has been added.  The Jira Server channel configuration page now displays a table of Jira Server channel configurations.  Similarly to the table of Black Duck providers for reference.

When clicking on the Jira Server channel for global configuration a table will be displayed. A user can add or delete Jira Server configurations. The configurations added to this screen will be available for a user to select when configuring a distribution job. This will allow the user to control which server Jira issues are created or updated from Alert.

A user will click New to create a configuration. A user can double click on a row or click the edit icon in the edit column to edit an existing configuration. When a user is creating a new configuration or editing an existing configuration they will be presented with a form to fill in the configuration details

Configure a Jira Server channel

  1. Navigate to Channels > Jira Server. Click on the New button above the table and complete the following fields.

  2. Name: The unique name for the Jira Server.

  3. Server URL: Type your Jira server URL.

  4. User Name: The username of the Jira Server user. This user must be a Jira admin unless the Disable Plugin Check checkbox is selected.

  5. Password: The password of the specified Jira Server user.

  6. Disable Plugin Check: Select this option to disable checking whether the Alert Issue Property Indexer plugin is installed on the Jira instance. You must ensure that the plugin is manually installed before using Alert with Jira. If you don't do this check, issues created by Alert in Jira will not be updated correctly, and duplicate issues may be created.

  7. Configure Jira server plugin: Click Install Plugin Remotely so that Alert installs the required plugin on the Jira server. This action installs a custom plugin called Alert Issue Property Indexer from the marketplace on the configured Jira Cloud server. This plugin enables Alert to search on the properties added to the issues created. To use Install Plugin Remotely, you must have execute permissions.

  8. When all fields are complete, click Test Configuration.

  9. Optional: To delete the current configuration, click the Delete button.

  10. If your configuration is successful, click Save. Otherwise, the fields requiring attention are highlighted.

 

In Alert 6.10.0 and later, you can delete the channel configuration for Jira Server Channel by clicking the Delete button above the table.

Configuring MS Teams

There is no global configuration for MS Teams when navigating to Channels > MS Teams.

  1. Navigate to Jobs > Distribution and select MsTeams for the Channel Type in a new distribution job where you configure a Webhook to post messages from Alert.

  2. To generate an MS Teams Webhook, follow the instructions for Setting up a custom incoming webhook.

Configuring Slack

There is no global configuration for Slack when navigating to Channels > Slack.

  1. Navigate to Jobs > Distribution and select Slack for the Channel Type in a new distribution job where you configure a Webhook to post messages from Alert.

  2. To generate a Slack Webhook, follow the instructions for Setting up a custom incoming webhook.

For a given global configuration such as for a Black Duck provider or channels, but not job configurations, if you remove the values in all fields and click Save, the configuration is cleared from the Alert database.

 

©2021 Synopsys, Inc. All Rights Reserved