Configuring Distribution Jobs

Depending on the selected Channel Type, the fields available in the distribution job will be presented as per the listed Channel Types below:

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

• Azure Board: The name of the desired Azure Board as configured in Distribution Channels.

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

Figure 3. Configuring Azure board distribution jobs.

• 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 the drop-down to display the Additional Email Addresses dialog box.

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

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

Figure 4. Additional email recipients

• Additional Email Addresses Only: 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.

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

Figure 5. Alert email distribution job.

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, and you are a member of one of those projects. When a project is deleted, Alert removes the project data within minutes. When this happens, no email addresses associated with that project in Alert, meaning 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 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 Username: Enter the user name to display as the message sender in the Slack channel.

Figure 6. Alert distribution job for Slack.

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

Figure 7. Alert distribution job for MS Teams.

Distribution jobs can be configured 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.

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

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

Figure 8. Configuring Jira distribution jobs.

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.

Figure 9. Advanced Jira Configuration.

To add a custom Jira field:

1. Click + Add Jira Field Mapping 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:

     • String (for example, labels)

     • Component (for example, Component/s field)

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

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

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

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

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

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

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

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

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

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

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"

Example value content:

JSON Object:

{"firstAttribute": 1001, "secondAttribute": "String value" }

JSON array:

[ { “key”: “value-1” }, { “key”: “value-2” }, { “key”: “value-3” }] 

Figure 10. Jira distribution job custom mapping.

Alert will parse the value as JSON and send the JSON as the content for the custom field if Treat Value as JSON is checked. This overrides any custom field processing that Alert does by inspecting the custom field type.

Figure 11. Test Jira distribution job configuration.

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.

Figure 12. Testing Jira distribution job.

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.

A non-admin Jira user (Cloud and Server), configured for Alert must have the following permissions for all Jira projects that Alert might need to update:

• Browse Projects
• Create Issues
• Edit Issues
• Assign Issues
• Modify Reporter
• Transition Issues
• Resolve Issues
• Add comments

The Distribution table includes an additional column containing a copy button. This enables you to copy existing jobs quickly where only a small number of fields differ.

To copy a distribution job:

• In the Distribution table, click on the copy icon in the last column.
• Edit the details as required, making sure to provide a unique job Name.
• Click Save.

If you configure two distribution jobs for Jira that are identical in their settings, and those settings include transitions, they will clash. 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 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 has already executed the transition for that message.

• In Jobs > Distribution, double click the row which contains the Distribution Job to display the Distribution Configuration screen.
• Make the desired edits.
• Click Test Configuration to validate the configuration changes are correct.
• Click Save to persist the edits.

• In Jobs > Distribution click the row that contains the job which you would like to delete.
• Click Delete. A popup will display asking you confirm.
• Click Confirm to delete the job.