# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for WhatsUp Gold Device Role API
  version: 1.0.0
extends: openapi/progress-software-devicerole-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 16
- target: $.paths['/api/v1/device-role/{roleId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a device role
      effect: read
      questions:
      - What does a specific device role in WhatsUp Gold contain?
      - Can I view one device role's summary information?
      instructions:
      - text: Show device role {roleId}.
        slots:
          roleId: path.roleId
      - text: Get role {roleId} with the {view} view.
        slots:
          roleId: path.roleId
          view: query.view
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/{roleId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a device role from the library
      effect: destructive
      questions:
      - How do I remove a custom device role from the library?
      - Is deleting a device role permanent?
      instructions:
      - text: Delete device role {roleId} from the library.
        slots:
          roleId: path.roleId
      - text: Remove role {roleId}.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/{roleId}/config/template'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the config template of a device role
      effect: read
      questions:
      - Can I export one device role's configuration template for copying to another system?
      - What template options control how much of a single role is included?
      instructions:
      - text: Get the config template for role {roleId} with options {options}.
        slots:
          roleId: path.roleId
          options: query.options
      - text: Export the transfer template of device role {roleId}.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/{roleId}/enable'].put
  update:
    x-apievangelist-phrasing:
      intent: Enable a device role
      effect: write
      questions:
      - How do I turn a disabled device role back on?
      - Can I make a role available for use again?
      instructions:
      - text: Enable device role {roleId}.
        slots:
          roleId: path.roleId
      - text: Turn on role {roleId} so it can be used.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/{roleId}/disable'].put
  update:
    x-apievangelist-phrasing:
      intent: Disable a device role
      effect: write
      questions:
      - Can I stop a device role from being used without deleting it?
      - What happens when I disable a role?
      instructions:
      - text: Disable device role {roleId}.
        slots:
          roleId: path.roleId
      - text: Stop role {roleId} from being used.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/{roleId}/restore'].put
  update:
    x-apievangelist-phrasing:
      intent: Restore a system role to defaults
      effect: write
      questions:
      - How do I reset a built-in device role to its shipped defaults?
      - Can I undo my customizations to a system role?
      instructions:
      - text: Restore system role {roleId} to shipped defaults.
        slots:
          roleId: path.roleId
      - text: Reset the built-in role {roleId}.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/{roleId}/assignments/-'].get
  update:
    x-apievangelist-phrasing:
      intent: List devices assigned a role
      effect: read
      questions:
      - Which devices is a particular role assigned to?
      - Can I filter the devices for one role's assignments?
      instructions:
      - text: List devices assigned role {roleId}.
        slots:
          roleId: path.roleId
      - text: Show assignments of role {roleId} for devices matching {deviceFilter}.
        slots:
          roleId: path.roleId
          deviceFilter: query.deviceFilter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/-/assignments/-'].get
  update:
    x-apievangelist-phrasing:
      intent: List all device role assignments
      effect: read
      questions:
      - What roles are assigned to every device across the system?
      - Can I include roles that aren't assigned to any device?
      instructions:
      - text: List all role assignments for {kind} roles.
        slots:
          kind: query.kind
      - text: List every device role assignment, including unassigned roles.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/-'].get
  update:
    x-apievangelist-phrasing:
      intent: List device roles
      effect: read
      questions:
      - Which device roles exist in my library?
      - Can I list only enabled roles of a certain kind?
      instructions:
      - text: List device roles named {name}.
        slots:
          name: query.name
      - text: Search device roles for {search}, enabled only.
        slots:
          search: query.search
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/-/config/template'].get
  update:
    x-apievangelist-phrasing:
      intent: Get templates for many device roles
      effect: read
      questions:
      - Can I pull configuration templates for a whole set of roles at once?
      - What bulk template export options exist for roles of a given source?
      instructions:
      - text: Get role templates for all {kind} roles.
        slots:
          kind: query.kind
      - text: Fetch templates for roles from source {source} with options {options}.
        slots:
          source: query.source
          options: query.options
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/-/config/template'].patch
  update:
    x-apievangelist-phrasing:
      intent: Apply multiple device role templates
      effect: write
      questions:
      - How do I apply a batch of role templates to this system?
      - Can several device role templates be applied in one call?
      instructions:
      - text: 'Apply these role templates: {templates}.'
        slots:
          templates: requestBody.templates
      - text: Apply templates {templates} with options {options}.
        slots:
          templates: requestBody.templates
          options: requestBody.options
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/-/config/export/content'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview the contents of an export package
      effect: read
      questions:
      - Before exporting, can I see what roles, monitors and icons a package would contain?
      - What would end up inventoried in an export package with my chosen options?
      instructions:
      - text: Inventory the export package {pkg} before generating it.
        slots:
          pkg: requestBody.pkg
      - text: Preview package {pkg} contents for roles {roles}.
        slots:
          pkg: requestBody.pkg
          roles: requestBody.roles
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/-/config/export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export roles as a package for another system
      effect: write
      questions:
      - How do I move device roles to another WhatsUp Gold system?
      - Can I sign the exported role package with keys?
      instructions:
      - text: Generate export package {pkg} with roles {roles}.
        slots:
          pkg: requestBody.pkg
          roles: requestBody.roles
      - text: Build a delivery package {pkg} including monitors {monitors}.
        slots:
          pkg: requestBody.pkg
          monitors: requestBody.monitors
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/-/config/import/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify a role package before import
      effect: read
      questions:
      - Can I check an incoming role package before importing it?
      - What's inside a package someone sent me?
      instructions:
      - text: Verify package {pkg} without applying it.
        slots:
          pkg: requestBody.pkg
      - text: Inventory the contents of import package {pkg}.
        slots:
          pkg: requestBody.pkg
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/-/config/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import and apply a role package
      effect: write
      questions:
      - How do I import a device role package exported from another system?
      - Can I choose which parts of a package get applied on import?
      instructions:
      - text: Import and apply package {pkg}.
        slots:
          pkg: requestBody.pkg
      - text: Apply package {pkg} using apply settings {apply}.
        slots:
          pkg: requestBody.pkg
          apply: requestBody.apply
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-role/-/percentVariables'].get
  update:
    x-apievangelist-phrasing:
      intent: List percent variables by type
      effect: read
      questions:
      - What percent variables are available for device roles?
      - Can I list percent variables of only one type?
      instructions:
      - text: List percent variables of type {choice}.
        slots:
          choice: query.choice
      - text: Show all available percent variables.
      method: generated
      generated: '2026-10-01'