Powered by

# URL Aliases

# Concepts

What is URL Alias?
A URL Alias is a custom, stable name that acts as a reference to a specific Agent and Agent Version. It functions as a bridge between your external applications and the Purple Fabric’s agents.

Why use URL Aliases?
Agents are frequently modified and updated, creating new version IDs. Without an alias, every time you modify an agent to a new version, you would need to manually update the API endpoints in every application that integrates with it.

URL Aliases enables you to decouple the integration URL from the specific agent version.

Key Benefits:

  • Seamless Transitions: When you modify an agent, you can simply update the alias to point to the new version. Your third-party applications continue to work without any code changes.
  • Stable Integration: Your API endpoints remain constant, using the Alias Name rather than a changing Asset ID.

# How-To Guide

# Accessing URL Aliases

  1. Log in to the platform.
  2. Navigate to the Admin module.
  3. Click on the URL Aliases component.
  4. You will see a list of existing aliases displaying: Alias Name, Mapped Agent, Agent Version, Modified At, and Owner.

# Creating a New Alias

  1. Click the Create new button.
  2. Alias Name: Enter a unique name for your alias (Min 6, Max 20 characters).
    • Note: Alphanumeric characters and basic special characters are allowed.
  3. Mapped Agent: Select the specific Agent you wish to map.
  4. Agent Version: Select the specific version of the agent you want this alias to use.
  5. Click Submit to save.

# Updating an Alias (Modifying Agents)

Scenario: You have modified your agent and want your live application to use the new version.

  1. Click on the specific URL Alias name in the list.
  2. This will open the Alias Detail Page.
  3. Click the Edit button.
  4. Change the Agent Version dropdown to the new desired version.
  5. Click Submit.

Result: Any application calling this alias will now immediately interact with the new version.

# Downloading API Specifications

To integrate the aliased agent into a third-party application, you need the OpenAPI specification for the specific version mapped to the alias.

  1. Click on the URL Alias in the list to open the Detail Page.
  2. Locate the menu (three vertical dots) and click Download API.

This will download the API specification specifically for the version currently mapped to this alias in JSON format.

# Deleting an Alias

  1. Click on the URL Alias in the list to open the Detail Page.
  2. Locate the menu and select the Delete option.
    The selected URL Alias is deleted

# FAQs

Q: Can I rename an alias after I create it?
A: No. Once an alias is created, the name is fixed to ensure link stability. If you need a different name, you must delete the existing alias and create a new one.

Q: Who can create or edit aliases?
A: Standard Users and Tenant Admins can create and edit aliases.

Q: What happens if I modify an agent version while an alias is pointing to it?
A: The alias points to a specific Version ID. If you modify an agent, a new Version ID is usually created. You must go to the Alias settings and update it to point to the new version for the changes to take effect in your integration.

Q: Can we create URL aliases for all kinds of agents?
A: URL Aliases are only applicable to Automation agents and not Conversation agents.

# Troubleshooting

Error / Issue Probable Cause Resolution
"Alias name already exists, please try again with new alias name" (Error Code: 400) The alias name you entered is already assigned to another agent or version in this workspace. Enter a different, unique name and click Submit again.
Cannot access URL Aliases menu Your user account does not have the required permissions. Ensure you are logged in as a Tenant Admin.
"Unexpected error value: ... code: 400" (Validation Error) The alias name does not meet the length requirements (6-20 characters) or contains invalid characters. Ensure the alias name is between 6 and 20 characters long and try again.
Cannot Edit Alias Name The UI prevents editing the name field. This is by design to prevent breaking existing integrations. To change a name, delete the alias and create a new one.
Alias points to old content The agent was modified, but the alias was not updated to the new version. Click on the Alias, click Edit, and select the latest Agent Version.

# Limitations

  • Asset type: URL Aliases are only applicable to Automation agents and not Conversation agents.