Roadie Backstage Plugins

If you need to customize how Okta users and groups are ingested into the Backstage catalog, you can implement your own entity provider by using the EntityProvider interface. You can choose between three main provider types:

1. OktaOrgEntityProvider: Loads both users and groups together.
2. OktaUserEntityProvider: Loads only users.
3. OktaGroupEntityProvider: Loads only groups.

Note: You must use either the default entity providers or your custom ones, not both simultaneously. To use a custom provider, you must register it as a Backstage module and add it to your backend using backend.add() while ensuring the default Okta provider is removed or commented out.

import { createBackendModule, coreServices } from '@backstage/backend-plugin-api';
import { oktaCatalogBackendEntityProviderFactoryExtensionPoint, EntityProviderFactory, OktaOrgEntityProvider } from '@roadiehq/catalog-backend-module-okta/new-backend';
import { Config } from '@backstage/config';

export const oktaOrgEntityProviderModule = createBackendModule({
  pluginId: 'catalog',
  moduleId: 'default-okta-org-entity-provider',
  register(env) {
    env.registerInit({
      deps: {
        provider: oktaCatalogBackendEntityProviderFactoryExtensionPoint,
        logger: coreServices.logger,
      },
      async init({ provider, logger }) {
        const factory: EntityProviderFactory = (oktaConfig: Config) =>
          OktaOrgEntityProvider.fromConfig(oktaConfig, {
            logger: logger,
            userNamingStrategy: 'strip-domain-email',
            groupNamingStrategy: 'kebab-case-name',
          });

        provider.setEntityProviderFactory(factory);
      },
    });
  },
});

// In packages/backend/src/index.ts:
// backend.add(import('@roadiehq/catalog-backend-module-okta/default-provider-factory')); // Remove/Comment this
backend.add(oktaOrgEntityProviderModule);

The Roadie RAG AI backend utilizes a retrieval pipeline to augment queries sent to configured LLMs.

Core Workflow

1. Retrieval: The pipeline retrieves information based on queries and other metadata.
2. Processing: Information is processed and sorted.
3. Augmentation: The processed data is added to the query prompt sent to the LLM.

Configuration Modes

• Full Pipeline: Retrieves and processes data to provide context to the LLM.
• Pass-through Mode: The pipeline runs without adding additional context, allowing users to interact with the configured LLMs directly.
• Customizable Implementation: The module is designed to be extended by injecting use-case specific implementations for:
  • Embeddings
  • Retrieval
  • Post-processing
  • Routing

Best Practices for Extension

To build a robust RAG pipeline, it is recommended to:

• Implement Routers: Use routers to define which specific retrievers should be used for different types of augmentation information.
• Use Post-processors: Implement post-processing logic to rerank, sort, and manipulate retrieved information before it reaches the LLM.

When using Backstage's experimental task recovery (spec.EXPERIMENTAL_recovery.EXPERIMENTAL_strategy: startOver), tasks that are interrupted are restarted from the beginning. This can cause non-idempotent actions (like creating a Jira ticket) to be duplicated.

To prevent this, use the idempotencyKey input. This wraps the request in a checkpoint:

• The request is executed at most once per task.
• On a restart, the cached response is returned instead of re-sending the request.

The idempotencyKey must be a stable and unique string within the template.

If idempotencyKey is omitted, the request will be sent every time the task runs.

steps:
  - id: create_jira_ticket
    name: Create Jira ticket
    action: http:backstage:request
    input:
      method: 'POST'
      path: '/proxy/jira/api/rest/api/latest/issue'
      idempotencyKey: 'jira.create.parent'
      headers:
        content-type: 'application/json'
      body:
        fields:
          project: { key: 'PROJ' }
          summary: 'Created from Backstage'
          issuetype: { name: 'Task' }

Instead of providing a full URL in the src prop, you can use srcFromAnnotation to pull an identifier from an entity's annotation and transform it into a full URL.

Use the transform prop to define how the annotation value is processed. The transform function receives (value, entity) where value is the annotation string and entity is the Backstage entity object.

Common transformation patterns include:

• Prefix only: Using wrapAnnotation('prefix') to prepend a base URL.
• Prefix and Suffix: Using wrapAnnotation('prefix', 'suffix') to wrap the value.
• Template: Using intoTemplate('url/with/${value}/suffix') to embed the value anywhere.
• Custom: A manual function for complex logic involving entity metadata.

Note: The resulting URL must be HTTPS and must be included in the iframe.allowList configuration.

import {
  EntityIFrameCard,
  wrapAnnotation,
  intoTemplate,
} from '@roadiehq/backstage-plugin-iframe';

// 1) Prefix only: https://host/prefix/${annotation_value}
<EntityIFrameCard
  srcFromAnnotation="grafana/dashboard-id"
  transform={wrapAnnotation('https://grafana.example.com/d/')}
/>

// 2) Prefix + suffix: https://host/foo/${annotation_value}/extra
<EntityIFrameCard
  srcFromAnnotation="my-org/widget-id"
  transform={wrapAnnotation('https://example.com/foo/', '/extra')}
/>

// 3) Free-form template
<EntityIFrameCard
  srcFromAnnotation="my-org/widget-id"
  transform={intoTemplate('https://example.com/foo/${value}/extra')}
/>

// 4) Custom transform using entity context
<EntityIFrameCard
  srcFromAnnotation="grafana/dashboard-id"
  transform={(value, entity) =>
    `https://grafana.example.com/d/${value}?var-service=${entity.metadata.name}`
  }
/>