Add the project name and project URL to bom processing notifications

[2000rosser]

Description

Previously, the user was only notified of the result of the BOM processing.

Now the user is told the name of the project for each notificication, and for processing errors, they are also given the project URL

Addressed Issue

#3637

Checklist

• I have read and understand the contributing guidelines
• This PR fixes a defect, and I have provided tests to verify that the fix is effective
• This PR implements an enhancement, and I have provided tests to verify that it works as intended
• This PR introduces changes to the database model, and I have added corresponding update logic
• This PR introduces new or alters existing behavior, and I have updated the documentation accordingly

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ +1.09% (target: -1.00%)	✅ ∅ (target: 70.00%)

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (fd82e58)	22052	16503	74.84%
Head commit (95c45ea)	22069 (+17)	16756 (+253)	75.93% (+1.09%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#3666)	0	0	∅ (not applicable)

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

_{Codacy will stop sending the deprecated coverage status from June 5th, 2024. Learn more}

[2000rosser]

When I cloned the repo and ran the App, it was using the BomUploadProcessingTask class. There is also the option to use BomUploadProcessingTaskV2, which is what the unit tests are checking. Which class is the correct one to make the changes?

[nscuro]

@2000rosser I don't think you need to touch the code dispatching the notification internally at all. The notification subject already includes the project object, it's just that when transforming this information to the MS Teams Webhook format, it is not included in the output.

When calling Notification.dispatch, what happens is that the Notification object is sent to NotificationRouter, which rules (i.e. the Alerts configured in the UI) apply.

For each applicable rule, it will invoke the corresponding publisher (i.e. email, MS Teams, Slack).

Publishers basically use Pebble templates to format a Notification to whatever the destination is expecting. You can see the variables made available in the template context here:

dependency-track/src/main/java/org/dependencytrack/notification/publisher/Publisher.java

Lines 83 to 143 in 7285d90

	default String prepareTemplate(final Notification notification, final PebbleTemplate template) throws IOException {
	try (QueryManager qm = new QueryManager()) {
	final ConfigProperty baseUrlProperty = qm.getConfigProperty(
	ConfigPropertyConstants.GENERAL_BASE_URL.getGroupName(),
	ConfigPropertyConstants.GENERAL_BASE_URL.getPropertyName()
	);
	final Map<String, Object> context = new HashMap<>();
	final long epochSecond = notification.getTimestamp().toEpochSecond(
	ZoneId.systemDefault().getRules()
	.getOffset(notification.getTimestamp())
	);
	context.put("timestampEpochSecond", epochSecond);
	context.put("timestamp", notification.getTimestamp().toString());
	context.put("notification", notification);
	if (baseUrlProperty != null) {
	context.put("baseUrl", UrlUtil.normalize(baseUrlProperty.getPropertyValue()));
	} else {
	context.put("baseUrl", "");
	}
	if (NotificationScope.PORTFOLIO.name().equals(notification.getScope())) {
	if (notification.getSubject() instanceof final NewVulnerabilityIdentified subject) {
	context.put("subject", subject);
	context.put("subjectJson", NotificationUtil.toJson(subject));
	} else if (notification.getSubject() instanceof final NewVulnerableDependency subject) {
	context.put("subject", subject);
	context.put("subjectJson", NotificationUtil.toJson(subject));
	} else if (notification.getSubject() instanceof final AnalysisDecisionChange subject) {
	context.put("subject", subject);
	context.put("subjectJson", NotificationUtil.toJson(subject));
	} else if (notification.getSubject() instanceof final ViolationAnalysisDecisionChange subject) {
	context.put("subject", subject);
	context.put("subjectJson", NotificationUtil.toJson(subject));
	} else if (notification.getSubject() instanceof final BomConsumedOrProcessed subject) {
	context.put("subject", subject);
	context.put("subjectJson", NotificationUtil.toJson(subject));
	} else if (notification.getSubject() instanceof final BomProcessingFailed subject) {
	context.put("subject", subject);
	context.put("subjectJson", NotificationUtil.toJson(subject));
	} else if (notification.getSubject() instanceof final VexConsumedOrProcessed subject) {
	context.put("subject", subject);
	context.put("subjectJson", NotificationUtil.toJson(subject));
	} else if (notification.getSubject() instanceof final PolicyViolationIdentified subject) {
	context.put("subject", subject);
	context.put("subjectJson", NotificationUtil.toJson(subject));
	}
	} else if (NotificationScope.SYSTEM.name().equals(notification.getScope())) {
	if (notification.getSubject() instanceof final UserPrincipal subject) {
	context.put("subject", subject);
	context.put("subjectJson", NotificationUtil.toJson(subject));
	}
	}
	enrichTemplateContext(context);
	try (final Writer writer = new StringWriter()) {
	template.evaluate(writer, context);
	return writer.toString();
	}
	}
	}

The template files live here. I recently added a suite of tests that assert the current output of all publishers. The relevant test case for this issue can be found here:

dependency-track/src/test/java/org/dependencytrack/notification/publisher/MsTeamsPublisherTest.java

Lines 71 to 107 in 7285d90

	@Override
	public void testInformWithBomProcessingFailedNotification() {
	super.testInformWithBomProcessingFailedNotification();
	verify(postRequestedFor(anyUrl())
	.withHeader("Content-Type", equalTo("application/json"))
	.withRequestBody(equalToJson("""
	{
	"@type": "MessageCard",
	"@context": "http://schema.org/extensions",
	"summary": "Bill of Materials Processing Failed",
	"title": "Bill of Materials Processing Failed",
	"sections": [
	{
	"activityTitle": "Dependency-Track",
	"activitySubtitle": "1970-01-01T18:31:06.000000666",
	"activityImage": "https://raw.githubusercontent.com/DependencyTrack/branding/master/dt-logo-symbol-blue-background.png",
	"facts": [
	{
	"name": "Level",
	"value": "ERROR"
	},
	{
	"name": "Scope",
	"value": "PORTFOLIO"
	},
	{
	"name": "Group",
	"value": "BOM_PROCESSING_FAILED"
	}
	],
	"text": "An error occurred while processing a BOM"
	}
	]
	}
	""")));
	}

You will notice that the corresponding test case for the email publisher does include the desired information:

dependency-track/src/test/java/org/dependencytrack/notification/publisher/SendMailPublisherTest.java

Lines 144 to 178 in 7285d90

	@Override
	public void testInformWithBomProcessingFailedNotification() {
	super.testInformWithBomProcessingFailedNotification();
	assertThat(greenMail.getReceivedMessages()).satisfiesExactly(message -> {
	assertThat(message.getSubject()).isEqualTo("[Dependency-Track] Bill of Materials Processing Failed");
	assertThat(message.getContent()).isInstanceOf(MimeMultipart.class);
	final MimeMultipart content = (MimeMultipart) message.getContent();
	assertThat(content.getCount()).isEqualTo(1);
	assertThat(content.getBodyPart(0)).isInstanceOf(MimeBodyPart.class);
	assertThat((String) content.getBodyPart(0).getContent()).isEqualToIgnoringNewLines("""
	Bill of Materials Processing Failed
	--------------------------------------------------------------------------------
	Project: projectName
	Version: projectVersion
	Description: projectDescription
	Project URL: /projects/c9c9539a-e381-4b36-ac52-6a7ab83b2c95
	--------------------------------------------------------------------------------
	Cause:
	cause
	--------------------------------------------------------------------------------
	An error occurred while processing a BOM
	--------------------------------------------------------------------------------
	1970-01-01T18:31:06.000000666
	""");
	});
	}

So ideally you shouldn't have to touch any code at all, except the test that is asserting the current output for MS Teams once the template has been updated.

[2000rosser]

@nscuro Thank you for taking the time to explain, it makes a lot more sense now.

[nscuro]

Thanks @2000rosser!