Ayfie Personal Assistant is an advanced AI-powered web application that enables users to upload, analyze, and interact with data of almost any file format, including Office documents, PDFs and even images, facilitating queries and discussions related to the uploaded content.

Here are a few important concepts to be aware of when managing the standalone Personal Assistant application.

Ayfie Personal Assistant consists of two components, of which one, the part that includes the UI, is referred to as the Ayfie Personal Assistant Application. Since Azure Marketplace refers to both components as applications, this can lead to some confusion. It is thus important to understand that Ayfie Personal Assistant is made up of these two components:

• Storage - Ayfie Personal Assistant Storage: a static, one time installed, secure document storage environment.

• Application - Ayfie Personal Assistant Application: a dynamic UI component that will change over time as features are being updated or added

A resource groups is what is used to group and administrate customer resources in Azure. The two Ayfie components Ayfie Personal Assistant Storage and Ayfie Personal Assistant Application could be placed in one resource group together with other non-Ayfie resources, or in a resource group just by themselves, or split across two different resource groups. Further, these resource groups could be given any name one see fit. However, it is recommended that each of them are given a dedicated resource group and that they are not mixed with other resources. It is also recommended naming the resource groups rg-ayfie-pa-storage and rg-ayfie-pa-application. Using these exact named resource groups will simplify later upgrades to newer versions of Ayfie Personal Assistant as well as any later interactions with Ayfie Support.

Version upgrades are not done as “upgrades” but rather by uninstalling the old version and then installing the new version. As of version 2.9, Personal Assistant consists of two components (see above) and only the application component is “upgraded” (uninstalled and installed), the storage component is left as-is.

The URL to access Personal Assistant can either be a custom domain of your choosing (for instance pa.mycompany.com) or be whatever random URL provided by Azure AI services. The former approach is what is normally used. In either case, this has to be followed up whenever one upgrade to a new version of Personal Assistant, either by making sure to reuse the same Service Principle (the Entra ID application) or by updating the callback_url if one uses the default alphanumeric URL provided by Azure AI services.

The prerequisites come in two groups:

• System prerequisites - Obtain the required subscription rights to do the installation

• Admin user prerequisites - Obtain the required user permissions to run the install process

Consult Business Agent On-Premises - PrerequisitesPreview for details.

After completing all system and admin user prerequisites listed in the linked documentation above, one can proceed with the installation of Ayfie Personal Assistant.

The installation of Ayfie Personal Assistant consists of these operations that will be covered in the next few sections:

• Obtain and configure the storage component of Ayfie Personal Assistant

• Obtain and configure the application component of Ayfie Personal Assistant

• Post-Deployment configuration

1. Go to the Microsoft Azure Portal at https://portal.azure.com

2. In the search box enter Marketplace and select it from the search results

3. At the Marketplace page, use the Marketplace search box to search for “Ayfie Personal Assistant Storage”

4. Select the Ayfie Personal Assistant Storage from the search result

5. Chose plan “Storage” and then click the Create button

Once the Create Storage page appears, fill in the details:

Open

• Select the subscription from the dropdown (Ayfie Development in the example above)

• Create a new resource group (recommended for simple ) or select an existing one. The name rg-ayfie-pa-storage is recommended.

• Select one of the regions from the dropdown menu.

  • The region of storage component determines what laws and regulation that will govern the data being stored.

  • The region of the application component determines which language models that are available. Not all language models are available in all regions.

  • Even though it is possible to have the two components spread across two different regions, that is not recommended.

  • Customers from EU countries should for legal reasons select one of the two EU regions.

  • These are the best performing GPT-4 LLM by region at the time of this writing:

    • France Central (GPT-4 1106-Preview)

    • Sweden Central (GPT-4o)

    • UK South (GPT-4 1106-Preview)

    • Canada East (GPT-4 1106-Preview)

• Check the checkbox to verify you have been granted access to Azure OpenAI with selected subscription (circled in yellow above)

• Click the white Next or the blue Review + create button. This will take one to the Review + create page.

Open

• Review the summary. Go back and correct anything found to be wrong.

• Click the Create button at the bottom of the page when ready to deploy Ayfie Personal Assistant

It typically takes some 10-15 minutes for the Managed Application to deploy its more than 15 Azure resources.

This is the click route to obtain the Ayfie Personal Assistant Application:

Open

1. Go to the Microsoft Azure Portal at https://portal.azure.com

2. In the search box enter Marketplace and select it from the search results

