| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Introduction
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 and PDFs, facilitating queries and discussions related to the uploaded content.
The Ayfie Personal Assistant consists of these two Azure Marketplace applications:
Ayfie Personal Assistant Storage - a static one time installed secure document storage environment.
Ayfie Personal Assistant Application - a dynamic UI component that will change over time as features are being updated or added
This documentation will take one step by step through the installation of the Ayfie Personal Assistant.
Prerequisites
The prerequisites comes in two groups:
System prerequisites - Obtaining the required subscription rights to do the installation
Admin user prerequisites - Obtaining the required user permissions to run the install process
System Prerequisites
These are the system prerequisites:
Obtain an Azure Subscription
One must have an active Azure subscription. If one don't have one, one can sign up for an Azure subscription on the Azure website.
Get Azure OpenAI Approval
The Azure subscription needs to be approved for Azure Open AI. How to do that is described in Ayfie Personal Assistant - How to Request Access to the Azure OpenAI Service.
Enable two Providers
In the Azure subscription settings, ensure that one enables the two providers below. How to do that is described in Ayfie Personal Assistant - How to Add Providers to an Azure Subscription.
Microsoft.App: Required for deploying applications within Azure.
Microsoft.ContainerService: Required for managing container-based services within Azure.
Admin User Prerequisites
The user that is to carry out the Ayfie Personal Assistant install process must have these roles and permissions:
Azure Subscription Management Contributor/Owner
The user must have the role Contributor or Owner for the subscription being used
Permission to Create and Manage Enterprise Applications
The user needs permissions to create and manage Enterprise Applications within Azure Active Directory.
Permission to Alter DNS Configuration
The user must have permissions to alter DNS records for custom domain setup (only required if the auto generated URL used by users to access the application is to be changed to something more readable)
Once one has completed all the system and the admin user prerequisites listed above, one can then start on installing Ayfie Personal Assistant.
Installing Ayfie Personal Assistant
The installation of Ayfie Personal Assistant consists of these operations that will be covered in the next 4 sections:
Obtain the Personal Assistant applications (Storage and Application) from Azure Marketplace via a private plan or public offering
Configure and deploy Ayfie Personal Assistant Storage
Configure and deploy Ayfie Personal Assistant Application
Post-Deployment configuration
Obtain Ayfie Personal Assistant Applications from Azure Marketplace
These are the two ways of getting the Ayfie Personal Assistant applications in Microsoft Azure Marketplace:
Via a private plan if one has a contract directly with Ayfie
Via a public offering if one does not have a contract directly with Ayfie
Most of the steps are the same for the two alternatives. The one main difference is as shown by the second red arrow in the click flows below. For private plans one has to select the private plan menu option as the second step (see left side of the image below) whereas for public offering (as shown to the right), this step is skipped.
...
Ayfie Personal Assistant Storage:
Go to the Microsoft Azure Portal at Microsoft Azure Marketplace
Use the search box to look up the “Ayfie Personal Assistant” applications
Select the Ayfie Personal Assistant Storage in search result, this will take one to Ayfie Personal Assistant page
Chose plan “Storage” and then click the Create button
Ayfie Personal Assistant Application:
Ensure that Ayfie Personal Assistant Storage is fully deployed before starting on installing this application.
Go to the Microsoft Azure Portal at Microsoft Azure Marketplace
If you have a private plan select Private plans in in the left side menu, otherwise skip this step
Use the search box to look up the “Ayfie Personal Assistant” applications
Select the Ayfie Personal Assistant Application in search result, this will take one to Ayfie Personal Assistant page
If you have a private plan, select it from the dropdown, otherwise select the number of users you want to license, and then click the Create button
Configure & Deploy Ayfie Personal Storage
he page has the following 2 tabs that we in the following will visit one by one:
Basic
Review + create
The Basic Tab
...
Select the subscription from the dropdown, and create a new resource group or select an existing one (circled in purple above)
Select one of these alternative locations from the dropdown menu (circled in orange). Technically it does not matter, but EU customers should for legal reasons select one of the two EU regions listed at the top:
France Central
Sweden Central
UK South
Canada East
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.
The Review + Create Tab
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 15 Azure resources.
Configure & Deploy Ayfie Personal Assistant Application
Before configuring and deploying the Ayfie Personal Assistant Application, verify that the Ayfie Personal Assistant Storage deployment is complete
Regardless of how one obtained Ayfie Personal Assistant above, via public offering or a private plan, at this point one will see the Create Ayfie Personal Assistant page shown below. The page has the following 4 tabs that we in the following will visit one by one:
Basic
User Authentication
Custom domain
Review + create
The Basic Tab
...
Select the subscription from the dropdown, and create a new resource group or select an existing one (circled in purple above)
Select one of these alternative locations from the dropdown menu (circled in orange). Technically it does not matter, but European customers should for legal reasons select one of the two European regions:
France Central
Sweden Central
UK South
Canada East
Select the name of the resource group where the Ayfie Personal Assistant Storage is deployed
Give the managed application a name, for instance "AyfiePersonalAssistant" (circled in green)
Click Next (circled in red) to get to the Authentication page
The User Authentication Tab
...
User access to Ayfie Personal Assistance is managed via a Service Principal which is an instance of an Entra ID (formerly known as Azure AD) application.
One can use a Service Principal that already exists or create a new one
Depending on which of the two options one chose, clicking the Make selection link will either bring up a search pane with existing Service Principals to choose from, or a form to register a new Service Principal. The screenshot above shows the case of creating a new one.
Give the Service Principal (the Entra ID application) a name, for instance AyfiePersonalAssistantApp as done in the example above.
Select the single tenant option (this would cover the case of all users being employees of the customer)
Click the Register button. This will take one away from the page. To get back, use the path at the top of the page as indicated by the green arrow.
Verify that one has created or selected a Service Principal by checking of the check box
Click Next (circled in red) to get to the Authentication page
The Custom Domain Tab
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 the users to access this application with their own custom domain/URL then follow the following steps (leave blank if not):
...
Check the “Configure custom domain”
...
Check the “Verify if you have access to DNS record for you domain”
...
Add the custom domain, e.g. “ayfie.company.com” to the input field
...
| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Introduction
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 and PDFs, 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.
Two Components
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
Private Plan vs. Public Offering
There are two ways of purchasing Ayfie Personal Assistant: via a private plan or via a public offering. As the installation and configuration is slightly different for the two cases, one will need to know how the product was purchased.
Private plan - the contract is with Ayfie and one orders a single user in Microsoft Azure regardless of the number of actual users.
Public offering - the contract is with Microsoft and one configures the number of users in Microsoft Azure in accordance with the actual number of users.
Technically, there is no problem installing and configuring Ayfie Personal Assistant as a public offering even if one purchased it via a private plan. However, that would significantly increase the monthly cost without any added benefit.
Resource Groups
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 future interactions with Ayfie support.
Version Upgrades
Version upgrades are not done as “upgrades” but rather as an uninstall operation (of the old version) followed by an install operation (of 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.
Custom Domain vs. Random URL
The URL to access Personal Assistant can be either a custom domain of your choosing (for instance pa.mycompany.com) or whatever random URL provided by Azure AI services. The former approach is what is most common. 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 URL provided by Azure AI services.
Prerequisites
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
System Prerequisites
These are the system prerequisites:
Obtain an Azure Subscription
An active Azure subscription is required. To register a new subscription, go to the Azure website.
At times, Microsoft may impose subscription type specific limitations on their OpenAI services, particularly concerning the amount of data (referred to as the token quota) that can be exchanged during chat interactions. Please see this Microsoft documentation on token quotas for details on which subscription types that may have such restrictions.
If one has a contract directly with Ayfie (a.k.a. private plan) please send the Subscription ID to your Ayfie contact.
Get Azure OpenAI Approval
The Azure subscription needs to be approved for Azure Open AI. How to do that is described in Ayfie Personal Assistant - How to Request Access to the Azure OpenAI Service.
Enable two Providers
In the Azure subscription settings, ensure that the two providers below are enabled. How to do that is described in Ayfie Personal Assistant - How to Add Providers to an Azure Subscription.
Microsoft.App: Required for deploying applications within Azure.
Microsoft.ContainerService: Required for managing container-based services within Azure.
Microsoft.ContainerInstance: Required for runningcontainerized applications without needing to manage the underlying infrastructure.
Microsoft.OperationalInsights: Required for monitoring, diagnostics, and log management.
Admin User Prerequisites
The user that is to carries out the Ayfie Personal Assistant install process must have these roles and permissions:
Azure Subscription Management Owner and Key Vault Administrator
Permission to Create and Manage Entra ID Enterprise Applications
Permission to Alter DNS Configuration
The user must have permissions to alter public DNS records for custom domain setup (only required if the auto generated URL used by users to access the application is to be changed to something more readable and user friendly).
After completing all system and admin user prerequisites listed above, one can proceed with the installation of Ayfie Personal Assistant.
Installing 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
Obtain and Configure the Storage Component
Obtain the Storage Component
Go to the Microsoft Azure Portal at https://portal.azure.com
In the search box enter Marketplace and select it from the search results
At the Marketplace page, use the Marketplace search box to search for “Ayfie Personal Assistant Storage”
Select the Ayfie Personal Assistant Storagefrom the search result
Chose plan “Storage” and then click the Create button
Configure & Deploy the Storage Component
Once the Create Storage page appears, fill in the details:
...
Select the subscription from the dropdown (Ayfie Development in the example above)
Create a new resource group (recommended) 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.
...
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.
Obtain and Configure the Application
| Note |
|---|
Ayfie Personal Assistant Storage must be created (or already exist) before setting up the Ayfie Personal Assistant Application. |
Obtain the Application Component
These are the two ways of configuring Ayfie Personal Assistant Application in Microsoft Azure Marketplace:
As a private plan
As a public offering
If in doubt, one should consult Private Plan or Public Offering? on how to find out what one has. Most of the steps are the same for the two alternatives. The difference is in step 2 and 5 below (indicated with bold font) and with green markings in the screenshot below where one follow the red arrows all the way for the public offering and swap to green for the private plan.
...
Go to the Microsoft Azure Portal at https://portal.azure.com
In the search box enter Marketplace and select it from the search results
If you have a private plan select Private plans in in the left side menu (circled in green), otherwise use the search box to look up the “Ayfie Personal Assistant” applications
Select the Ayfie Personal Assistant Application box
If you have a private plan, select the plan from the dropdown (see green arrow below), otherwise select the number of users you want to license (red arrow). Then click the Create button.
...
From this point of in the procedure, there is no difference between having a private plan or a public offering.
Configure the Application Component
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 Basic Tab
The page title in the graphics below ends with Private Plan. if one is using a public offering, then the title will instead be Create N users, where N is the number of users one selected from the dropdown on the previous page. The graphics in this section will show both title types.
...
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
The User Authentication Tab
...
User access to Ayfie Personal Assistance is managed by Entra ID via a Service Principal.
One can use a Service Principal that already exists or create a new one.
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
Depending on which of the two options one chose, clicking the Make selection link will either bring up a search pane with existing Service Principals to choose from, or a form to register a new Service Principal. The screenshot above shows the case of creating a new one.
Give the Service Principal (the Entra ID application) a name, for instance AyfiePersonalAssistantApp as in the graphics above.
Select the single tenant option (this would cover the case of all users being employees of the customer)
Click the Register button. This will take one away from the page. After having completed the registration, just redo the first few steps to get back to this place.
Verify that one has created or 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
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 (red box)
Data Retention Policy - Allows one to configure for how long time uploaded documents are to be stored after having been accessed the last time (green box)
Model Configuration - Set the philosophy for how to determine what AI-model to be used as the default for when starting new chat sessions or going back to stored chat sessions. Price, performance or a mix? (blue box)
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.
...
Custom Domain (red box)
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 DNS record for you domain”
Add the custom domain, e.g. “pa.my-domain.com” to the input field
Note: This has to be made as a public DNS
Click the white Next or the blue Review + create button. This will take one to the Review + create page.
Data Retention Policy (green box)
To reduce storage expenses, adhere to data storage guidelines, or keep the Personal Assistant interface uncluttered, you can turn on the Data Retention Policy. This will automatically remove any uploaded documents that haven't been used in chats for the duration (from 7 to 100 days) set by the adjustable sliding scale.
Check the “Enable data retention policy”
Enter the number of days before files are deleted due to inactivity
Model Configuration (blue box)
For each region there will be a set of models that will be made available to the users. One of those models will be the default one and the one to be returned to each time one starts a new chat or when one return to a stored chat. While it is not possible to select a specific model to instead be used as the default, one can set the “philosophy” for how to determine the default. The three “philosophies” to chose chose from are Economy, Premium, Standard. That is, price, performance, and mix of the two, respectability. Economy is the default.
The Review + Create Tab
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
...
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:
Configure Obtain the Callback URL
Set the Entra ID application up with the Callback URL and implicit grant
Add Users to the ApplicationLimit Users Access If Required
Custom domain configuration
Configure the Callback URL and Implicit Grant
...
Obtain the Callback URL
Retrieve the callback URL:
...
Go to the Microsoft Azure Portal at https://portal.azure.com
...
In the search box enter Managed Applications and select it from the search results
At the Managed Applications page, click AyfiePersonalAssistant (the name we gave it in the previous section)
Under Settings, Click Parameters and Outputs in the left vertical menu
Copy the the values of your_personal_assistant_url and callback_url
...
to
...
a notepad
...
as you will be needing these later in this procedure.
...
Set the Entra ID application up with the Callback URL
Configure the Entra ID application to do single sign-on access control for a single-page application:
...
Go to the Microsoft Azure Portal at https://portal.azure.com
...
In the search box enter Enterprise Applications
...
and select it from the search results
Search for and click the Service Principle we created earlier (in this documentation we named it AyfiePersonalAssistantApp)
At the Enterprise Applications page, select the Single sign-on menu option in the vertical left side menu
Click Go to application up in the right corner of the first item listed
Select
...
Authentication
...
in the vertical left side menu
Click Add a platform and then select
...
Access tokens
...
Single-page application up to the right of the page
...
Enter the earlier saved callback_url in the text input field that has appeared and then click the blue Configure button at the bottom of the page
...
Click "Add URI" and include a second URL:
Append
/silent-renew.htmlto your earlier savedyour_personal_assistant_url.
...
Now back at the Authentication page, scroll down to the Implicit grant and hybrid flows section and ensure that these two check boxes are checked:
Only if an upgrade and not a brand new installation: Make sure to remove any previously used web application platform by clicking the trash can icon up in the right corner
Enter the callback_url we saved earlier in the top text input field and then check of the two boxes at the bottom for Access tokens and ID tokens before clicking Configure:
Click the blue Save button at the bottom of the page
...
Granting Permissions for the Application
With single sign-on now successfully configured, sign in using one’s standard Microsoft account. The final step is to add oneself and other users to the designated users and groups, unless one has not disabled user assignment (which means anyone on the tenant can log in whether they are added to the application or not - see subsection “Setting the ‘Assignment Required’” below).
To harness the full potential of Ayfie Personal Assistant, follow these steps:
Go to the top (click Home at the beginning of the bread chrome path at the top of the page or go to https://portal.azure.com)
Click the Enterprise Applications icon (or search for Enterprise Applications in the search bar).
Select the application we earlier named AyfiePersonalAssistant.
Select Users and groups in the vertical menu to the left
Grant Access
There are multiple methods for granting access, driven by individual preference or company policies. Commence by clicking the 'Add user/group' button.
After assigning access permissions to the selected users or groups, gain the ability to access the application. If one opened a new tab, return to the Managed Application tab and copy the 'your_personal_assistant_url' into the browser. If there is no separate tab, easily locate the managed application in the resource group selected during the initial deployment.
Setting the "Assignment Required"
To enhance security and control over user access, you can configure the "Assignment required" property for Ayfie Personal Assistant. This setting ensures that users must be explicitly assigned to the application before being able to access it.
Follow these steps to enable "Assignment required":
Navigate to the Enterprise Application named AyfiePersonalAssistant.
In the left-hand menu, click on Properties under the Manage section.
Locate the Assignment required property and set it to Enabled.
Save your changes.
With "Assignment required" enabled, users will need to be explicitly added or assigned to Ayfie Personal Assistant to gain access.
Granting Permissions for the Application
To enable Ayfie Personal Assistant to interact with Microsoft Graph on behalf of users, it's essential to grant admin consent for the required permissions. This step ensures that the necessary API permission “Microsoft Graph\User.Read” is granted through admin consent.
...
Follow these steps to grant admin consent (assuming you are still on the Enterprise Application):
Navigate to Permissions within the Security menu.
Click on Grant admin consent for [Your Organization].
A new web browser window is shown where you have to accept the permission request
By granting admin consent, you authorize Ayfie Personal Assistant to access the specified Microsoft Graph permissions on behalf of all users in your organization. This is essential for seamless functionality that relies on delegated access to user data.
Custom domain configuration
If you've opted for a custom domain during your Ayfie Personal Assistant Application setup Application then you are required to perform changes to your DNS and validate the changes.
...
Go to your Azure portal and locate the Managed Resource Group for the Ayfie Personal Assistant Application . Within this group, find and click on the 'chat-ui' resource to access its settings.
In the 'chat-ui' resource, look for the 'Custom Domain' section in the navigation pane on the left side of the screen.
Click on the 'Add custom domain' button to start the domain setup process.
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.
In the 'Domain' field (circled in green), type in the exact domain name you specified during the deployment of the Ayfie Personal Assistant Application.
For the record type, leave it set to “CNAME”
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.
Once you've updated your domain's DNS settings, click the 'Validate' button in Azure to check if the records are correctly configured.
If the validation is successful, the domain status should eventually update to 'Secured', indicating that your custom domain is now properly set up and protected with an SSL certificate.
Accessing the Ayfie Personal Assistant
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'
Uninstalling the Ayfie Personal Assistant
The following graphic shows how to start the operation of uninstalling Ayfie Personal Assistant:
...
The next graphic shows how one can check the status of the delete operation by clicking the notification icon up in the right corner of the browser window:
...
The uninstallation process may take anywhere from 3 to 20 minutes.
Upgrading to a Newer Version of Ayfie Personal Assistant
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. Be aware that for customers currently on versions earlier than 2.9, upgrading to the new version will result in data loss, as the existing data is not retained post-uninstallation. For the Personal Assistant users this means that any uploaded documents have to be re-uploaded if they are still of interest.
However, starting with version 2.9 and future releases, Ayfie Personal Assistant Storage will ensure that data is preserved during upgrades. The upgrade process that leverages the new Storage application will be provided with the upcoming release in the marketplace.
Here are the 3 steps to “upgrade” to a later version:
Uninstall the current version as described in chapter Uninstalling the Ayfie Personal Assistant
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.
Install from scratch as described in chapter Installing Ayfie Personal Assistant.
If opting to re-use the existing "Service Principal," ensure to update the URLs under Configure the Callback URL with the new values:
callback_url
your_personal_assistan_url/silent-renew.html
Troubleshooting
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
Error Notification
To know the status of an ongoing or completed deployment or other operation, click the bell icon to the right of the top bar.
...
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 athttps://learn.microsoft.com/en-us/azure/azure-resource-manager/troubleshooting/common-deployment-errors. 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.
Common Deployment Errors
In the following we will list some error that we see from time to time when deploying the Ayfie Personal Assistant:To enable Ayfie Personal Assistant to interact with Microsoft Graph on behalf of users, one has to grant admin consent for the required permissions.
...
Under the Security part of the vertical menu to the left, Select Permissions
Click on Grant admin consent for [Your Organization].
A new web browser window is shown, click Accept.
Limit User Access for Personal Assistant
See following chapters in the guide https://learn.microsoft.com/en-us/entra/identity-platform/howto-restrict-your-app-to-a-set-of-users
Update the app to require user assignment
Assign the app to users and groups to restrict access
Custom Domain Configuration
If a custom domain was configured earlier, then that has to be followed up with a corresponding DNS configuration as shown here:
...
Step 1 and 2 below is not shown in the graphic above.
Go to the Microsoft Azure Portal at https://portal.azure.com
In the search box enter Resource Groups and select it from the search results
Search for and select resource group rg-ayfie-pa-application (or whatever other name that it was given)
Click the managed application AyfiePersonalAssistant (or whatever other name that it was given)
Click the managed resource group link mrg-ayfie_personal_assistan-<timestamp> (or whatever other name that it was given) up to the right
Within this group, find and click on the 'chat-ui' resource to access its settings.
In the 'chat-ui' resource, look for the 'Custom Domain' section in the navigation pane on the left side of the screen.
Click on the 'Add custom domain' button to start the domain setup process.
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.
In the 'Domain' field (circled in green), type in the exact domain name you specified during the deployment of the Ayfie Personal Assistant Application.
For the record type, leave it set to “CNAME”
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:
CNAME Record:
Host: Enter your domain name (e.g.,
ayfie.company.com).Value: Use the URL ending with
...containerapps.ioprovided by Azure.
TXT Record:
Host: Enter
asuid.followed by your domain name (e.g.,asuid.ayfie.company.com).Value: Use the value provided by Azure.
Once you've updated your domain's DNS settings, click the 'Validate' button in Azure to check if the records are correctly configured.
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.
Accessing Ayfie Personal Assistant
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'
Uninstalling Ayfie Personal Assistant
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:
...
The next graphic shows how one can check the status of the delete operation by clicking the notification icon up in the right corner of the browser window:
...
The uninstallation process may take anywhere from 3 to 20 minutes.
Upgrading to a Newer Version of Ayfie Personal Assistant
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.
| Note |
|---|
Do NOT uninstall the application Ayfie Personal Assistant Storage |
Here are the 3 steps to “upgrade” to a later version:
Retrieve the Client ID of the application:
Go to the Microsoft Azure Portal at https://portal.azure.com
In the search box enter Managed Applications and select it from the search results
At the Managed Applications page, click AyfiePersonalAssistant (or whatever other name one chose to give the application in a previous section above)
Under Settings, Click Parameters and Outputs in the left vertical menu
Navigate to Settings and select Parameters and outputs
Copy the Client ID, it will be needed in step 4 below
Uninstall the current version as described in chapter Uninstalling the Ayfie Personal Assistant
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.
...
Do the installation from scratch as described in chapter Installing Ayfie Personal Assistant (but skip installing the storage component that was not uninstalled):
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 earlier section Set the Entra ID application up with the Callback URL. The same applies if one is upgrading from a Personal Assistant version prior to version 2.14.
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.
Troubleshooting
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
Error Notification
To know the status of an ongoing or completed deployment or other operation, click the bell icon to the right of the top bar.\
...
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 athttps://learn.microsoft.com/en-us/azure/azure-resource-manager/troubleshooting/common-deployment-errors. 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.
Common Deployment Errors
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 clicking “Redeploy” on the Deployment.
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):
Logs
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.
...
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:
Code Block ContainerAppSystemLogsContainerAppConsoleLogs_CL | where TypeContainerName_s contains== "warningchat"
Code Block ContainerAppConsoleLogs_CL
For each query result, extract the logs to CSV (all columns)
This documentation was last updated for version 2.14.1