Configuring Distribution Jobs in Alert

Table of contents

A distribution job is a set of instructions for using specific channels to send certain alerts to Black Duck users. This section explains how you configure and manage these jobs.

About Distribution Jobs

You use the Black Duck providers and channels that you configure to create distribution jobs in Alert.

Go to the Jobs > Distribution page in Alert to define and manage your Alert jobs. When you create a distribution job, you create and save instructions for sending specific types of alerts to selected audiences. The Distribution page lists all currently saved jobs. From here, you can create, edit, or delete jobs. Selecting a project includes all versions of that project. You get alerts for notification that any version of a project configured in the distribution job generates. The notifications match notifications types configured in the distribution job. Alerts are sent through email, Jira Cloud, Jira Server, MS Teams, Azure Boards, or Slack.

Open

The Distribution page contains the following fields, displayed in a table format. You can sort in ascending or descending order on any column heading.

• Distribution Job: The name for this distribution.

• Type: Azure Boards, Email, Jira Cloud, Jira Server, MS Teams, or Slack.

• Provider: Your selected provider; in this example, Black Duck.

• Frequency Type: Specifies when this distribution job runs, either Daily or Real-Time.

• Last Run: Date/time of the most recent distribution.

• Status: Success, Failure, or Unknown.

• Enabled: Displays a checkmark or an X depending on the enabled state of the job. 
  You can enable or disable a distribution job by selecting a checkbox on the Edit Distribution Job or New Distribution Job screen.

• Edit: Click the pencil icon at the far right to edit a distribution job.

• Copy: Click the copy icon at the far right to copy a distribution job. For more information, refer to Copying a distribution job.

• Enable Auto-Refresh: Selecting this checkbox removes the Refresh button from this screen. Clicking Refresh enables you to refresh the view on-demand. De-select Enable Auto-Refresh to display the Refresh button.

Distribution jobs display an error under the following conditions:

• When you create a new distribution job but the global configuration is not configured for the Channel or Provider.

• When you open an existing Distribution Job, and the global configuration for the Channel is missing.

Open

Creating a distribution job

Use the following process to create a distribution job. Required fields are denoted by a red asterisk ( * ).

1. Navigate to Jobs > Distribution, click +New. The New Distribution Job dialog displays.

2. To enable the distribution job, leave the Enabled checkbox selected or deselect the checkbox to disable the job.

3. Using the Channel Type dropdown menu, select the job type; either Azure Boards, Email, Jira Cloud, Jira Server, MS Teams, or Slack.
   Notifications generated through Alert are sent using this channel. The New Distribution Job dialog expands to display the appropriate fields for the selected job type.
   Note: The distribution jobs display an error message when there are validation errors relating to global configurations.

4. Complete the fields as follows.
   The following are common for all job types:
   Name: Enter a unique name for the distribution job.
   Frequency: Use the dropdown to select how frequently you want Alert to check for notifications to send: Real-Time as triggers occur or Daily.
   Provider Type: Select Black Duck. This displays additional fields, which are described in the following steps.

5. Provider Configuration: Enter the unique name assigned to this provider configuration, which is configured on the Providers page.

6. After completing the previous fields, additional fields display which are pertinent to your selected provider type:
   Notification Types: Select one or more types from the dropdown list. Only the selected notification types are included for this distribution job. Your selections display in the Notification Types box.
   
   - Click X at the right of a notification type to remove it from your selections.
   - Alert versions 5.0.0 and later support the BOM_EDIT notification.
   - In Distribution Job configurations with Black Duck selected as the provider, BOM_EDIT displays as an option in the dropdown selector for Notification Types. The BOM_EDIT notification is primarily used in Jira Cloud, Jira Server, Azure Boards to keep component information on issues as up-to-date as possible.
   - In Alert versions 5.1.0 and later, two new Black Duck notification types are supported: Project and Project Version. When selected, you are notified when new projects or project versions are created or deleted.
   - When used with Jira Cloud, Jira Server, or Azure Boards, the deletion of either project or project version triggers a Resolve Transition, when enabled, for all issues related to it.
   
   For information about notifications in Black Duck, refer to your Black Duck help pages:
   https://<hub-server>/doc/Welcome.htm#users_and_groups/managing_notifications.htm?Highlight=notification
   
   Notification types are as follows:
   - BOM_EDIT- changes to a BOM component such as updating its license or usage
   - PROJECT - projects are created or deleted
   - PROJECT VERSION - project versions are created or deleted
   - LICENSE_LIMIT - license restrictions are near or exceeding capacity
   - POLICY_OVERRIDE - policy is overridden
   - RULE_VIOLATION - policy violation
   - RULE_VIOLATION_CLEARED - policy violation is cleared (either the affected BOM component was deleted or the policy itself was updated)
   - VULNERABILITY - vulnerabilities introduced, updated, or removed.
   - COMPONENT_UNKNOWN_VERSION - a component is added to the BOM that does not have a version. 
   
   Processing: Select one of the following for how the notification message is processed:
   - Default: Displays the notifications as they are.
   - Digest: Displays a more streamlined version.
   - Summary: Only includes changes that have occurred.
   Note:
   In version 5.3.0 and earlier, the Processing field is labeled as Format.
   Important note:
   The Summary processing type was removed (Alert 6.2.0) as an option for the issue tracker channels such as Jira Cloud, Jira Server, or Azure Boards because of unexpected behavior with the created issues.

