Page Comparison

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. Therefore, if a notification is generated in You get alerts for notification that any version of a project configured in the distribution job , and if the notification matches a notification type generates. The notifications match notifications types configured in the distribution job, then an alert is sent, either . Alerts are sent through email, Jira Cloud, Jira Server, MS Teams, Azure Boards, or Slack.

...

...

• 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 Specifies when this distribution job is set to runruns, 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.

...

• When you create a new distribution job , and but the global configuration is missing not configured for the Channel or Provider, which means that the Provider or Channel you're trying to use is not configured.

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

...

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:
   

   Image RemovedImage Added

Note: Alert (ProviderDataAccessor) now retrieves Black Duck project and user data information directly from Black Duck rather than using the database tables in Alert.

• 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. ou You are notified if the validation fails and the cause of the failure. ncorrect Incorrect fields are indicated, informing you of the information to correct.

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

...

• 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. tachment 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. is 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. is This may occur if a distribution job has multiple projects associated with the job and you are a member of one of those projects. en When a project is deleted, eventually Alert removes the project data from Alert. s This usually occurs between one and two minutes after the project is deleted. W When this happens, there are no email addresses associated with that project in Alert. Th 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. Th This happens when the distribution job is configured for a Daily frequency. For stribution distribution jobs with Real-Time frequency, this does not happen. An e ple example of a system-wide notification is a license limit notifications.

...

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

...

In Alert versions 5.2.0 and later, you can configure distribution jobs to send notifications to the Jira server channel. Such tifications notifications create new tickets, or update tickets matching the notification content. The t ket 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 tifications 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 ppens 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 ansition transition is listed (case sensitive), it is used when you reopen an issue. This ppens 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 f lowing 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 th the Advanced Jira Configuration section, expand this panel to open a field mapping dialog box. Use t s this field to provide static values to Jira fields or map them to information from the notifications.
  
  To add a custom Jira Field.

• 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 a ountaccount_id on Jira Cloud. (Find n 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:

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

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

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

After you have made your selections for the new distribution job, click Test Configuration. Click g 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 icking 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. Compl Complete the required fields, and click Test Configuration. When t the test is successful, click Save.

...

In Alert versions 5.0.0 and later, distribution jobs can be configured to send notifications to the Jira cloud channel. Such no fications notifications can create new tickets, or update tickets matching the notification content. The tic t 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 th that the user must have a valid Jira ID.

• Jira Project: The Jira project to which you want to point. Use the ull 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 ha ens 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 tr sition transition is listed (case sensitive), it is used when you reopen an issue. This ha ens 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 fol wing 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  vanced advanced Jira Configuration section, expand this panel to open a field mapping dialog box. Use thi this field to provide static values to Jira fields or map them to information from the notifications.

  To add a custom Jira Field.

  1. Click + Advanced Jira Configuration

  2. Click + New to create a new mapping

  3. 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 a an account ID for a Jira Cloud user.)

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

       

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

     • For example, using the following template:

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

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

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

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

Click Send Message to test the job configuration. You can ustomize customize the topic displayed in the message and the message content. When cl king 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. Complet he Complete the required fields, and click Test Configuration. When the st 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 elds fields remain blank, issues can still be opened and commented, but no transitioning occurs.

...

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

...

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.

...

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 i is deleted.