Skip to main content
Documentation
Documentation
Administrator Guide
Last Updated: 2023-06-23
Register and Authenticate External Agents

Register and Authenticate External Agents

You might need to take additional steps to enable this feature based on your organization's subscription service agreement. Your organization is either on the Main Service Agreement (MSA) or the Universal Main Service Agreement (UMSA). To determine your organization's subscription service agreement:
  1. Select your profile avatar on Workday Community.
  2. Select
    Profile
    .
  3. On your profile page, select your organization's name, which is beneath your name and next to your job title.
  4. View your
    Subscription Service Agreement
     value.
If the value is:
UMSA is required for non-production and production tenants for Workday-Built agents. UMSA is not required for non-production tenants for self-built agents.
For information about how using agents impacts your Flex Credits, see: Workday Flex Credits Community page.
  • Security:
    • Agent Management Hub
       domain in the Agent System of Record functional area.
    • Manage Agents
       domain in the Agent System of Record functional area.
    • Set Up: Tenant Setup - Security
       domain in the System functional area.
You must use the Agent System of Record (ASOR) API to define and register external agents. You can use any API client of your preference to invoke the API.
Registration endpoints:
  • REST API Endpoint:
     https://us.agent.workday.com/asor/v1/agentDefinition.
  • Token Endpoint:
     https://us.agent.workday.com/auth/oauth2/<Tenant_Name>/token
  • Authorize Endpoint:
     https://us.agent.workday.com/auth/authorize/<Tenant_Name>?response_type=code&client_id=<client_id>&state=test3pagent1&redirect_uri=<redirect_uri>
  2. Find the Workday identifiers (WIDs) of the relevant Workday SOAP and REST APIs for the agent tools definition.
    As you retrieve WIDs for your APIs, you can also cross-reference these lists:
    1. Access the
      Create Custom Report
       task.
    2. Complete the report:
      Option
      Description
      Report Type
      Select
      Advanced
      .
      Optimized for Perform
      Clear this check box.
      Data Source
      Public Web Services
       for SOAP APIs and
      All Public Service Operations
       for REST APIs.
    3. Click
      OK
      .
    4. For SOAP APIs: On the
      Edit Custom Report
       page, on the
      Columns
       tab of the report definition, add these rows:
      Business Object
      Field
      Web Service
      Web Service
      Web Service Operation
      Web Service Operation Name
      Web Service Operation
      Workday ID
    5. For REST APIs: On the
      Edit Custom Report
       page, on the
      Columns
       tab of the report definition, add these rows:
      Business Object
      Field
      Service Operation
      Service
      Service Operation
      Name
      Service Operation
      Workday ID
    6. Save and run the report.
  3. Find the agent provider.
    Agent providers refer to who has built the agent and are displayed in the
    Built By
     field on the agent’s profile.
    1. Access the
      View Agent Provider
       task.
      Security:
      Setup: Agents
      domain in the Agent System of Record functional area.
    2. Use the Provider ID in your agent registration API call.
  4. Find the agent platform.
    Agent platforms refer to who has built the agent and are displayed in the
    Built On
     field on the agent’s profile.
    1. ccess the
      View Agent Platforms
       task.
      Security:
      Setup: Agents
      domain in the Agent System of Record functional area.
    2. Use the Platform ID in your agent registration API call.
    3. Call the ASOR REST API.
      Create a new request to register your agent using an external API client:
      Option
      Description
      Endpoint
      https://us.agent.workday.com/asor/v1/agentDefinition
      Operation
      POST
      Body
      Headers
      • Authorization: Bearer <token>
      • wd-agent-tenant-alias:<your tenant name>
After you successfully load your agent definition into Workday, you can verify that it is registered by viewing it in the
Agent Management Hub
:
  1. Access the
    Agent Management Hub
    .
  2. Click
    Agent Registry
     to display a list of your agents.
  3. Click an agent to display overview information for it.
Configure your agent in Workday.