7. Filter by Project: If selected, only notifications from the selected projects table are processed. Otherwise, notifications from all projects are processed. Selecting this checkbox displays these additional fields:
   
   

• Project Name Pattern: Enter the regular expression to determine the projects to include. These are in addition to the projects selected in the table in the next step.

  The Project Name Pattern field displays after selecting Black Duck as the provider type and then selecting the Filter by Project checkbox. You can supply a regular expression that Alert can use to match multiple Black Duck projects. If you are not familiar with regular expressions, refer to: https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html.

  The project name pattern you specify selects projects in addition to the projects selected in the table. Use this feature when you want to specify multiple projects that have similar names. This saves time in specifying existing projects as well as avoiding the work of adding future projects whose names match the pattern.

  For example, assume there's a distribution job called Job1. An administrator creates Job1 with this regular expression in the distribution job field: TestProject[0-9]*. If a new project is added named TestProject3, Job1 sends notifications for TestProject3 because the new project name satisfies the regular expression matches An administrator didn't have to manually edit Job1 to include TestProject3.

• The Project Version Name Pattern field is similar to the Project Name Pattern field, except it allows further filtering based on the version. If you specify a project name pattern or select any projects, the Project Version Name Pattern only checks the projects that apply when filtering.

• Projects: Select a project or projects for which you want to retrieve notifications.
  - Clicking Select displays the Projects table Select the projects to include in notifications by clicking the checkbox at the left of the project name.
  - Click Show Selected Only to display only your selected projects.
  - Click Show All to display all projects.
  - When you are finished selecting your projects, click OK to return to New Distribution Job.
  
  

  
  Your selected projects now display in the Projects field when projects are selected, but not returned in the request and you navigate to the listing, these items are added to the list and are removable.
  Note: BlackDuck request-caching is employed when saving Distribution Jobs that filter by project.
  BlackDuck projects and users that were updated/deleted less than 2 minutes prior to creating a Distribution Job might not be updated by Alert. his can be resolved by waiting 2 minutes after creating a new project or user before saving the Distribution Job or resaving the Distribution Job after such a change in BlackDuck.
  
  Black Duck Notification Filtering: The following filters are available:
  
  - Policy Notification Type Filter: To use this filter, select a policy notification.
  - Click Select to show a list of policies.
  - Select the checkbox for each policy that you want to add, and click OK.
  Alert versions 5.1.0 and later include vulnerability information in security-related policy notifications.
  
  - Vulnerability Notification Contains Severities: To use this filter, select a vulnerability notification.
  - Click the dropdown menu to show a list of vulnerability severities.
  
  

• Test Configuration
  Click Test Configuration to send a test alert to ensure the configuration is valid. You are notified if the validation fails and the cause of the failure. Incorrect fields are indicated, informing you of the information to correct.

• Click Save to save the new job. You are returned to the Distribution screen, and the new job is listed.
  
  

The following fields are available in the distribution job depending on your selection for the Channel Type field:

Azure Boards

• Comment on Work Items: When selected, Alert comments on Work Items it created when updates occur.

• Azure Project: The project name or ID in Azure Boards

• Work Item Type: The work item type in Azure Boards

• Work Item Completed State: The work item state when Alert receives a DELETE operation for the work item

• Work Item Reopen State: The resulting state of a work item when Alert receives an ADD operation and the work item is in a completed state

Email

• Subject Line: Enter the text for the Alert email subject line.

• Additional Email Addresses: Additional email addresses for valid users of the provider to which notifications of this job should be sent.

  • Click Select to display the Additional Email Addresses dialog box.

  • Click the checkbox for each email address you want to add and click OK.

  • Click the checkbox for Email Address to clear to deselect all previously selected email addresses.