3. Use the search box to look up the “Ayfie Personal Assistant” applications

4. Select the Ayfie Personal Assistant Application box

5. Select the number of users you want to license. Then click the Create button.

Open

To complete the creation of the Ayfie Personal Assistant Application component, one will visit these 4 page tabs one by one in the given order:

• Basic

• User Authentication

• Application Settings

• Review + create

The page title in the graphics below ends with Private Plan. As public offering is the only remaining option, the title will instead be Create N users, where N is the number of users one selected from the dropdown on the previous page.

Open

• Select the subscription from the dropdown (Ayfie Development in the example above).

• Create a new resource group (recommended) or select an existing one. The recommended name for the group is rg-ayfie-pa-application.

• Select the region. Normally one would select the same region as earlier selected for the storage component, but if this is done as part of an upgrade one may have to select another region if one as part of the upgrade is changing to a new language model that is not available in the same region.

• Select the storage resource group from earlier (that is rg-ayfie-pa-storage if one created it using the recommended name)

• Give the managed application a name, for instance the recommended name AyfiePersonalAssistant as in the example above.

• Click Next to get to the next page tab

Open

User access to Ayfie Personal Assistance is managed by Entra ID via the Service Principal created as one of the prerequisites.

• Note: If upgrading, make sure to use the exact same Enterprise Application as in for previous version, otherwise it may cause issues with stored documents and chat history

• Verify that one has selected a Service Principal by checking of the check box

• Click Next (circled in red) to get to the Authentication page

The Application Settings tab has the following optional settings:

• Custom Domain - Allows one to configure a Custom Domain that is to be used instead of a randomly generated URL when accessing the Personal Assistant, e.g., pa.company.com. The wizard allows setting the custom domain also for the backend/API - this is optional. If the corresponding checkbox is selected, the backend/API will be available under api-pa.company.com (red box)

• Model Advanced Configuration - Allows one to modify the deployment type and/or token quota (blue box)

Open

These settings are not possible to change post deployment. That would require one to uninstall and install as explained in section Upgrading to a Newer Version of Ayfie Personal Assistant.

When deploying Ayfie Personal Assistant one is always given an URL which users can use to access the frontend. This URL will adhere to the format: https://chat-ui.random-part.region-name.azurecontainerapps.io.

If one instead would like users to access the application with a specific custom URL, then do as described below, otherwise, click the Next button directly:

• Check the “Configure custom domain”

• Check the “Verify if you have access to the DNS record for your domain”

• Add the custom domain, e.g., pa.company.com to the input field

  • Note: This has to be made as a public DNS

• Optionally, you can decide if the backend/API will also be available under the custom domain by selecting the corresponding checkbox. If the “Use custom domain for backend/API” option is selected, the backend/API will be available under api-pa.company.com. This option is recommended if you are going to integrate any of the API endpoints into another system or if you are going to integrate Chatbots via the provided code snippets.

• Click the white Next or the blue Review + create button. This will take one to the Review + create page.

Deploy OpenAI models

Decide whether OpenAI models should be deployed alongside the application. By default, this option is selected. If you choose to skip deploying the models, you will need to deploy them manually and configure them within the application. You can do this by following the instructions in this article.

Model Deployment Type
Choose between Standard and Data Zone Standard deployment types during installation. Data Zone Standard routes traffic within a Microsoft-specified data zone, ensuring data processing remains local, such as within EU geographies for resources located there. For more details, visit the Azure OpenAI Deployment Data Processing Locations.
ct Model Deployment Region

Select the region where the Azure OpenAI models will be deployed. This region can differ from the application deployment region chosen in the first step.

• Review the summary of one’s choices from the previous two tabs and go back and correct anything found to be wrong.

• Click the Create button at the bottom of the page when ready to deploy Ayfie Personal Assistant

It typically takes some 10-15 minutes for the Managed Application to deploy its more than 10 Azure resources.

The last step of the previous section created and deployed the Personal Assistant and all its resources. Once it is fully deployed (reported above to take some 15-20 minutes), there are two post-configuration steps:

• Limit Users Access If Required

• Custom domain configuration

See following chapters in the guide Restrict a Microsoft Entra app to a set of users - Microsoft identity platform

• Update the app to require user assignment

• Assign the app to users and groups to restrict access

If a custom domain was configured earlier, then that has to be followed up with a corresponding DNS configuration as shown here:

Open

Step 1 and 2 below is not shown in the graphic above.

