Campaigns - Spotify for Backstage

Campaigns in Soundcheck

Soundcheck Campaigns provide a structured approach for organizations to drive focused initiatives, such as software updates or system transitions. They offer a way to create, manage, and monitor these initiatives within the Soundcheck framework.

Key features include:

Initiation of Campaigns: Users can create campaigns with specific goals, ownership, and timelines.
Focused Initiatives: Campaigns enable targeting specific organizational objectives, like updating a software library.
Notification System: Alerts are optionally sent out via Slack when there are changes in check statuses or certification levels, aiding prompt action.
Dashboard Tracking: Progress of campaigns across different teams or the entire organization is visually trackable.
Archiving Feature: Completed campaigns can be archived for historical reference.

Campaigns are designed to enhance awareness and actionability in focused initiatives, providing an additional capability within Soundcheck to manage initiatives that run for shorter periods. Some example use cases include: Examples include:

There is a need to Upgrade Spring Libraries to use a specific version of Spring Boot.
When your organization wants to remove unneeded data endpoints to save cost.

Campaigns Page

The Campaigns page in Soundcheck serves as the central dashboard for all campaign-related activities. It is designed to provide users with a comprehensive overview of campaigns as well as control over various campaigns within the organization. Here, users can engage in several key activities:

Navigate to Individual Campaign Details: Users can view detailed information about each campaign, including its objectives, current status, assigned teams or individuals, and progress metrics. This detailed view helps in monitoring and managing specific campaigns more effectively.
Create New Campaigns: This function allows users to initiate new campaigns. Users can define the campaign’s objectives, set timelines, assign owners, and specify other relevant parameters. The creation process is designed to be intuitive, guiding users through each step to ensure all necessary information is captured.
Edit Campaigns: Campaign creators have the flexibility to modify the details of existing campaigns. This includes changing objectives, timelines, ownership, and other critical campaign parameters. This feature is crucial for adapting to changing conditions or requirements within a project or organization.
Delete Campaigns: In cases where a campaign is no longer relevant or has been created by mistake, users can remove it from the system. This helps in maintaining a clean and up-to-date campaign dashboard.
Archive Completed Campaigns: Once a campaign has reached its conclusion or its goals have been met, users can archive the campaign. This feature keeps the main dashboard focused on active campaigns, while still preserving the data of completed initiatives for future reference or analysis.

Campaign Creation

Creating campaigns in Soundcheck is a feature accessible to all users, allowing them to initiate new campaigns. This process is divided into four structured steps.

Step 1: Campaign Details

In this initial step, users establish the foundational elements of the campaign:

Campaign Name: Assign a unique and descriptive name for easy identification.
Campaign Description: Provide a detailed description of the campaign’s objectives and scope.
Campaign Owner: Designate the individual or team responsible for overseeing the campaign.
Support Channel: Optionally specify the Slack channel for campaign-related notifications.
Start and End Dates: Set definitive start and end dates to establish a clear timeline for the campaign.
Mark as draft: Draft campaigns are perfect for testing and verification, allowing you to refine your campaign before making it visible by default. Draft campaigns are hidden from Soundcheck Entity Card, Soundcheck Entity Tab and Soundcheck Overview pages.

Step 2: Selecting Checks

This step involves choosing specific checks that the campaign will use to track progress against.

Step 3: Applying Filters

Filters are used to determine which entities the campaign targets. See filters for more details.

Step 4: Defining Milestones

Milestones are set to track progress and achieve specific targets within the campaign. Each milestone includes a name, description, and a defined pass rate, providing clear targets for campaign progression.

Campaign Archival

The Soundcheck Campaigns page which lists all active campaigns offers users tools for finalizing and archiving campaigns, ensuring the completion of objectives is clearly documented. Admins and authorized users can view archived campaigns, providing a historical perspective on past initiatives.

Configure mode for YAML-sourced campaigns

Campaigns defined in YAML configuration files (via app-config.yaml) cannot be edited and saved through the UI because they are not stored in the Soundcheck database. However, you can use Configure mode to work with these campaigns using the full form tooling. When you open the action menu for a YAML-sourced campaign, a Configure button appears instead of Edit. Clicking it opens the campaign form in Configure mode, which:

Opens directly to a Preview YAML step so you can immediately see the YAML output.
Lets you navigate back through all form steps to modify details, checks, filters, and milestones.
Replaces the Save button with an Export button that downloads the campaign as a YAML file in the soundcheck.tracks config format (with type: campaign), ready to paste into your configuration.
Replaces the Cancel button with a Close button that shows a confirmation dialog before discarding your changes.

You can also use the clipboard button in the YAML preview to copy the configuration directly.

Configure mode does not persist any changes to the database. To apply your changes, export or copy the YAML and update your configuration files (app-config.yaml or the referenced YAML files) manually.

Export to YAML

Individual campaigns can be exported as YAML via the row action menu in the campaigns table.

Associated checks are not exported. You must export these separately and ensure the id fields match.