• Additional Email Addresses Only: In Alert version 5.1.0 and later, you can select the Additional Email Addresses Only checkbox to customize email recipients. By selecting this checkbox, you exclude the configured emails on projects and enable sending emails only to the users selected in the Additional Email Addresses field.

• Project Owner Only: Select this checkbox to have Alert sends email alerts to project administrators.
  If this is not selected, then all users assigned to the project, including the project administrators, receive alerts. More information is available through clickable links that are included in the notification emails.

• Additional Email Addresses Only: Selecting this checkbox tells the distribution job to send emails to the additional email addresses only.

• Attachment File Type: You can provide an external file type to be used as an email attachment in the Distribution job.
  Click the dropdown menu for Attachment File Type, and select a file type. Attachment options are CSV, JSON, XML, and NONE which is the default.
  If a file type is selected, then a file of that type that shows the message content is attached to the email.

Email considerations

For email, one message is sent per project, rather than per project version. This occurs only if the notifications are processed in the same batch.

When projects are deleted, you may receive an email stating that a project has been removed even if you are not a member of that project. This may occur if a distribution job has multiple projects associated with the job and you are a member of one of those projects. When a project is deleted, eventually Alert removes the project data from Alert. This usually occurs between one and two minutes after the project is deleted. When this happens, there are no email addresses associated with that project in Alert. This means that Alert treats this scenario 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 happen. An example of a system-wide notification is license limit notifications.

Slack

Slack messages sent via Apps/webhooks use the App name and no longer support setting the sender username. Existing webhooks created before Slack made this change will still support setting the sender username.

When creating new webhooks the field Channel Username will have no effect and will instead show the name of the Slack Application that the webhook was created for.

• Webhook: Enter the appropriate Slack URL to receive alerts.

• Channel Name: Enter the Slack channel name].

• Channel Username: Enter the user name to display as the message sender in the Slack channel.

MS Teams

• Webhook: Enter the MS Teams URL to receive alerts.

Jira Server

In Alert versions 5.2.0 and later, you can configure distribution jobs to send notifications to the Jira server channel. Such notifications create new tickets, or update tickets matching the notification content. The ticket data displays in a format similar to an email or Slack message containing a single piece of data.

In Alert versions 6.10.0 and later, you must select the Jira server configuration name that is assigned, which is configured on the Jira Server channel configuration.

• Jira Server: Select a Jira server that will be used to create or update issues.  Please note the options are limited to the first 25 Jira Servers.

• Add Comments: If this checkbox is selected, comments are added to the Jira ticket with the latest changes.

• Issue Creator: The user name of the Jira server user to assign to the Issue Creator field in the Jira issue.

• Jira Project: The name of the Jira project for which this job creates/updates Jira tickets.

• Issue Type: Specify the issue type; for example, bug or task.

• Resolve Transition: If a transition is listed (case sensitive), it is used when resolving an issue. This happens when Alert receives a DELETE operation from a provider.
  This must be in the Done status category.

• Re-open Transition: Used for re-opening issues. If a transition is listed (case sensitive), it is used when you reopen an issue. This happens when Alert receives an ADD/UPDATE operation from a provider.
  This must be in the To Do status category.

• Issue Summary: Summary of the issue that Alert creates. The following variables can be used to enter content from the message providerName, projectName, projectVersion, componentName, componentVersion, and severity.

• + Advanced Jira Configuration
  Configure custom fields for Jira Server and Jira Cloud distribution jobs. In the Advanced Jira Configuration section, expand this panel to open a field mapping dialog box. Use this field to provide static values to Jira fields or map them to information from the notifications.

