Merge pull request #5730 from SDA-SE/feat/entity-picker

Add a `<EntityPicker>` field to the scaffolder

.changeset/red-ducks-yawn.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder': patch
+---
+
+Add a `<EntityPicker>` field to the scaffolder to pick arbitrary entity kinds, like systems.

plugins/scaffolder-backend/sample-templates/v1beta2-demo/template.yaml

@@ -29,6 +29,16 @@ spec:
           ui:options:
             allowedKinds: 
               - Group
+        system:
+          title: System
+          type: string
+          description: System of the component
+          ui:field: EntityPicker
+          ui:options:
+            allowedKinds: 
+              - System
+            defaultKind: System
+            
     - title: Choose a location
       required:
         - repoUrl

plugins/scaffolder-backend/sample-templates/v1beta2-demo/template/catalog-info.yaml

@@ -7,3 +7,6 @@ spec:
   type: website
   lifecycle: experimental
   owner: {{cookiecutter.owner | jsonify}}
+{%- if cookiecutter.backstage_system != "" %}
+  system: {{ cookiecutter.system | jsonify }}
+{%- endif %}

plugins/scaffolder/src/components/ScaffolderPage/ScaffolderPage.tsx

@@ -35,12 +35,12 @@ import StarIcon from '@material-ui/icons/Star';
 import React, { useEffect, useMemo, useState } from 'react';
 import { Link as RouterLink } from 'react-router-dom';
 import { EntityFilterGroupsProvider, useFilteredEntities } from '../../filter';
+import { registerComponentRouteRef } from '../../routes';
 import { ResultsFilter } from '../ResultsFilter/ResultsFilter';
 import { ScaffolderFilter } from '../ScaffolderFilter';
 import { ButtonGroup } from '../ScaffolderFilter/ScaffolderFilter';
 import SearchToolbar from '../SearchToolbar/SearchToolbar';
 import { TemplateCard } from '../TemplateCard';