1. Go to the Microsoft Azure Portal at https://portal.azure.com

2. In the search box enter Resource Groups and select it from the search results

3. Search for and select resource group rg-ayfie-pa-application (or whatever other name that it was given)

4. Click the managed application AyfiePersonalAssistant (or whatever other name that it was given)

5. Click the managed resource group link mrg-ayfie_personal_assistan-<timestamp> (or whatever other name that it was given) up to the right

6. Within this group, find and click on the 'chat-ui' resource to access its settings.

7. In the 'chat-ui' resource, look for the 'Custom Domain' section in the navigation pane on the left side of the screen (under Networking).

8. Click on the 'Add custom domain' button to start the domain setup process.

9. When prompted, choose 'Managed certificate' as your first option (circled in purple) to ensure your domain is secured with an SSL certificate managed by Azure.

10. In the 'Domain' field (circled in green), type in the exact domain name you specified during the deployment of the Ayfie Personal Assistant Application.

11. For the record type, leave it set to “CNAME”

12. Add the two records provided in the 'Domain validation' section (circled in orange) to your domain's DNS settings. These records are crucial for proving ownership of the domain and for the SSL certificate to be issued. Please note the following when setting up the public DNS record:

    1. CNAME Record:

       • Host: Enter your domain name (e.g., pa.company.com).

       • Value: Use the URL ending with ...containerapps.io provided by Azure.

    2. TXT Record:

       • Host: Enter asuid. followed by your domain name (e.g., asuid.pa.company.com).

       • Value: Use the value provided by Azure.

13. Once you've updated your domain's DNS settings, click the 'Validate' button in Azure to check if the records are correctly configured.

14. If the validation is successful, the domain status should eventually update from “No binding” to 'Secured', indicating that your custom domain is now properly set up and protected with an SSL certificate. If you receive an error, delete the binding and try to validate and add again.
    
    Additional steps needed if “Use custom domain for backend/API” was selected during installation

15. Within mrg-ayfie_personal_assistan-<timestamp> select chat container and navigate to ‘Custom Domain’ section.

16. Repeat steps 7 - 14, but for the chat container

    1. In step 10, enter the host name, but with api prefix, e.g., api-pa.company.com

    2. In step 12, update your DNS settings with 2 new records presented in step 10.

• Enter the 'your_personal_assistant_url' in the browser to access the Ayfie Personal Assistant website and start conversing about uploaded documents.

• Note: Managed Applications installed via Azure Marketplace does not allow one to change the DNS of this application. That means one has these options:

  • Use the 'your_personal_assistant_url' as is

  • Configure an alias with a redirect to the 'your_personal_assistant_url'

To update system settings or creating chatbots, see the following guide on how to assign permissions to one or more users: Business Agent On-Premises - Assign RolesPreview

Personal Assistant consists of two components:

• Ayfie Personal Assistant Application

• Ayfie Personal Assistant Storage

There are two different uninstall scenarios:

• One wants to uninstall Personal Assistant completely for not using it any longer

  • Uninstall both components

• One wants to uninstall Personal Assistant as part of an upgrade to a newer version of Personal Assistant

  • Only uninstall the application component, leave the storage component with chat history and uploaded documents in place

The following graphic shows how to start the operation of uninstalling Ayfie Personal Assistant Application:

Open

1. Go to the Microsoft Azure Portal at https://portal.azure.com

2. Search for Managed Applications

3. Click Managed Applications

4. Click on your instance of Ayfie Personal Assistant Application

5. Click Delete

6. Click Yes to confirm

The uninstall process will take about 10-15 minutes to complete. In the notification tab (upper right) you will be notified when it’s deleted.