• Click + Advanced Jira Configuration

  1. Click + New to create a new mapping

  2. Enter a name for the Jira Field
     Supported field types are:

     • String - i.e. text fields: single and multi-line)

     • Array - A space-separated list of values with the following supported item types:

       o   String (for example, labels)

       o   Component (for example, Component/s field)

       o   Option (for example, Checkboxes)

     • Option (for example, single-select field)

     • Priority – for example, high.

     • User - Use username on Jira Server and Jira Data Center. Use account_id on Jira Cloud. (Find an account ID for a Jira Cloud user.)

  3. Enter a static value or select one of the following placeholders.

     1. {{providerType}} - The name of the Alert provider (Black Duck) from which the notification was received.

     2. {{projectName}} - The name of the project in Black Duck

     3. {{projectVersion}} - The version of the project in Black Duck

     4. {{componentName}} - The name of the component from the project-version in Black Duck

     5. {{severity}} - The policy severity or the highest vulnerability severity for the component in Black Duck.

     6. {{componentVersion}} - The version of the component from the project-version in Black Duck

     7. "{{policyCategory}}" - The policy category field for a policy violation in Black Duck

     8. "{{shortTermUpgradeGuidance}}" - The short term upgrade recommendation for security vulnerabilities of a component in Black Duck

     9. "{{longTermUpgradeGuidance}}" - The long term upgrade recommendation for security vulnerabilities of a component in Black Duck

     10. "{{componentUsage}}" - The usage option of the component in Black Duck

     11. "{{componentLicense}}" - The license name of the component in Black Duck
         
         

          

  4. Templates can be used along with placeholder values to create custom field values.

     • For example, using the following template:

       "Project Name: {{projectName}} | Project Version Name: {{projectVersion}}" 

     • Would produce the following value in the Jira Custom field: 

       "Project Name: my_project | Project Version Name: my_version" 

After you have made your selections for the new distribution job, click Test Configuration. Clicking Test Configuration displays a dialog that is pre-populated with a default message.

Click Send Message to test the job configuration. You c customize the topic displayed in the message and the message content. When clicking Send Message, the configuration is validated and the contents are sent to the channel specified by the job.

If information is missing, the notification Required field missing displays in red above the affected field. Complete the required fields, and click Test Configuration. When the test is successful, click Save.

Jira Cloud

In Alert versions 5.0.0 and later, distribution jobs can be configured to send notifications to the Jira cloud channel. Such notifications can create new tickets, or update tickets matching the notification content. The ticket data displays in a format similar to an email or Slack message containing a single piece of data.

• Add Comments: If this checkbox is selected, comments are added to the Jira ticket with the latest changes.

• Issue Creator: The email address, not the user name, of the Jira user is shown as the creator in Jira. This is the issue reporter. Note that the user must have a valid Jira ID.

• Jira Project: The Jira project to which you want to point. Use the full project name or the project key.

• Issue Type: Specify the issue type; for example, bug or task.

• Resolve Transition: If a transition is listed (case sensitive), it is used when resolving an issue. This happens when Alert receives a DELETE operation from a provider.
  This must be in the Done status category.

• Re-open Transition: Used for re-opening issues. If a transition is listed (case sensitive), it is used when you reopen an issue. This happens when Alert receives an ADD/UPDATE operation from a provider.
  This must be in the To Do status category.

• Issue Summary: Summary of the issue that Alert creates. The following variables can be used to enter content from the message providerName, projectName, projectVersion, componentName, componentVersion, and severity.

• + Advanced Jira Configuration
  Configure custom fields for Jira Server and Jira Cloud distribution jobs. In the advanced Jira Configuration section, expand this panel to open a field mapping dialog box. Use this field to provide static values to Jira fields or map them to information from the notifications.

• Click + Advanced Jira Configuration

  1. Click + New to create a new mapping

  2. Enter a name for the Jira Field
     Supported field types are:

     • String - i.e. text fields: single and multi-line)

     • Array - A space-separated list of values with the following supported item types:

       o   String (for example, labels)

       o   Component (for example, Component/s field)

       o   Option (for example, Checkboxes)

     • Option (for example, single-select field)

     • Priority – for example, high.

     • User - Use username on Jira Server and Jira Data Center. Use acc nt_id on Jira Cloud. (Find an account ID for a Jira Cloud user.)

  3. Enter a static value or select one of the following placeholders.

     • {{providerType}} - The name of the Alert provider (Black Duck) from which the notification was received.

     • {{projectName}} - The name of the project in Black Duck

     • {{projectVersion}} - The version of the project in Black Duck

     • {{componentName}} - The name of the component from the project-version in Black Duck

     • {{componentVersion}} - The version of the component from the project-version in Black Duck

     • {{severity}} - The policy severity or the highest vulnerability severity for the component in Black Duck

     • "{{policyCategory}}" - The policy category field for a policy violation in Black Duck

     • "{{shortTermUpgradeGuidance}}" - The short term upgrade recommendation for security vulnerabilities of a component in Black Duck

     • "{{longTermUpgradeGuidance}}" - The long term upgrade recommendation for security vulnerabilities of a component in Black Duck

     • "{{componentUsage}}" - The usage option of the component in Black Duck

     • "{{componentLicense}}" - The license name of the component in Black Duck
       
       

        

  4. Templates can be used along with placeholder values to create custom field values.

     • For example, using the following template:

       "Project Name: {{projectName}} | Project Version Name: {{projectVersion}}" 

     • Would produce the following value in the Jira Custom field: 

