Custom UI components and filters - Red Hat Ansible Automation Platform 2.7

`AAPTokenField`

The AAPTokenField is a secure authentication field used in backstage scaffolder templates. It automatically fetches and stores an Ansible Automation Platform OAuth2 token, which is then available for all rhaap:* actions, enabling seamless authentication.

AAPTokenField Properties

The following table details the field's properties for use in a template's properties section.


Property	Type	Description
`title`	string	The label displayed in the UI (for example, "AAP Token"). Defaults to "AAP Token".
`description`	string	A short help text displayed below the input field.
`ui:field`	string	Must be set to `AAPTokenField`. This setting instructs Backstage to render a custom react component instead of a default input field.
`ui:backstage.review.show`	boolean	If `true`, this field appears in the Review step before scaffolding executes. The default value is `true`.

Authentication flow and token management

All rhaap:* actions require an OAuth2 token for authenticating with Ansible Automation Platform. The token is always stored in the Backstage secrets context as aapToken and referenced in template steps as ${{ secrets.aapToken }}.

How the token reaches the secrets context depends on the deployment model:

Ansible automation portal (Create Task): The portal automatically injects the token into secrets.aapToken when the user submits the form. You do not need to declare AAPTokenField in the template parameters — the token is handled transparently.
Ansible plug-ins for Red Hat Developer Hub: The standard Backstage scaffolder does not auto-inject the token. You must include AAPTokenField in the template parameters to trigger the OAuth popup and populate secrets.aapToken.

Important:

Starting in Ansible Backstage Plugins v2.2.0, the portal no longer passes the OAuth token in template form values. Do not use ${{ parameters.token }} in rhaap:* action steps — AAPTokenField stores a masked display value in form parameters. Always use ${{ secrets.aapToken }} to access the real OAuth token.

When the RHAAP auth provider is used, the token is referenced in the workflow steps as shown:

  - id: create-project
    action: rhaap:create-project
    input:
      token: ${{ secrets.aapToken }}
      # ... other inputs

Example

The following example shows how to declare AAPTokenField for Ansible plug-ins for Red Hat Developer Hub deployments. For Ansible automation portal deployments, the authentication section is optional.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: my-AAP-template
  title: Example AAP Template
spec:
  parameters:
    - title: Authentication
      properties:
        token:
          title: AAP Authentication Token
          type: string
          description: Oauth2 token
          ui:field: AAPTokenField
          ui:widget: hidden
          ui:backstage:
            review:
              show: false
  steps:
    - id: launch-job
      name: Launch AAP Job Template
      action: rhaap:launch-job-template
      input:
        token: ${{ secrets.aapToken }}
        ...

Error and validation handling

All rhaap:* actions include built-in validation and user-friendly error reporting:

Validation: If the token is missing or invalid, the action throws the error: "`Authorization token not provided`."
Error Messages: Actions catch API client errors, extracting and surfacing meaningful messages without exposing stack traces.
Workflow Safety: If a step fails due to authentication, subsequent steps are automatically skipped, ensuring a safe and predictable workflow.

`AAPResourcePicker`

AAPResourcePicker is a dynamic field for Backstage scaffolder templates. It fetches Ansible Automation Platform resources (like inventories or credentials) via the Ansible Automation Platform API, allowing users to select resources for their automation workflows.

AAPResourcePicker Properties

The following table details the essential properties for configuring the resource picker in a template’s properties section.


Property	Type	Description
`title`	string	The label displayed in the UI (for example, "Inventory").
`description`	string	A short help text shown below the field.
`ui:field`	string	Must be set to `AAPResourcePicker`.
`resource`	string	The specific Ansible Automation Platform (AAP) resource type to fetch and display (for example, `inventories`, `credentials`, or `organizations`).
`idKey`	string	The property name used to retrieve the resource ID (default: “id”).
`nameKey`	string	The property name used to display the resource name in the list (default: “name”).
`type`	string	Set to “array” for a multi-select field; omit this property for a single-select field.

Example

The following example demonstrates how to use the AAPResourcePicker to create a single-select field for choosing an Inventory.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: my-AAP-template
  title: Example AAP Template
spec:
  parameters:
    - title: Authentication
      properties:
        jobInventory:
          title: Inventory
          description: Select inventory
          resource: inventories
          ui:field: AAPResourcePicker
          default: DemoInventory

Custom filters

The plugins provide custom filters to extract specific properties from resource objects, which is essential for passing data between backstage steps.


Filter	Purpose	Example Usage
`resourceFilter`	Extracts a single, specific property from a resource object.	`$!{{ parameters.organization \| resourceFilter('name') }}`
`multiResourceFilter`	Extracts a specific property from multiple resource objects (when the input is an array).	`$!{{ parameters.organization \| multiResourceFilter('name') }}`