diff --git a/.changeset/selfish-phones-smoke.md b/.changeset/selfish-phones-smoke.md new file mode 100644 index 0000000000..42f33f9869 --- /dev/null +++ b/.changeset/selfish-phones-smoke.md @@ -0,0 +1,37 @@ +--- +'@backstage/plugin-scaffolder': minor +'@backstage/plugin-scaffolder-backend-module-cookiecutter': patch +'@backstage/plugin-scaffolder-backend-module-rails': patch +'@backstage/plugin-scaffolder-backend-module-yeoman': patch +'@backstage/plugin-scaffolder-backend': patch +--- + +Added `catalogFilter` field to OwnerPicker and EntityPicker components to support filtering options by any field(s) of an entity. + +The `allowedKinds` field has been deprecated. Use `catalogFilter` instead. This field allows users to specify a filter on the shape of [EntityFilterQuery](https://github.com/backstage/backstage/blob/774c42003782121d3d6b2aa5f2865d53370c160e/packages/catalog-client/src/types/api.ts#L74), which can be passed into the CatalogClient. See examples below: + +- Get all entities of kind `Group` + + ```yaml + owner: + title: Owner + type: string + description: Owner of the component + ui:field: OwnerPicker + ui:options: + catalogFilter: + - kind: Group + ``` + +- Get entities of kind `Group` and spec.type `team` + ```yaml + owner: + title: Owner + type: string + description: Owner of the component + ui:field: OwnerPicker + ui:options: + catalogFilter: + - kind: Group + spec.type: team + ``` diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md index e5fdb034fb..5c9340b393 100644 --- a/docs/features/software-templates/writing-templates.md +++ b/docs/features/software-templates/writing-templates.md @@ -44,8 +44,8 @@ spec: description: Owner of the component ui:field: OwnerPicker ui:options: - allowedKinds: - - Group + catalogFilter: + kind: Group - title: Choose a location required: - repoUrl @@ -459,7 +459,7 @@ an owner for them. Ideally, users should be able to select an owner when they go through the scaffolder form from the users and groups already known to Backstage. The `OwnerPicker` is a custom field that generates a searchable list of groups and/or users already in the catalog to pick an owner from. You can -specify which of the two kinds are listed in the `allowedKinds` option: +specify which of the two kinds (or both) are listed in the `catalogFilter.kind` option: ```yaml owner: @@ -468,8 +468,8 @@ owner: description: Owner of the component ui:field: OwnerPicker ui:options: - allowedKinds: - - Group + catalogFilter: + kind: [Group, User] ``` ## `spec.steps` - `Action[]` diff --git a/packages/app/src/components/scaffolder/defaultPreviewTemplate.ts b/packages/app/src/components/scaffolder/defaultPreviewTemplate.ts index 56f34779de..5d8a2accda 100644 --- a/packages/app/src/components/scaffolder/defaultPreviewTemplate.ts +++ b/packages/app/src/components/scaffolder/defaultPreviewTemplate.ts @@ -31,8 +31,8 @@ parameters: description: Owner of the component ui:field: OwnerPicker ui:options: - allowedKinds: - - Group + catalogFilter: + kind: Group - title: Choose a location required: - repoUrl diff --git a/plugins/scaffolder-backend-module-cookiecutter/README.md b/plugins/scaffolder-backend-module-cookiecutter/README.md index 8516139e64..ae34e09c96 100644 --- a/plugins/scaffolder-backend-module-cookiecutter/README.md +++ b/plugins/scaffolder-backend-module-cookiecutter/README.md @@ -73,16 +73,16 @@ spec: description: Owner of the component ui:field: OwnerPicker ui:options: - allowedKinds: - - Group + catalogFilter: + kind: Group system: title: System type: string description: System of the component ui:field: EntityPicker ui:options: - allowedKinds: - - System + catalogFilter: + kind: System defaultKind: System - title: Choose a location diff --git a/plugins/scaffolder-backend-module-rails/README.md b/plugins/scaffolder-backend-module-rails/README.md index 738cd43cff..f4ec086775 100644 --- a/plugins/scaffolder-backend-module-rails/README.md +++ b/plugins/scaffolder-backend-module-rails/README.md @@ -74,16 +74,16 @@ spec: description: Owner of the component ui:field: OwnerPicker ui:options: - allowedKinds: - - Group + catalogFilter: + kind: Group system: title: System type: string description: System of the component ui:field: EntityPicker ui:options: - allowedKinds: - - System + catalogFilter: + kind: System defaultKind: System - title: Choose a location diff --git a/plugins/scaffolder-backend-module-yeoman/README.md b/plugins/scaffolder-backend-module-yeoman/README.md index 5242ef298c..b5c7b4d026 100644 --- a/plugins/scaffolder-backend-module-yeoman/README.md +++ b/plugins/scaffolder-backend-module-yeoman/README.md @@ -73,16 +73,16 @@ spec: description: Owner of the component ui:field: OwnerPicker ui:options: - allowedKinds: - - Group + catalogFilter: + kind: Group system: title: System type: string description: System of the component ui:field: EntityPicker ui:options: - allowedKinds: - - System + catalogFilter: + kind: System defaultKind: System - title: Choose a location diff --git a/plugins/scaffolder-backend/sample-templates/bitbucket-demo/template.yaml b/plugins/scaffolder-backend/sample-templates/bitbucket-demo/template.yaml index 58955582d2..0a7c841d8f 100644 --- a/plugins/scaffolder-backend/sample-templates/bitbucket-demo/template.yaml +++ b/plugins/scaffolder-backend/sample-templates/bitbucket-demo/template.yaml @@ -49,8 +49,8 @@ spec: description: Owner of the component ui:field: OwnerPicker ui:options: - allowedKinds: - - Group + catalogFilter: + kind: Group steps: - id: fetch-base diff --git a/plugins/scaffolder/api-report.md b/plugins/scaffolder/api-report.md index 3fe1208ba9..1c4d163123 100644 --- a/plugins/scaffolder/api-report.md +++ b/plugins/scaffolder/api-report.md @@ -88,6 +88,10 @@ export const EntityPickerFieldExtension: FieldExtensionComponent< defaultNamespace?: string | false | undefined; allowedKinds?: string[] | undefined; allowArbitraryValues?: boolean | undefined; + catalogFilter?: + | Record + | Record[] + | undefined; } >; @@ -99,6 +103,10 @@ export const EntityPickerFieldSchema: FieldSchema< defaultNamespace?: string | false | undefined; allowedKinds?: string[] | undefined; allowArbitraryValues?: boolean | undefined; + catalogFilter?: + | Record + | Record[] + | undefined; } >; @@ -316,6 +324,10 @@ export const OwnerPickerFieldExtension: FieldExtensionComponent< defaultNamespace?: string | false | undefined; allowedKinds?: string[] | undefined; allowArbitraryValues?: boolean | undefined; + catalogFilter?: + | Record + | Record[] + | undefined; } >; @@ -326,6 +338,10 @@ export const OwnerPickerFieldSchema: FieldSchema< defaultNamespace?: string | false | undefined; allowedKinds?: string[] | undefined; allowArbitraryValues?: boolean | undefined; + catalogFilter?: + | Record + | Record[] + | undefined; } >; diff --git a/plugins/scaffolder/src/components/TemplateEditorPage/TemplateFormPreviewer.tsx b/plugins/scaffolder/src/components/TemplateEditorPage/TemplateFormPreviewer.tsx index 041b7797ee..5bc32ed581 100644 --- a/plugins/scaffolder/src/components/TemplateEditorPage/TemplateFormPreviewer.tsx +++ b/plugins/scaffolder/src/components/TemplateEditorPage/TemplateFormPreviewer.tsx @@ -53,8 +53,8 @@ parameters: description: Owner of the component ui:field: OwnerPicker ui:options: - allowedKinds: - - Group + catalogFilter: + kind: Group - title: Choose a location required: - repoUrl diff --git a/plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.test.tsx b/plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.test.tsx index 942eef9d82..b6d6688a09 100644 --- a/plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.test.tsx +++ b/plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.test.tsx @@ -14,6 +14,7 @@ * limitations under the License. */ +import { EntityFilterQuery } from '@backstage/catalog-client'; import { Entity } from '@backstage/catalog-model'; import { CatalogApi, catalogApiRef } from '@backstage/plugin-catalog-react'; import { renderInTestApp, TestApiProvider } from '@backstage/test-utils'; @@ -34,7 +35,13 @@ describe('', () => { const schema = {}; const required = false; let uiSchema: { - 'ui:options': { allowedKinds?: string[]; defaultKind?: string }; + 'ui:options': { + allowedKinds?: string[]; + defaultKind?: string; + allowArbitraryValues?: boolean; + defaultNamespace?: string | false; + catalogFilter?: EntityFilterQuery; + }; }; const rawErrors: string[] = []; const formData = undefined; @@ -66,7 +73,7 @@ describe('', () => { afterEach(() => jest.resetAllMocks()); - describe('without allowedKinds', () => { + describe('without allowedKinds and catalogFilter', () => { beforeEach(() => { uiSchema = { 'ui:options': {} }; props = { @@ -136,4 +143,97 @@ describe('', () => { }); }); }); + + describe('with catalogFilter', () => { + beforeEach(() => { + uiSchema = { + 'ui:options': { + catalogFilter: [ + { + kind: ['Group'], + 'metadata.name': 'test-entity', + }, + { + kind: ['User'], + 'metadata.name': 'test-entity', + }, + ], + }, + }; + props = { + onChange, + schema, + required, + uiSchema, + rawErrors, + formData, + } as unknown as FieldProps; + + catalogApi.getEntities.mockResolvedValue({ items: entities }); + }); + + it('searches for a specific group entity', async () => { + await renderInTestApp( + + + , + ); + + expect(catalogApi.getEntities).toHaveBeenCalledWith({ + filter: [ + { + kind: ['Group'], + 'metadata.name': 'test-entity', + }, + { + kind: ['User'], + 'metadata.name': 'test-entity', + }, + ], + }); + }); + }); + + describe('catalogFilter should take precedence over allowedKinds', () => { + beforeEach(() => { + uiSchema = { + 'ui:options': { + catalogFilter: [ + { + kind: ['Group'], + 'metadata.name': 'test-group', + }, + ], + allowedKinds: ['User'], + }, + }; + props = { + onChange, + schema, + required, + uiSchema, + rawErrors, + formData, + } as unknown as FieldProps; + + catalogApi.getEntities.mockResolvedValue({ items: entities }); + }); + + it('searches for a Group entity', async () => { + await renderInTestApp( + + + , + ); + + expect(catalogApi.getEntities).toHaveBeenCalledWith({ + filter: [ + { + kind: ['Group'], + 'metadata.name': 'test-group', + }, + ], + }); + }); + }); }); diff --git a/plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.tsx b/plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.tsx index bc78e00576..48e60b60ad 100644 --- a/plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.tsx +++ b/plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.tsx @@ -13,6 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +import { type EntityFilterQuery } from '@backstage/catalog-client'; import { useApi } from '@backstage/core-plugin-api'; import { catalogApiRef, @@ -44,6 +45,11 @@ export const EntityPicker = (props: EntityPickerProps) => { idSchema, } = props; const allowedKinds = uiSchema['ui:options']?.allowedKinds; + + const catalogFilter: EntityFilterQuery | undefined = + uiSchema['ui:options']?.catalogFilter || + (allowedKinds && { kind: allowedKinds }); + const defaultKind = uiSchema['ui:options']?.defaultKind; const defaultNamespace = uiSchema['ui:options']?.defaultNamespace; @@ -51,7 +57,7 @@ export const EntityPicker = (props: EntityPickerProps) => { const { value: entities, loading } = useAsync(() => catalogApi.getEntities( - allowedKinds ? { filter: { kind: allowedKinds } } : undefined, + catalogFilter ? { filter: catalogFilter } : undefined, ), ); diff --git a/plugins/scaffolder/src/components/fields/EntityPicker/schema.ts b/plugins/scaffolder/src/components/fields/EntityPicker/schema.ts index 9236457fc0..f83dfbf817 100644 --- a/plugins/scaffolder/src/components/fields/EntityPicker/schema.ts +++ b/plugins/scaffolder/src/components/fields/EntityPicker/schema.ts @@ -16,16 +16,28 @@ import { z } from 'zod'; import { makeFieldSchemaFromZod } from '../utils'; +/** + * @public + */ +export const entityQueryFilterExpressionSchema = z.record( + z.string().or(z.array(z.string())), +); + /** * @public */ export const EntityPickerFieldSchema = makeFieldSchemaFromZod( z.string(), z.object({ + /** + * @deprecated Use `catalogFilter` instead. + */ allowedKinds: z .array(z.string()) .optional() - .describe('List of kinds of entities to derive options from'), + .describe( + 'DEPRECATED: Use `catalogFilter` instead. List of kinds of entities to derive options from', + ), defaultKind: z .string() .optional() @@ -42,6 +54,11 @@ export const EntityPickerFieldSchema = makeFieldSchemaFromZod( .describe( 'The default namespace. Options with this namespace will not be prefixed.', ), + catalogFilter: z + .array(entityQueryFilterExpressionSchema) + .or(entityQueryFilterExpressionSchema) + .optional() + .describe('List of key-value filter expression for entities'), }), ); diff --git a/plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.test.tsx b/plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.test.tsx index b78d3add9e..00508593f5 100644 --- a/plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.test.tsx +++ b/plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.test.tsx @@ -14,6 +14,7 @@ * limitations under the License. */ +import { type EntityFilterQuery } from '@backstage/catalog-client'; import { Entity } from '@backstage/catalog-model'; import { CatalogApi, catalogApiRef } from '@backstage/plugin-catalog-react'; import { renderInTestApp, TestApiProvider } from '@backstage/test-utils'; @@ -32,7 +33,15 @@ describe('', () => { const onChange = jest.fn(); const schema = {}; const required = false; - let uiSchema: { 'ui:options': { allowedKinds?: string[] } }; + let uiSchema: { + 'ui:options': { + allowedKinds?: string[]; + defaultKind?: string; + allowArbitraryValues?: boolean; + defaultNamespace?: string | false; + catalogFilter?: EntityFilterQuery; + }; + }; const rawErrors: string[] = []; const formData = undefined; @@ -63,7 +72,7 @@ describe('', () => { afterEach(() => jest.resetAllMocks()); - describe('without allowedKinds', () => { + describe('without catalogFilter and allowedKinds', () => { beforeEach(() => { uiSchema = { 'ui:options': {} }; props = { @@ -108,7 +117,7 @@ describe('', () => { catalogApi.getEntities.mockResolvedValue({ items: entities }); }); - it('searches for users and groups', async () => { + it('searches for users', async () => { await renderInTestApp( @@ -122,4 +131,93 @@ describe('', () => { }); }); }); + + describe('with catalogFilter', () => { + beforeEach(() => { + uiSchema = { + 'ui:options': { + catalogFilter: [ + { + kind: ['Group'], + 'spec.type': 'team', + }, + ], + }, + }; + props = { + onChange, + schema, + required, + uiSchema, + rawErrors, + formData, + } as unknown as FieldProps; + + catalogApi.getEntities.mockResolvedValue({ items: entities }); + }); + + it('searches for group entities of type team', async () => { + await renderInTestApp( + + + , + ); + + expect(catalogApi.getEntities).toHaveBeenCalledWith({ + filter: [ + { + kind: ['Group'], + 'spec.type': 'team', + }, + ], + }); + }); + }); + + describe('catalogFilter should take precedence over allowedKinds', () => { + beforeEach(() => { + uiSchema = { + 'ui:options': { + allowedKinds: ['User'], + catalogFilter: [ + { + kind: ['Group', 'User'], + }, + { + 'spec.type': ['team', 'business-unit'], + }, + ], + }, + }; + props = { + onChange, + schema, + required, + uiSchema, + rawErrors, + formData, + } as unknown as FieldProps; + + catalogApi.getEntities.mockResolvedValue({ items: entities }); + }); + + it('searches for users and groups or teams and business units', async () => { + await renderInTestApp( + + + , + ); + + expect(catalogApi.getEntities).toHaveBeenCalledWith({ + filter: [ + { + kind: ['Group', 'User'], + }, + { + 'spec.type': ['team', 'business-unit'], + }, + ], + }); + }); + }); }); diff --git a/plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.tsx b/plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.tsx index 1c4c356906..5c69e73e12 100644 --- a/plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.tsx +++ b/plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.tsx @@ -33,14 +33,16 @@ export const OwnerPicker = (props: OwnerPickerProps) => { } = props; const defaultNamespace = uiSchema['ui:options']?.defaultNamespace; + const allowedKinds = uiSchema['ui:options']?.allowedKinds; + + const catalogFilter = uiSchema['ui:options']?.catalogFilter || { + kind: allowedKinds || ['Group', 'User'], + }; const ownerUiSchema = { ...uiSchema, 'ui:options': { - allowedKinds: (uiSchema['ui:options']?.allowedKinds || [ - 'Group', - 'User', - ]) as string[], + catalogFilter, defaultKind: 'Group', allowArbitraryValues: uiSchema['ui:options']?.allowArbitraryValues ?? true, diff --git a/plugins/scaffolder/src/components/fields/OwnerPicker/schema.ts b/plugins/scaffolder/src/components/fields/OwnerPicker/schema.ts index 56edef1343..0dbe2fa74f 100644 --- a/plugins/scaffolder/src/components/fields/OwnerPicker/schema.ts +++ b/plugins/scaffolder/src/components/fields/OwnerPicker/schema.ts @@ -15,6 +15,7 @@ */ import { z } from 'zod'; import { makeFieldSchemaFromZod } from '../utils'; +import { entityQueryFilterExpressionSchema } from '../EntityPicker/schema'; /** * @public @@ -22,12 +23,15 @@ import { makeFieldSchemaFromZod } from '../utils'; export const OwnerPickerFieldSchema = makeFieldSchemaFromZod( z.string(), z.object({ + /** + * @deprecated Use `catalogFilter` instead. + */ allowedKinds: z .array(z.string()) .default(['Group', 'User']) .optional() .describe( - 'List of kinds of entities to derive options from. Defaults to Group and User', + 'DEPRECATED: Use `catalogFilter` instead. List of kinds of entities to derive options from. Defaults to Group and User', ), allowArbitraryValues: z .boolean() @@ -39,6 +43,11 @@ export const OwnerPickerFieldSchema = makeFieldSchemaFromZod( .describe( 'The default namespace. Options with this namespace will not be prefixed.', ), + catalogFilter: z + .array(entityQueryFilterExpressionSchema) + .or(entityQueryFilterExpressionSchema) + .optional() + .describe('List of key-value filter expression for entities'), }), );