After you have made your selections for the new distribution job, click Test Configuration. Clicking Test Configuration displays a dialog that is pre-populated with a default message.

Click Send Message to test the job configuration. You can customize the topic displayed in the message and the message content. When clicking Send Message, the configuration is validated and the contents are sent to the channel specified by the job.

If information is missing, the notification Required field missing displays in red above the affected field. Complete the required fields, and click Test Configuration. When the test is successful, click Save.

Example of a Jira Cloud distribution setup

The following is an example of a possible Jira Cloud job distribution setup.

There are no default values provided for Jira Cloud Resolve Transition and  Re-open Transition fields. If these fields remain blank, issues can still be opened and commented, but no transitioning occurs.

Alert requires the Reopen Transition field to transition to a status in the To Do status category, and the Resolve Transition field to transition to a status in the Done status category.

Fields and recommended values for a Jira Cloud distribution:

• Type: Jira Cloud

• Name: Your choice

• Frequency: Real-Time

• Provider Type: Black Duck

• Add Comments: Select this checkbox

• Issue Creator: Your choice; must have a valid Jira user ID

• Jira Project: Enter the name of the Jira project

• Issue Type: Task

• Resolve Transition: Resolve Issue

• Re-open Transition: Reopen Issue

• Notification Types: Your choice

• Processing: Default

• Filter by project: Your choice; the default is all Black Duck Projects unless the box is checked.

Example workflow for this Jira Cloud job distribution setup:

Example summary for this Jira Cloud job distribution setup:

Updates to existing Jira Cloud tickets

After an issue is created, any notifications that match the Category value, such as Vulnerability or Policy and the Component and Component Version of that issue, are used to update the issue rather than create a new issue. Examples include, but are not limited to the following:

• Black Duck Security Vulnerability: vulnerabilities change = comment on the ticket if configured in the distribution job.

• Black Duck Security Vulnerability: vulnerabilities are all resolved/deleted = resolve the related ticket.

• Black Duck Policy Violation: vulnerability-related policy/vulnerabilities change = comment on the ticket if configured to do so in the distribution job.

• Black Duck Policy Violation, vulnerability-related policy, vulnerabilities are all resolved/deleted = resolves the related ticket.

• Black Duck Policy Violation, policy violation is overridden/component is removed = resolves the related ticket.

Additionally, a comment describing those changes is added to the existing issue when issues are updated.

Permissions - Jira Cloud

The Jira Cloud user configured for Alert is the user configured in the Jira Cloud Configuration tab and must have the following permissions to create issues for the target project:

• Create issues

• Browse projects

• Resolve issues

• Add comments

The Jira Cloud user must also be an Admin user. Before the plugin creates Jira Cloud issues, it confirms that the Alert Indexer App is installed in the Jira Cloud instance, and this check requires Admin permissions.

For more information regarding permissions, refer to Atlassian: Managing Project Permissions.

Copying a distribution job

In Alert versions 5.0.0 and later, the Distribution table includes an additional column containing a copy button, located at the far right of each distribution job. This enables you to copy the configuration of an existing distribution job and configure new jobs quickly where only a small number of fields differ between jobs.

To copy a distribution job:

1. In the Distribution table, click the copy icon at the far right of the job to be copied.
   The Copy Distribution Job dialog box is displayed.

2. Edit the job as desired.

3. In the Name field, assign a unique name.

4. Click Save.

Identical distribution jobs that include transitions

If you configure two distribution jobs for Jira Cloud that are identical in their settings, and those settings include transitions, they will thrash. When one of the jobs transitions the issue, the next job will fail to transition the issue because the issue is already transitioned.

When resending a notification to a Jira Cloud distribution job from the Audit page, if that distribution job includes transitions and has already succeeded, then an attempt to resend a message to it fails because Jira Cloud has already executed the transition for that message. 

Editing a distribution job

1. In Jobs > Distribution, click the Edit (pencil) icon at the right of the desired job. The Edit Distribution Job dialog displays. In Alert version 5.1.0 and later, double-clicking a row in the Distribution table opens the Edit Distribution Job dialog for the selected entry.

2. Make the desired edits.

3. Click Test Configuration to send a test alert to ensure values are valid.

4. Click Save to save the edited job. Your changes are saved, and you are returned to the Distribution screen.

Deleting a distribution job

1. In Jobs > Distribution, click the row of the desired job to select it.

2. Click Delete. A popup asks you to confirm the deletion.

3. Click Confirm. The job is deleted.