All campaigns can be saved as YAML via the Export all campaigns button on the top toolbar.

Associated checks are not exported. You must export these separately and ensure the id fields match.

Export entities to CSV

On a campaign’s detail page, the entity list can be exported to CSV using the Export button in the toolbar. The export respects any active filters, so the downloaded file contains exactly the entities visible on screen. The CSV includes the following columns: Name, Pass Rate, Passed, Failed, Warning, Error, Not Reported, Exempt, System, Type, Lifecycle, Kind, Owner, and Entity Ref. Owner, System, Type, and Lifecycle are enriched from the Backstage Software Catalog.

Exports are limited to 5,000 entities. If the filtered list exceeds this limit, a warning toast is displayed indicating how many entities were included out of the total.

Import from YAML

Campaigns can be created from YAML via the Import YAML campaign(s) button on the top toolbar. The campaigns will be created in the Soundcheck database and can be modified later just like other campaigns created via the UI. If using RBAC, make sure that your user has soundcheck.track.create permission.

Notes:

YAML file may contain either a single campaign or an array of campaigns.
Campaigns are tracks with type: campaign — the same soundcheck.tracks format is used.
If the YAML file contains campaigns with IDs that already exist in Soundcheck, such campaigns will be skipped and the import will continue as normal.
If one or more campaigns fail to import, their IDs will be listed in the warning banner and the import of the remaining campaigns will continue as normal.

Associated checks are not imported. You must import these separately and ensure the id fields match.

Managing campaigns via YAML configuration

Campaigns can be defined in code via YAML configuration files. Campaigns defined in config are read-only and cannot be edited, archived, or deleted from the UI.

Overall Shape Of A Campaign

A campaign is a track with type: campaign and additional campaign-specific fields like startDate, targetCompletionDate, milestones, and supportChannel. The following is an example of a YAML-defined campaign:

- id: production-lifecycle-campaign
  name: Ensure Lifecycle Production Set
  type: campaign
  ownerEntityRef: group:default/toast-infra
  description: >
    Ensure all components have a production lifecycle defined in their
    catalog-info.yaml to indicate production readiness.
  filter:
    kind: 'Component'
  startDate: '2026-04-01'
  targetCompletionDate: '2030-04-01'
  supportChannel: toasty-devs
  milestones:
    - name: 80% Adoption
      targetPercent: 80
  levels:
    - checks:
        - id: has-production-lifecycle
          name: Has Production Lifecycle
          description: >
            Verifies that the component has a production lifecycle defined
            in its catalog-info.yaml.

See below for details about the campaign fields.

Adding YAML campaigns to Soundcheck

Campaigns are defined alongside tracks in the soundcheck.tracks configuration. To add campaigns defined in a YAML file, source them in your app-config.yaml. You have the option of storing them locally or remotely. Here is an example configuration should your campaign YAML files be local to your Backstage project:

app-config.yaml

soundcheck:
  tracks:
    - $include: ./path-to-local-folder/campaigns-file.yaml
    - $include: ./path-to-local-folder/tracks-file.yaml

To maintain your campaign files in a remote repo, you can source them in app-config.yaml in a similar manner:

app-config.yaml

soundcheck:
  tracks:
    - https://github.com/user/repo/blob/main/campaigns-file.yaml
    - https://github.com/user/repo/blob/main/tracks-file.yaml
  remote_file_updates:
    disabled: false
    frequency:
      minutes: 5

Campaigns and tracks share the same soundcheck.tracks configuration key and can coexist in the same YAML file. Campaigns are distinguished by type: campaign.

You cannot combine local and remote sourcing. This includes the usage of $include within a remotely sourced file. See the tracks documentation for details.

Smart Defaults

Campaign YAML supports minimal configurations with sensible defaults:

ordinal on levels defaults to 0 (campaigns must have exactly one level).
milestones — if omitted, a single “Campaign Complete” milestone is created with targetPercent: 100.
Milestone id — if omitted, an ID is auto-generated using the pattern {campaign-id}-milestone-target{percent}-{date} to prevent collisions across campaigns.
Milestone targetPercent — defaults to 100 if omitted.
Milestone targetCompletionDate — defaults to the campaign’s targetCompletionDate if omitted.

This means a minimal campaign only needs id, name, ownerEntityRef, description, startDate, targetCompletionDate, type: campaign, and a single level with checks.

Minimal Campaign Example

The following example will automatically create a single “Campaign Complete” milestone at 100% targeting the campaign’s end date:

- id: upgrade-spring-boot
  name: Upgrade to Spring Boot 3
  type: campaign
  ownerEntityRef: group:default/platform-team
  description: >
    Migrate all Java services to Spring Boot 3 before end of support.
  startDate: '2026-01-01'
  targetCompletionDate: '2026-12-31'
  levels:
    - checks:
        - id: uses-spring-boot-3
          name: Uses Spring Boot 3
          description: >
            Verifies that the service is running Spring Boot 3.x.

