From 35b55871187924d223289d81907aa7f458ffe4f0 Mon Sep 17 00:00:00 2001 From: Kacper Nowacki Date: Wed, 15 Feb 2023 17:31:38 +0100 Subject: [PATCH 1/2] Allow to change default document type of indexed files by catalog collator Signed-off-by: Kacper Nowacki --- .changeset/wet-pugs-exist.md | 5 +++ docs/features/search/how-to-guides.md | 43 +++++++++++++++++++ plugins/catalog-backend/api-report.md | 3 +- .../search/DefaultCatalogCollatorFactory.ts | 5 ++- 4 files changed, 54 insertions(+), 2 deletions(-) create mode 100644 .changeset/wet-pugs-exist.md diff --git a/.changeset/wet-pugs-exist.md b/.changeset/wet-pugs-exist.md new file mode 100644 index 0000000000..dbc2c735c9 --- /dev/null +++ b/.changeset/wet-pugs-exist.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +Added optional parameter `type` to `DefaultCatalogCollatorFactoryOptions` which allows to override default document type `software-catalog`. For more details, see [How to customize document type in the Software Catalog index](../docs/features/search/how-to-guides.md#how-to-customize-document-type-in-the-software-catalog-index). diff --git a/docs/features/search/how-to-guides.md b/docs/features/search/how-to-guides.md index b464168724..be8bac43fb 100644 --- a/docs/features/search/how-to-guides.md +++ b/docs/features/search/how-to-guides.md @@ -184,6 +184,49 @@ indexBuilder.addCollator({ As shown above, you can add a catalog entity filter to narrow down what catalog entities are indexed by the search engine. +## How to customize document type in the Software Catalog index + +In some cases you might want to have the ability to change the document type in which catalog entities will be indexed by catalog collator. +Such option gives a possibility to customize SearchPage results and filters depending on which document type you would like to see results for. + +You can achieve that by passing additional parameter `type` to the `DefaultCatalogCollatorFactory`. + +Let's say that you want to have two different document types for some entities. +Our example will cover a use case in which we want to: + +- Store entities of kind `User` or `Group` under document type `yourCustomDocumentType`, +- Store rest of entities under default document type `software-catalog` + +To achieve that you will have to remove `User` and `Group` from your previous collator `filter` and register new `DefaultCatalogCollatorFactory` with new parameter `type`. + +```diff +// packages/backend/src/plugins/search.ts + + indexBuilder.addCollator({ + schedule, + factory: DefaultCatalogCollatorFactory.fromConfig(env.config, { + discovery: env.discovery, + tokenManager: env.tokenManager, + filter: { +- kind: ['API', 'Component', 'Domain', 'Resource', 'System', 'Template', 'User', 'Group'], ++ kind: ['API', 'Component', 'Domain', 'Resource', 'System', 'Template'], + }, + }), + }); + ++ indexBuilder.addCollator({ ++ schedule, ++ factory: DefaultCatalogCollatorFactory.fromConfig(env.config, { ++ discovery: env.discovery, ++ tokenManager: env.tokenManager, ++ filter: { ++ kind: ['User', 'Group'], ++ }, ++ type: 'yourCustomDocumentType', ++ }), ++ }); +``` + ## How to customize search results highlighting styling The default highlighting styling for matched terms in search results is your diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index f15f6b9ba9..dcca23c069 100644 --- a/plugins/catalog-backend/api-report.md +++ b/plugins/catalog-backend/api-report.md @@ -368,7 +368,7 @@ export class DefaultCatalogCollatorFactory implements DocumentCollatorFactory { // (undocumented) getCollator(): Promise; // (undocumented) - readonly type = 'software-catalog'; + readonly type: string; // (undocumented) readonly visibilityPermission: Permission; } @@ -382,6 +382,7 @@ export type DefaultCatalogCollatorFactoryOptions = { batchSize?: number; catalogClient?: CatalogApi; entityTransformer?: CatalogCollatorEntityTransformer; + type?: string; }; export { DeferredEntity }; diff --git a/plugins/catalog-backend/src/search/DefaultCatalogCollatorFactory.ts b/plugins/catalog-backend/src/search/DefaultCatalogCollatorFactory.ts index 1c03836e51..fc5c465ccb 100644 --- a/plugins/catalog-backend/src/search/DefaultCatalogCollatorFactory.ts +++ b/plugins/catalog-backend/src/search/DefaultCatalogCollatorFactory.ts @@ -44,11 +44,12 @@ export type DefaultCatalogCollatorFactoryOptions = { batchSize?: number; catalogClient?: CatalogApi; entityTransformer?: CatalogCollatorEntityTransformer; + type?: string; }; /** @public */ export class DefaultCatalogCollatorFactory implements DocumentCollatorFactory { - public readonly type = 'software-catalog'; + public readonly type: string; public readonly visibilityPermission: Permission = catalogEntityReadPermission; @@ -75,6 +76,7 @@ export class DefaultCatalogCollatorFactory implements DocumentCollatorFactory { catalogClient, tokenManager, entityTransformer, + type, } = options; this.locationTemplate = @@ -86,6 +88,7 @@ export class DefaultCatalogCollatorFactory implements DocumentCollatorFactory { this.tokenManager = tokenManager; this.entityTransformer = entityTransformer ?? defaultCatalogCollatorEntityTransformer; + this.type = type ?? 'software-catalog'; } async getCollator(): Promise { From 5a2df6c0c83700a376059d31321725cd87b2aaa6 Mon Sep 17 00:00:00 2001 From: Kacper Nowacki Date: Wed, 1 Mar 2023 14:14:31 +0100 Subject: [PATCH 2/2] Change variable name to documentType Signed-off-by: Kacper Nowacki --- .changeset/wet-pugs-exist.md | 2 +- docs/features/search/how-to-guides.md | 6 +++--- plugins/catalog-backend/api-report.md | 2 +- .../src/search/DefaultCatalogCollatorFactory.ts | 6 +++--- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.changeset/wet-pugs-exist.md b/.changeset/wet-pugs-exist.md index dbc2c735c9..509fb19f8d 100644 --- a/.changeset/wet-pugs-exist.md +++ b/.changeset/wet-pugs-exist.md @@ -2,4 +2,4 @@ '@backstage/plugin-catalog-backend': patch --- -Added optional parameter `type` to `DefaultCatalogCollatorFactoryOptions` which allows to override default document type `software-catalog`. For more details, see [How to customize document type in the Software Catalog index](../docs/features/search/how-to-guides.md#how-to-customize-document-type-in-the-software-catalog-index). +Added optional parameter `documentType` to `DefaultCatalogCollatorFactoryOptions` which allows to override default document type `software-catalog`. For more details, see [How to customize document type in the Software Catalog index](../docs/features/search/how-to-guides.md#how-to-customize-document-type-in-the-software-catalog-index). diff --git a/docs/features/search/how-to-guides.md b/docs/features/search/how-to-guides.md index be8bac43fb..d2c8c537f2 100644 --- a/docs/features/search/how-to-guides.md +++ b/docs/features/search/how-to-guides.md @@ -189,7 +189,7 @@ entities are indexed by the search engine. In some cases you might want to have the ability to change the document type in which catalog entities will be indexed by catalog collator. Such option gives a possibility to customize SearchPage results and filters depending on which document type you would like to see results for. -You can achieve that by passing additional parameter `type` to the `DefaultCatalogCollatorFactory`. +You can achieve that by passing additional parameter `documentType` to the `DefaultCatalogCollatorFactory`. Let's say that you want to have two different document types for some entities. Our example will cover a use case in which we want to: @@ -197,7 +197,7 @@ Our example will cover a use case in which we want to: - Store entities of kind `User` or `Group` under document type `yourCustomDocumentType`, - Store rest of entities under default document type `software-catalog` -To achieve that you will have to remove `User` and `Group` from your previous collator `filter` and register new `DefaultCatalogCollatorFactory` with new parameter `type`. +To achieve that you will have to remove `User` and `Group` from your previous collator `filter` and register new `DefaultCatalogCollatorFactory` with new parameter `documentType`. ```diff // packages/backend/src/plugins/search.ts @@ -222,7 +222,7 @@ To achieve that you will have to remove `User` and `Group` from your previous co + filter: { + kind: ['User', 'Group'], + }, -+ type: 'yourCustomDocumentType', ++ documentType: 'yourCustomDocumentType', + }), + }); ``` diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index dcca23c069..78c883a912 100644 --- a/plugins/catalog-backend/api-report.md +++ b/plugins/catalog-backend/api-report.md @@ -382,7 +382,7 @@ export type DefaultCatalogCollatorFactoryOptions = { batchSize?: number; catalogClient?: CatalogApi; entityTransformer?: CatalogCollatorEntityTransformer; - type?: string; + documentType?: string; }; export { DeferredEntity }; diff --git a/plugins/catalog-backend/src/search/DefaultCatalogCollatorFactory.ts b/plugins/catalog-backend/src/search/DefaultCatalogCollatorFactory.ts index fc5c465ccb..07da2da03a 100644 --- a/plugins/catalog-backend/src/search/DefaultCatalogCollatorFactory.ts +++ b/plugins/catalog-backend/src/search/DefaultCatalogCollatorFactory.ts @@ -44,7 +44,7 @@ export type DefaultCatalogCollatorFactoryOptions = { batchSize?: number; catalogClient?: CatalogApi; entityTransformer?: CatalogCollatorEntityTransformer; - type?: string; + documentType?: string; }; /** @public */ @@ -76,7 +76,7 @@ export class DefaultCatalogCollatorFactory implements DocumentCollatorFactory { catalogClient, tokenManager, entityTransformer, - type, + documentType, } = options; this.locationTemplate = @@ -88,7 +88,7 @@ export class DefaultCatalogCollatorFactory implements DocumentCollatorFactory { this.tokenManager = tokenManager; this.entityTransformer = entityTransformer ?? defaultCatalogCollatorEntityTransformer; - this.type = type ?? 'software-catalog'; + this.type = documentType ?? 'software-catalog'; } async getCollator(): Promise {