-import { registerComponentRouteRef } from '../../routes';
 
 const useStyles = makeStyles(theme => ({
   contentWrapper: {
@@ -174,8 +174,9 @@ export const ScaffolderPageContents = () => {
             <ItemCardGrid>
               {matchingEntities &&
                 matchingEntities?.length > 0 &&
-                matchingEntities.map(template => (
+                matchingEntities.map((template, i) => (
                   <TemplateCard
+                    key={i}
                     template={template}
                     deprecated={template.apiVersion === 'backstage.io/v1alpha1'}
                   />

plugins/scaffolder/src/components/TemplatePage/TemplatePage.tsx

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { JsonObject, JsonValue } from '@backstage/config';
 import {
   Content,
   errorApiRef,
@@ -27,14 +28,13 @@ import { LinearProgress } from '@material-ui/core';
 import { FieldValidation, FormValidation, IChangeEvent } from '@rjsf/core';
 import parseGitUrl from 'git-url-parse';
 import React, { useCallback, useState } from 'react';
-import { generatePath, useNavigate, Navigate } from 'react-router';
+import { generatePath, Navigate, useNavigate } from 'react-router';
 import { useParams } from 'react-router-dom';
 import { useAsync } from 'react-use';
 import { scaffolderApiRef } from '../../api';
+import { FieldExtensionOptions } from '../../extensions';
 import { rootRouteRef } from '../../routes';
 import { MultistepJsonForm } from '../MultistepJsonForm';
-import { JsonObject, JsonValue } from '@backstage/config';
-import { FieldExtensionOptions } from '../../extensions';
 
 const useTemplateParameterSchema = (templateName: string) => {
   const scaffolderApi = useApi(scaffolderApiRef);

plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.test.tsx

@@ -0,0 +1,138 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Entity } from '@backstage/catalog-model';
+import { ApiProvider, ApiRegistry } from '@backstage/core';
+import { CatalogApi, catalogApiRef } from '@backstage/plugin-catalog-react';
+import { renderInTestApp } from '@backstage/test-utils';
+import { FieldProps } from '@rjsf/core';
+import userEvent from '@testing-library/user-event';
+import React from 'react';
+import { EntityPicker } from './EntityPicker';
+
+const makeEntity = (kind: string, namespace: string, name: string): Entity => ({
+  apiVersion: 'backstage.io/v1beta1',
+  kind,
+  metadata: { namespace, name },
+});
+
+describe('<EntityPicker />', () => {
+  let entities: Entity[];
+  const onChange = jest.fn();
+  const schema = {};
+  const required = false;
+  let uiSchema: {
+    'ui:options': { allowedKinds?: string[]; defaultKind?: string };
+  };
+  const rawErrors: string[] = [];
+  const formData = undefined;
+
+  let props: FieldProps;
+
+  const catalogApi: jest.Mocked<CatalogApi> = {
+    getLocationById: jest.fn(),
+    getEntityByName: jest.fn(),
+    getEntities: jest.fn(async () => ({ items: entities })),
+    addLocation: jest.fn(),
+    getLocationByEntity: jest.fn(),
+    removeEntityByUid: jest.fn(),
+  } as any;
+  let Wrapper: React.ComponentType;
+
+  beforeEach(() => {
+    const apis = ApiRegistry.with(catalogApiRef, catalogApi);
+    entities = [
+      makeEntity('Group', 'default', 'team-a'),
+      makeEntity('Group', 'default', 'squad-b'),
+    ];
+
+    Wrapper = ({ children }: { children?: React.ReactNode }) => (
+      <ApiProvider apis={apis}>{children}</ApiProvider>
+    );
+  });
+
+  afterEach(() => jest.resetAllMocks());
+
+  describe('without allowedKinds', () => {
+    beforeEach(() => {
+      uiSchema = { 'ui:options': {} };
+      props = ({
+        onChange,
+        schema,
+        required,
+        uiSchema,
+        rawErrors,
+        formData,
+      } as unknown) as FieldProps<any>;
+
+      catalogApi.getEntities.mockResolvedValue({ items: entities });
+    });
+
+    it('searches for all entities', async () => {
+      await renderInTestApp(
+        <Wrapper>
+          <EntityPicker {...props} />
+        </Wrapper>,
+      );
+
+      expect(catalogApi.getEntities).toHaveBeenCalledWith(undefined);
+    });
+
+    it('updates even if there is not an exact match', async () => {
+      const { getByLabelText } = await renderInTestApp(
+        <Wrapper>
+          <EntityPicker {...props} />
+        </Wrapper>,
+      );
+      const input = getByLabelText('Entity');
+
+      userEvent.type(input, 'squ');
+      input.blur();
+
+      expect(onChange).toHaveBeenCalledWith('squ');
+    });
+  });
+
+  describe('with allowedKinds', () => {
+    beforeEach(() => {
+      uiSchema = { 'ui:options': { allowedKinds: ['User'] } };
+      props = ({
+        onChange,
+        schema,
+        required,
+        uiSchema,
+        rawErrors,
+        formData,
+      } as unknown) as FieldProps<any>;
+
+      catalogApi.getEntities.mockResolvedValue({ items: entities });
+    });
+
+    it('searches for users and groups', async () => {
+      await renderInTestApp(
+        <Wrapper>
+          <EntityPicker {...props} />
+        </Wrapper>,
+      );
+
+      expect(catalogApi.getEntities).toHaveBeenCalledWith({
+        filter: {
+          kind: ['User'],
+        },
+      });
+    });
+  });
+});

plugins/scaffolder/src/components/fields/EntityPicker/EntityPicker.tsx

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { useApi } from '@backstage/core';
+import {
+  catalogApiRef,
+  formatEntityRefTitle,
+} from '@backstage/plugin-catalog-react';
+import { TextField } from '@material-ui/core';
+import FormControl from '@material-ui/core/FormControl';
+import Autocomplete from '@material-ui/lab/Autocomplete';
+import { FieldProps } from '@rjsf/core';
+import React from 'react';
+import { useAsync } from 'react-use';
+
+export const EntityPicker = ({
+  onChange,
+  schema: { title = 'Entity', description = 'An entity from the catalog' },
+  required,
+  uiSchema,
+  rawErrors,
+  formData,
+}: FieldProps<string>) => {
+  const allowedKinds = uiSchema['ui:options']?.allowedKinds as string[];
+  const defaultKind = uiSchema['ui:options']?.defaultKind as string | undefined;
+  const catalogApi = useApi(catalogApiRef);
+
+  const { value: entities, loading } = useAsync(() =>
+    catalogApi.getEntities(
+      allowedKinds ? { filter: { kind: allowedKinds } } : undefined,
+    ),
+  );
+
+  const entityRefs = entities?.items.map(e =>
+    formatEntityRefTitle(e, { defaultKind }),
+  );
+
+  const onSelect = (_: any, value: string | null) => {
+    onChange(value || '');
+  };
+
+  return (
+    <FormControl
+      margin="normal"
+      required={required}
+      error={rawErrors?.length > 0 && !formData}
+    >
+      <Autocomplete
+        value={(formData as string) || ''}
+        loading={loading}
+        onChange={onSelect}
+        options={entityRefs || []}
+        autoSelect
+        freeSolo
+        renderInput={params => (
+          <TextField
+            {...params}
+            label={title}
+            margin="normal"
+            helperText={description}
+            variant="outlined"
+            required={required}
+            InputProps={params.InputProps}
+          />
+        )}
+      />
+    </FormControl>
+  );
+};

plugins/scaffolder/src/components/fields/EntityPicker/index.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export { EntityPicker } from './EntityPicker';

plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.test.tsx

@@ -14,14 +14,12 @@
  * limitations under the License.
  */
 
-import React from 'react';
+import { Entity } from '@backstage/catalog-model';
 import { ApiProvider, ApiRegistry } from '@backstage/core';
 import { CatalogApi, catalogApiRef } from '@backstage/plugin-catalog-react';
 import { renderInTestApp } from '@backstage/test-utils';
-import userEvent from '@testing-library/user-event';
-import { Entity } from '@backstage/catalog-model';
 import { FieldProps } from '@rjsf/core';
-
+import React from 'react';
 import { OwnerPicker } from './OwnerPicker';
 
 const makeEntity = (kind: string, namespace: string, name: string): Entity => ({
@@ -93,20 +91,6 @@ describe('<OwnerPicker />', () => {
         },
       });
     });
-
-    it('updates even if there is not an exact match', async () => {
-      const { getByLabelText } = await renderInTestApp(
-        <Wrapper>
-          <OwnerPicker {...props} />
-        </Wrapper>,
-      );
-      const input = getByLabelText('Owner');
-
-      userEvent.type(input, 'squ');
-      input.blur();
-
-      expect(onChange).toHaveBeenCalledWith('squ');
-    });
   });
 
   describe('with allowedKinds', () => {

plugins/scaffolder/src/components/fields/OwnerPicker/OwnerPicker.tsx

@@ -13,81 +13,31 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import React from 'react';
 import { FieldProps } from '@rjsf/core';
-import { catalogApiRef } from '@backstage/plugin-catalog-react';
-import { useApi } from '@backstage/core';
-import { useAsync } from 'react-use';
-import Autocomplete from '@material-ui/lab/Autocomplete';
-import FormControl from '@material-ui/core/FormControl';
-import { Entity } from '@backstage/catalog-model';
-import { TextField } from '@material-ui/core';
-
-const entityRef = (entity: Entity | undefined): string => {
-  if (!entity) {
-    return '';
-  }
-  const {
-    kind,
-    metadata: { namespace, name },
-  } = entity;
-
-  const namespacePart =
-    !namespace || namespace === 'default' ? '' : `${namespace}/`;
-  const kindPart = kind.toLowerCase() === 'group' ? '' : `${kind}:`;
-
-  return `${kindPart}${namespacePart}${name}`;
-};
+import React from 'react';
+import { EntityPicker } from '../EntityPicker';
 
 export const OwnerPicker = ({
-  onChange,
   schema: { title = 'Owner', description = 'The owner of the component' },
-  required,
   uiSchema,
-  rawErrors,
-  formData,
+  ...props
 }: FieldProps<string>) => {
-  const allowedKinds = (uiSchema['ui:options']?.allowedKinds || [
-    'Group',
-    'User',
-  ]) as string[];
-  const catalogApi = useApi(catalogApiRef);
-
-  const { value: owners, loading } = useAsync(() =>
-    catalogApi.getEntities({ filter: { kind: allowedKinds } }),
-  );
-
-  const ownerRefs = owners?.items.map(entityRef);
-
-  const onSelect = (_: any, value: string | null) => {
-    onChange(value || '');
+  const ownerUiSchema = {
+    ...uiSchema,
+    'ui:options': {
+      allowedKinds: (uiSchema['ui:options']?.allowedKinds || [
+        'Group',
+        'User',
+      ]) as string[],
+      defaultKind: 'Group',
+    },
   };
 
   return (
-    <FormControl
-      margin="normal"
-      required={required}
-      error={rawErrors?.length > 0 && !formData}
-    >
-      <Autocomplete
-        value={(formData as string) || ''}
-        loading={loading}
-        onChange={onSelect}
-        options={ownerRefs || []}
-        autoSelect
-        freeSolo
-        renderInput={params => (
-          <TextField
-            {...params}
-            label={title}
-            margin="normal"
-            helperText={description}
-            variant="outlined"
-            required={required}
-            InputProps={params.InputProps}
-          />
-        )}
-      />
-    </FormControl>
+    <EntityPicker
+      {...props}
+      schema={{ title, description }}
+      uiSchema={ownerUiSchema}
+    />
   );
 };

plugins/scaffolder/src/components/fields/OwnerPicker/index.ts

@@ -13,4 +13,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export * from './OwnerPicker';
+export { OwnerPicker } from './OwnerPicker';

plugins/scaffolder/src/components/fields/index.ts

@@ -13,5 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export * from './RepoUrlPicker';
+export * from './EntityPicker';
 export * from './OwnerPicker';
+export * from './RepoUrlPicker';

plugins/scaffolder/src/extensions/default.ts

@@ -13,14 +13,19 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { EntityPicker } from '../components/fields/EntityPicker';
 import { OwnerPicker } from '../components/fields/OwnerPicker';
 import {
-  RepoUrlPicker,
   repoPickerValidation,
+  RepoUrlPicker,
 } from '../components/fields/RepoUrlPicker';
 import { FieldExtensionOptions } from './types';
 
 export const DEFAULT_SCAFFOLDER_FIELD_EXTENSIONS: FieldExtensionOptions[] = [
+  {
+    component: EntityPicker,
+    name: 'EntityPicker',
+  },
   {
     component: RepoUrlPicker,
     name: 'RepoUrlPicker',

plugins/scaffolder/src/index.ts

@@ -14,13 +14,14 @@
  * limitations under the License.
  */
 
+export { scaffolderApiRef, ScaffolderClient } from './api';
+export type { ScaffolderApi } from './api';
+export { ScaffolderFieldExtensions } from './extensions';
 export {
-  scaffolderPlugin,
-  scaffolderPlugin as plugin,
-  ScaffolderPage,
+  EntityPickerFieldExtension,
   OwnerPickerFieldExtension,
   RepoUrlPickerFieldExtension,
+  ScaffolderPage,
+  scaffolderPlugin as plugin,
+  scaffolderPlugin,
 } from './plugin';
-export { ScaffolderFieldExtensions } from './extensions';
-export type { ScaffolderApi } from './api';
-export { ScaffolderClient, scaffolderApiRef } from './api';

plugins/scaffolder/src/plugin.ts

@@ -21,15 +21,16 @@ import {
   discoveryApiRef,
   identityApiRef,
 } from '@backstage/core';
-import { OwnerPicker } from './components/fields/OwnerPicker';
-import {
-  RepoUrlPicker,
-  repoPickerValidation,
-} from './components/fields/RepoUrlPicker';
 import { scmIntegrationsApiRef } from '@backstage/integration-react';
 import { scaffolderApiRef, ScaffolderClient } from './api';
+import { EntityPicker } from './components/fields/EntityPicker';
+import { OwnerPicker } from './components/fields/OwnerPicker';
+import {
+  repoPickerValidation,
+  RepoUrlPicker,
+} from './components/fields/RepoUrlPicker';
 import { createScaffolderFieldExtension } from './extensions';
-import { rootRouteRef, registerComponentRouteRef } from './routes';
+import { registerComponentRouteRef, rootRouteRef } from './routes';
 
 export const scaffolderPlugin = createPlugin({
   id: 'scaffolder',
@@ -53,6 +54,13 @@ export const scaffolderPlugin = createPlugin({
   },
 });
 
+export const EntityPickerFieldExtension = scaffolderPlugin.provide(
+  createScaffolderFieldExtension({
+    component: EntityPicker,
+    name: 'EntityPicker',
+  }),
+);
+
 export const RepoUrlPickerFieldExtension = scaffolderPlugin.provide(
   createScaffolderFieldExtension({
     component: RepoUrlPicker,