Migrating campaigns from YAML to no-code UI

To migrate campaigns from YAML to the no-code UI, follow these steps:

Remove references to campaigns from the soundcheck.tracks configuration in app-config.yaml.
Import the YAML campaigns previously referenced in configuration using the “Import YAML campaign(s)” button on the Campaigns tab in the UI.

Your campaign history will be preserved, and you can continue to use the campaigns as usual.

Campaign Fields

Field	Required	Description
`id`	Yes	Unique identifier for this campaign.
`name`	Yes	Human-readable name for this campaign.
`type`	Yes	Must be set to `campaign`.
`description`	Yes	Details about the campaign’s objectives and scope.
`ownerEntityRef`	Yes	Relates this campaign to the person or team responsible for maintaining it.
`startDate`	Yes	The start date for the campaign in ISO date format (e.g. `2026-04-01`).
`targetCompletionDate`	Yes	The target end date for the campaign in ISO date format (e.g. `2030-04-01`).
`levels`	Yes	Must contain exactly one level with one or more checks.
`filter`	No	Specifies the type of entities that this campaign targets.
`exclude`	No	Specifies entity types to exclude from this campaign.
`milestones`	No	An array of milestones to track progress. A default milestone is created if omitted.
`supportChannel`	No	Deprecated. Slack channel name for legacy campaign notifications. Ignored when using the Backstage Notifications plugin.
`documentationURL`	No	Link users can follow for more details about this campaign.
`draft`	No	A boolean flag that enables / disables draft mode. Draft campaigns are not visible by default.
`archived`	No	A boolean flag indicating whether the campaign is archived.

Milestone Fields

Field	Required	Default	Description
`id`	No	Auto-generated	Unique identifier for the milestone. Auto-generated if omitted.
`name`	Yes		A name for the milestone suitable for display.
`description`	No		Additional details about the milestone.
`targetPercent`	No	`100`	The pass rate percentage target for this milestone (0-100).
`targetCompletionDate`	No	Campaign’s `targetCompletionDate`	The target date for reaching this milestone in ISO date format.

Campaign Progress and Milestones

Milestones are an important part of campaigns, serving as tangible markers of progress and success. Each milestone’s progress is monitored, with updates provided on completion rates and remaining tasks. Campaign progress is monitored and displayed in various sections within Soundcheck:

Campaign Insights Page: Each campaign has an insights page where you can view information about your campaign.
Entity-Specific Progress: For each entity page in Soundcheck, there’s a section that displays the campaign progress related to that particular entity.

Campaign Notifications

The legacy campaign notification systems (direct Slack and email) are deprecated and will be removed in a future release. Use the Backstage Notifications plugin instead. See the migration guide for details.

The optional notification feature for campaigns is designed to keep users informed and responsive to changes and developments within their software environment. They act as a proactive communication tool, enhancing awareness and efficiency in managing software health and compliance. For detailed documentation on getting notifications set up, refer to the Slack Notifications or Email Notifications sections.

Scenarios for Receiving Notifications

During campaign creation, the creator has the option to set up a Slack channel to be used for campaign notifications. If specified, campaign notifications will be sent to the provided channel.

Assigned Campaigns: When a new campaign is created, the campaign specific channel will receive a notification to acknowledge and start addressing the goals of the campaign.
Campaign Updates: Alerts are issued for any changes to a campaigns, including the checks associated with the campaign, the milestones of the campaign, or any related metadata.
Campaign Deleted: Alerts when a Campaign itself has been Deleted.
Campaign Archival: When a Campaign is archived an alert will be sent.

​Campaigns in Soundcheck

​Key features include:

​Campaigns Page

​Campaign Creation

​Step 1: Campaign Details

​Step 2: Selecting Checks

​Step 3: Applying Filters

​Step 4: Defining Milestones

​Campaign Archival

​Configure mode for YAML-sourced campaigns

​Export to YAML

​Export entities to CSV

​Import from YAML

​Managing campaigns via YAML configuration

​Overall Shape Of A Campaign

​Adding YAML campaigns to Soundcheck

​Smart Defaults

​Minimal Campaign Example

​Migrating campaigns from YAML to no-code UI

​Campaign Fields

​Milestone Fields

​Campaign Progress and Milestones

​Campaign Notifications

​Scenarios for Receiving Notifications

Campaigns in Soundcheck

Key features include:

Campaigns Page

Campaign Creation

Step 1: Campaign Details

Step 2: Selecting Checks

Step 3: Applying Filters

Step 4: Defining Milestones

Campaign Archival

Configure mode for YAML-sourced campaigns

Export to YAML

Export entities to CSV

Import from YAML

Managing campaigns via YAML configuration

Overall Shape Of A Campaign

Adding YAML campaigns to Soundcheck

Smart Defaults

Minimal Campaign Example

Migrating campaigns from YAML to no-code UI

Campaign Fields

Milestone Fields

Campaign Progress and Milestones

Campaign Notifications

Scenarios for Receiving Notifications