Merge branch 'backstage:master' into techdocs-config-md

docs/features/software-catalog/audit-events.md

@@ -0,0 +1,49 @@
+---
+id: audit-events
+title: Audit Events
+description: Tracking access to your Software Catalog.
+---
+
+The Catalog backend emits audit events for various operations. Events are grouped logically by `eventId`, with `subEventId` providing further distinction within an operation group.
+
+## Entity Events
+
+- **`entity-fetch`**: Retrieves entities.
+- **Note:** By default, "low" severity audit events like `entity-fetch` aren't logged because they map to the "debug" level, while Backstage defaults to "info" level logging. To see `entity-fetch` events, update your `app-config.yaml` by setting `backend.auditor.severityLogLevelMappings.low: info`. See the [Auditor Service documentation](https://backstage.io/docs/backend-system/core-services/auditor/#severity-levels-and-default-mappings) for details on severity mappings.
+
+  Filter on `queryType`.
+
+  - **`all`**: Fetching all entities. (GET `/entities`)
+  - **`by-id`**: Fetching a single entity using its UID. (GET `/entities/by-uid/:uid`)
+  - **`by-name`**: Fetching a single entity using its kind, namespace, and name. (GET `/entities/by-name/:kind/:namespace/:name`)
+  - **`by-query`**: Fetching multiple entities using a filter query. (GET `/entities/by-query`)
+  - **`by-refs`**: Fetching a batch of entities by their entity refs. (POST `/entities/by-refs`)
+  - **`ancestry`**: Fetching the ancestry of an entity. (GET `/entities/by-name/:kind/:namespace/:name/ancestry`)
+
+- **`entity-mutate`**: Modifies entities.
+
+  Filter on `actionType`.
+
+  - **`delete`**: Deleting a single entity. Note: this will not be a permanent deletion and the entity will be restored if the parent location is still present in the catalog. (DELETE `/entities/by-uid/:uid`)
+  - **`refresh`**: Scheduling an entity refresh. (POST `/entities/refresh`)
+
+- **`entity-validate`**: Validates an entity. (POST `/entities/validate`)
+
+- **`entity-facets`**: Retrieves entity facets. (GET `/entity-facets`)
+
+## Location Events
+
+- **`location-fetch`**: Retrieves locations.
+
+  Filter on `actionType`.
+
+  - **`all`**: Fetching all locations. (GET `/locations`)
+  - **`by-id`**: Fetching a single location by ID. (GET `/locations/:id`)
+  - **`by-entity`**: Fetching locations associated with an entity ref. (GET `/locations/by-entity`)
+
+- **`location-mutate`**: Modifies locations.
+
+  - **`create`**: Creating a new location. (POST `/locations`)
+  - **`delete`**: Deleting a location and its associated entities. (DELETE `/locations/:id`)
+
+- **`location-analyze`**: Analyzes a location. (POST `/locations/analyze`)

docs/features/software-catalog/extending-the-model.md

@@ -596,7 +596,7 @@ import {
   coreServices,
   createBackendModule,
 } from '@backstage/backend-plugin-api';
-import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node/alpha';
+import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node';
 /* highlight-add-next-line */
 import { FoobarEntitiesProcessor } from './providers';
 

docs/features/software-catalog/external-integrations.md

@@ -294,7 +294,7 @@ import {
   coreServices,
   createBackendModule,
 } from '@backstage/backend-plugin-api';
-import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node/alpha';
+import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node';
 import { FrobsProvider } from './path/to/class';
 
 export const catalogModuleFrobsProvider = createBackendModule({
@@ -737,7 +737,7 @@ import {
   coreServices,
   createBackendModule,
 } from '@backstage/backend-plugin-api';
-import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node/alpha';
+import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node';
 import { SystemXReaderProcessor } from '../path/to/class';
 
 export const catalogModuleSystemXReaderProcessor = createBackendModule({

docs/features/software-templates/audit-events.md

@@ -0,0 +1,32 @@
+---
+id: audit-events
+title: Audit Events
+description: Tracking access to your Scaffolder.
+---
+
+The Scaffolder backend emits audit events for various operations. Events are grouped logically by `eventId`, with `subEventId` providing further distinction when needed.
+
+## Template Events
+
+- **`template-parameter-schema`**: Retrieves template parameter schemas. (GET `/v2/templates/:namespace/:kind/:name/parameter-schema`)
+
+## Action Events
+
+- **`action-fetch`**: Retrieves installed actions. (GET `/v2/actions`)
+
+## Task Events
+
+- **`task`**: Operations related to Scaffolder tasks.
+
+  Filter on `actionType`.
+
+  - **`create`**: Creates a new task. (POST `/v2/tasks`)
+  - **`list`**: Fetches details of all tasks. (GET `/v2/tasks`)
+  - **`get`**: Fetches details of a specific task. (GET `/v2/tasks/:taskId`)
+  - **`cancel`**: Cancels a running task. (POST `/v2/tasks/:taskId/cancel`)
+  - **`retry`**: Retries a failed task. (POST `/v2/tasks/:taskId/retry`)
+  - **`stream`**: Retrieves a stream of task logs. (GET `/v2/tasks/:taskId/eventstream`)
+  - **`events`**: Retrieves a snapshot of task logs. (GET `/v2/tasks/:taskId/events`)
+  - **`dry-run`**: Creates a dry-run task. (POST `/v2/dry-run`) All audit logs for events associated with dry runs have the `meta.isDryLog` flag set to `true`.
+  - **`stale-cancel`**: Automated cancellation of stale tasks.
+  - **`execute`**: Tracks the initiation and completion of a real scaffolder task execution. This event will not occur during dry runs.

docs/features/software-templates/writing-custom-actions.md

@@ -91,8 +91,8 @@ The `createTemplateAction` takes an object which specifies the following:
   may ship with the `scaffolder-backend` plugin.
 - `description` - An optional field to describe the purpose of the action. This will populate in the `/create/actions`
   endpoint.
-- `schema.input` - A `zod` or JSON schema object for input values to your function
-- `schema.output` - A `zod` or JSON schema object for values which are output from the
+- `schema.input` - A `zod` schema object for input values to your function
+- `schema.output` - A `zod` schema object for values which are output from the
   function using `ctx.output`
 - `handler` - the actual code which is run as part of the action, with a context
 
@@ -195,7 +195,7 @@ argument. It looks like the following:
   executed successfully on the previous run.
 - `ctx.logger` - a [LoggerService](../../backend-system/core-services/logger.md) instance for additional logging inside your action
 - `ctx.workspacePath` - a string of the working directory of the template run
-- `ctx.input` - an object which should match the `zod` or JSON schema provided in the
+- `ctx.input` - an object which should match the `zod` schema provided in the
   `schema.input` part of the action definition
 - `ctx.output` - a function which you can call to set outputs that match the
   `zod` schema in `schema.output` for ex. `ctx.output('downloadUrl', myDownloadUrl)`