The following graphic shows how to start the operation of uninstalling Ayfie Personal Assistant Storage (remove the whole resource group
There is no way to retrieve earlier chat conversations or files if you proceed with these steps

Open

Ayfie Personal Assistant is in Microsoft terminology a Managed Application. Managed Applications cannot be upgraded per se; the old version must first be uninstalled before the new version can be installed.

However, Ayfie Personal Assistant Storage ensures that data is preserved during upgrades. Therefore, it is crucial to only uninstall and reinstall the Managed Application Ayfie Personal Assistant Application. The Managed Application Ayfie Personal Assistant Storage must remain in place as-is.

Here are the 4 steps to “upgrade” to a later version:

1. Obtain the Subscription Name, Application and Storage Resource Group Names, Client ID and Custom Domain. Here are the detailed steps for how to go about obtaining those 5 items:

   • Go to the Microsoft Azure Portal at https://portal.azure.com

   • In the search box enter “subscriptions” and/or press the Subscriptions icon if visible

   • Select the relevant relevant subscription

   • At the top of the subscription page, copy and preserve the Subscription Name

   • Select Resource groups from the vertical menu

   • Find the relevant storage resource (the recommended name to be used is rg-ayfie-pa-storage).

   • Copy and preserve the Storage Resource Group Name

   • Find the relevant application resource (the recommended name to be used is rg-ayfie-pa-application)

   • Copy and preserve the Application Resource Group Name

   • Click the Application Resource Group to enter it

   • Select chat-ui, then Application, then Containers, then Environment Variables

   • Copy and preserve the value of variable AYFIE_CHAT_BASE_URL as the Custom Domain (unless it contains a random alphanumeric string in which case one should start using a custom domain)

   • Copy and preserve the value of variable AYFIE_CHAT_AUTHORITY_CLIENT_ID as the Client ID

2. Uninstall the current version as described in chapter Uninstalling Ayfie Personal Assistant

3. Force an immediate deletion of any resources that are marked for deletion but that have still not been deleted as shown in the screenshot below.

Open

4. Do the installation from scratch as described in chapter Installing Ayfie Personal Assistant (but skip installing the storage component that was not uninstalled):

   1. If opting to re-use the existing "Service Principal" (Entra ID application) and one does not use a custom domain name, ensure to update the 'callback_url' as described in an earlier sub-section Configure Entra ID Application with the Callback URL. The same applies if one is upgrading from a Personal Assistant version prior to version 2.14.

   2. If Custom Domain is configured with the same value as in past versions, one is required to follow the steps within earlier section Custom Domain Configuration.

Deploying Ayfie Personal Assistant may encounter issues, and this section provides guidance on identifying and resolving common errors.

If you are unable to troubleshoot or fix the issue, please contact our support at support-nordics@ayfie.com

To know the status of an ongoing or completed deployment or other operation, click the bell icon to the right of the top bar.\

Open

To the right in the graphic above we see a successful application creation followed by a failed deployment (last action listed at the top). By clicking on the title we can get to more detailed information as shown with the error descriptions shown to the left.

Microsoft provides a long list of errors and their causes atTroubleshoot common Azure deployment errors - Azure Resource Manager. Not all of them are relevant to the deployment of Ayfie Personal Assisitant. Later in this section we will address the error message that are more relevant to our product.

In the following we will list some error that we see from time to time when deploying the Ayfie Personal Assistant:

• Configuration error: If one has installed Ayfie Personal Assistant Application with wrong settings (e.g. Enterprise Application, Data Retention or Custom Domain) we do not support modifying this post-deployment. One would therefore need to reinstall as written in Upgrading to a Newer Version of Ayfie Personal Assistant

• User chat and file upload history is gone after upgrade: This will occur when the Enterprise Application/ClientID is not the same across upgrades. One would therefore need to reinstall as written in Upgrading to a Newer Version of Ayfie Personal Assistant

• InsuffientQuota - this is an error that one normally would not see for a first time deployment, but is not uncommon during later re-deployments like for instance during upgrades. What normally causes this error is that one has forgotten to liberate Open AI resources that has been marked for deletion, but that has actually not been physically deleted. The fix is to do step 2 of the 3 steps procedure given in section Upgrading to a Newer Version of Ayfie Personal Assistant above. Another fix is to select another region as the quota is per region.

• “Random” deployments failures - sometimes Azure fails to deploy all of the resources. This is often caused by temporary issues at Azure and can usually be fixed by simply clicking the green circled Redeploy option in the graphic below. The error message in theses cases is typical without any details (see red circled example of this below):

  Open

  

Several containers now support extracting logs (some are locked down and not possible to extract logs from). The logs is specific to Ayfie related products and technology and would require one to forward the logs to Ayfie Support for further analysis.

In most cases of an error, the appropriate logs can be found in the “chat”-container:

• Navigate to the Managed Application for Ayfie PA.

• Click on the "Managed resource group."

• Within "Overview," select the resource "chat."

• Access logs under "Monitoring" and run the following queries:

  • ContainerAppConsoleLogs_CL | where ContainerName_s == "chat"
  • ContainerAppConsoleLogs_CL

• For each query result, extract the logs to CSV (all columns)

This documentation was last updated for version 2.14.1