> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Migration & Installation
> Migrate from Insights v0.3.0 or earlier to v0.4.0+ by adding database support and updated frontend wiring for the Feedback feature.
> If this is your first time installing Backstage Insights, you can safely ignore this section. However, if you are currently using a version of `@spotify/backstage-plugin-insights` that is `v0.3.0` or earlier, you will need to migrate using the following guide.
As of `v0.4.0`, the Backstage Insights plugin has introduced the **Feedback** feature, enabling you to create and administer pop-up surveys within Backstage where you can collect qualitative and satisfaction data.
This feature requires two small changes to existing installations.
There is a known issue with react-router\@6.0.0-beta.0 that causes the Feedback
features route matching functionality to not work as expected. If you are
using this version of react-router, please follow the Backstage guidance of
[upgrading to a later mainline (6.x.x) version of
react-router](https://backstage.io/docs/tutorials/react-router-stable-migration).
## Provide a database to the backend
Surveys and survey responses are stored in your Backstage instance's database. You will therefore need to provide a database manager to the Insights backend:
If you are using the New Backend System, you can skip this section.
1. [Upgrade](../getting-started#upgrading-the-plugins) to the latest version of `@spotify/backstage-plugin-insights-backend`
2. Add the database manager (`database` argument) to the `createRouter` call in `src/plugins/insights.ts`
```ts packages/backend/src/plugins/insights.ts highlight={7} theme={"theme":{"light":"github-light","dark":"dracula"}}
export default async function createPlugin(
env: PluginEnvironment,
): Promise {
return await createRouter({
cache: env.cache,
config: env.config,
database: env.database,
discovery: env.discovery,
identity: env.identity,
logger: env.logger,
permissions: env.permissions,
tokenManager: env.tokenManager,
});
}
```
If your `src/plugins/insights.ts` file resembles the following snippet, no action is necessary.
```ts packages/backend/src/plugins/insights.ts theme={"theme":{"light":"github-light","dark":"dracula"}}
import { createRouter } from '@spotify/backstage-plugin-insights-backend';
export default async function createPlugin(
env: PluginEnvironment,
): Promise {
return await createRouter({
...env,
});
}
```
## Install the `SurveyLoader` in the frontend
Pop-up surveys can be configured to load on arbitrary paths in your Backstage app. The `` needs to be installed in your app frontend in order for surveys to be loaded and rendered.
1. [Upgrade](../getting-started#upgrading-the-plugins) to the latest version of `@spotify/backstage-plugin-insights`
2. Add the `` under your `` in your `App.tsx` file:
```ts packages/app/src/App.tsx highlight={4,12} theme={"theme":{"light":"github-light","dark":"dracula"}}
import {
InsightsPage,
insightsPlugin,
InsightsSurveyLoader,
} from '@spotify/backstage-plugin-insights';
...
export default app.createRoot(
<>
{routes}
,
);
```
## (Optional) Configure new permissions
**Feedback** introduces the concept of surveys, which are a resource type that can be permissioned. If you are using RBAC or the permissions framework to configure access controls, you will likely want to take these new permissions into account.
The full list of permissions and their descriptions can be viewed [under Available Permissions](./setup-and-installation#available-permissions), but two common scenarios are detailed below.
### Insights Admin role
If you had previously limited access to the Insights plugin to a specific group of "admin" users, you'll likely want to allow those same users the following permissions: `insights.survey.read`, `insights.survey.create`, `insights.survey.update`, and `insights.survey.delete`.
In the RBAC UI, such a role might look like this:
### Delegate access through survey ownership
The Backstage Insights plugin also exposes an `IS_SURVEY_OWNER` rule, which can be used to conditionally allow surveys to be read, updated, or deleted based on a user's ownership claims.
This conditional rule can be used to allow a group of users to manage their surveys without necessarily being able to see responses to surveys they're not involved with.
