Distribution Jobs

About Distribution Jobs

Configure distribution jobs to send specific types of alerts to selected audiences. You use the providers and channels that you configure to create distribution jobs in Alert.

Go to Jobs > Distribution to define and manage your Alert jobs; in other words, you create and save sets of 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. Therefore, if a notification is generated in any version of a project configured in the distribution job, and if the notification matches a notification type configured in the distribution job, then an alert is sent, either through email, Jira Cloud, Jira Server, MS Teams, 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: When this distribution job is set to run; either Daily or Real Time.

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

• Status: Success or Fail.

• 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 and the global configuration is missing 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.

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 drop-down 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.

4. Complete the fields as follows.
   The following are common for all job types:
   Name: Type a unique name for the distribution job.
   Frequency: Use the drop-down to select how frequently you want Alert to check for notifications to send: Real Time as triggers occur, or Daily.
   Provider Type: Name of provider type. Only notifications for the selected provider are processed in this distribution job. Selecting Black Duck displays additional fields which are described in the following steps.

5. Provider Configuration: The unique name assigned to this provider configuration that is configured on the Providers page.

6. After completing the previous fields, additional fields display which are pertinent to your selected provider type, which includes the following fields and sections.

   Notification Types: Select one or more types from the drop-down 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 higher support the BOM_EDIT notification. In Distribution Job configurations with Black Duck selected as the provider, BOM_EDIT displays as an option in the drop-down selector for Notification Types. The BOM_EDIT notification is primarily intended for use in Jira Cloud to keep component information on issues as up to date as possible.
   When Project and Project Version Black Duck notification types are selected, these notifications notify you 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.
   In Alert versions 5.1.0 and higher, two new Black Duck notification types are supported: Project and Project Version. When selected, these notifications notify you 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.

   Notification types are as follows:
   - BOM_EDIT
   - PROJECT
   - PROJECT VERSION
   - LICENSE_LIMIT
   - POLICY_OVERRIDE
   - RULE_VIOLATION
   - RULE_VIOLATION_CLEARED
   - VULNERABILITY

   Processing: Select one of the following:
   - Default: Displays the notifications as they are.
   - Digest: Displays a more streamlined version.
   - Summary: Only includes changes that have occurred.
   Note: In versions 5.3.0 and earlier, the Processing field is labeled as Format.
   Important note:
   Using the Summary processing type with the issue tracker channels will result in unexpected behavior with the issues that are created.

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:

8. Project name pattern: Type the regular expression to use for determining the projects to include. These are in addition to the projects selected in the table.

9. Projects: Select a project or projects to be used to retrieve notifications from your provider. 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.

   Black Duck Notification Filtering:
   This filtering option is available when you select Black Duck as the Provider.

   Policy Notification Type Filter: To use this filter, you select a policy notification.
   Click Select to show a list of policies and select the checkbox for each policy that you want to add, and click OK.
   Vulnerability Notification Type Filter: To use this filter, you select a vulnerability notification.
   Click the dropdown menu to show a list of vulnerability severities.

10. The following fields display based on your selection in the 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: Type the text to use 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 that 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 versions 5.1.0 and higher, 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: By selecting this checkbox, 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. Direct links 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 to be used as an email attachment in the Distribution job.
  Click Attachment File Type, and select the file. Attachment options are CSV, JSON, XML and NONE which is the default.

Slack

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

• Channel Name: Type the Slack #[channel name].

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

Jira Server

In Alert versions 5.2.0 and later, distribution jobs can be configured to send notifications to the Jira server channel. When configured, 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.

• Provider Type: Select the provider. Only notifications from the selected provider are processed in the distribution job.

• 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.

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.

Jira Cloud

In Alert versions 5.0.0 and higher, distribution jobs can be configured to send notifications to the Jira cloud channel. When configured, 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.

• 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 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, not the 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.

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. Your settings will vary based on your environment; this example is for illustrative purposes only.

There are no default values provided for Jira Cloud transitions fields; specifically the Resolve Transition and the Re-open Transition fields. If these fields remain blank, issues can still be opened and commented, but no transitioning occurs. If you provide valid transitions, then those transitions occur whenever the issue is updated.

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: Your choice of existing projects.

• 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; for example, Vulnerability or Policy and the Component and Component Version of that issue are used to update the issue rather than to create a new issue. Examples include, but are not limited to:

• Black Duck Security Vulnerability: vulnerabilities change = comment on the ticket if configured to do so 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, when issues are updated, a comment describing those changes is added to the existing issue.

Permissions - Jira Cloud

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

• Create issues

• Browse projects

• Resolve issues

• Add comments

 The Jira Cloud 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 higher, 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. By using the copy functionality you can easily configure multiple distribution jobs where only a small number of fields differ between jobs. When copying a distribution job, you must use a unique job name for the copied job. Clicking the copy icon displays the Copy Distribution Job dialog box.

To copy a distribution job:

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

2. Edit the job as desired.

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

4. Click Save.

Identical distribution jobs

If you configure two distribution jobs for Jira Cloud that are identical in their settings, and those settings include transitions, they will thrash. That means that one of the jobs transitions the issue and the next job tries to transition the issue but fails 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 the transition for that message has already been executed by Jira Cloud.

Defining the Project Name Pattern

In the job definition, the Project Name Pattern field displays after selecting Black Duck as the provider type, and then deselecting the Filter by project checkbox. This is a regular expression pattern that you must use. If you are not familiar with regular expressions, or to find examples of valid input, refer to: https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html.

The project name pattern functionality is a way to define a regular expression to match project names which determines the projects to include. This is in addition to the projects selected in the table. Use this feature when you want to define a regular expression to match multiple projects in Black Duck. When new projects are added that match the pattern, they are automatically included in the data for the distribution job, instead of requiring an administrator of Alert to edit a job to add the new Black Duck project to the job. Your specific naming patterns for your projects enables you to define a job once in Alert, and includes the ability to add projects to a provider as needed. Alert sends future notifications including the newly-added project notification data.

For example, assume the following projects exist:

• TestProject

• TestProject1

• TestProject2

Now assume there’s a distribution job called Job1. An administrator creates Job1 with this regular expression in the distribution job field: TestProject[0-9]*. This adds a new project in Black Duck named TestProject3. Job1 sends notifications for TestProject3 because the regular expression matches. An administrator didn’t have to manually edit Job1 to include TestProject3.

Common to all job types:

1. Select/deselect the Projects checkbox as desired. If you deselect it, you are prompted to select one or more projects from a list. Should the list be too long, you can click Show Selected Only to display only the selected projects. Sort the list by clicking the column headings.

2. Click Test Configuration to send a test alert to ensure values are 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.

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

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 versions 5.1.0 and higher, 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.

Deleting global configurations

For a given global configuration, but not job configurations, if you remove the values in all fields and click Save, the configuration is cleared from the database.

Vulnerability update considerations

In Alert versions 5.0.0 and higher, vulnerability notifications include remediation information when available. This is listed as an additional section of the message, and is listed per component version.