Ayfie Personal Assistant - Installation Guide

Owned by Lars Gjestang
Last updated: May 16, 2024 by Morten Johnsen
13 min read

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:

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.

image-20240117-120347.png

Ayfie Personal Assistant Storage:

  1. Go to the Microsoft Azure Portal at Microsoft Azure Marketplace

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

  3. Select the Ayfie Personal Assistant Storage in search result, this will take one to Ayfie Personal Assistant page

  4. 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.

  1. Go to the Microsoft Azure Portal at Microsoft Azure Marketplace

  2. If you have a private plan select Private plans in in the left side menu, otherwise skip this step

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

  4. Select the Ayfie Personal Assistant Application in search result, this will take one to Ayfie Personal Assistant page

  5. 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

image-20240513-104214.png

 

  • 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 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

  • 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

  • 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 10 Azure resources.

Post-Deployment Configuration

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 the Callback URL and implicit grant

  • Add Users to the Application

  • Custom domain configuration

Configure the Callback URL and Implicit Grant

Based on what has been done so far, one would at this point already be at the Managed Application page for the Personal Assistant Application. The graphic below, however, shows the full route from entering the Microsoft Azure Portal at https://portal.azure.com.

On the Ayfie Personal Assistant page, click Parameters and Outputs under Settings in the vertical menu to the left.

  • Copy the the values of your_personal_assistant_url and callback_url (see red circled values in the graphics) to for instance a notepad. You will need these later.

  • 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) and there click the Enterprise Applications icon (or enter Enterprise Applications in the search bar) to locate the Service Principal you either created or referenced earlier.

    • Click the Service Principle name (link)

    • 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 the Authentication option of the vertical left side menu

    • Click Add a platform and then select Web in the section that comes 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.html to your earlier saved your_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:

    • Access tokens

    • ID tokens

  • Click the blue Save button at the bottom of the page

Add Users to 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:

  1. 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)

  2. Click the Enterprise Applications icon (or search for Enterprise Applications in the search bar).

  3. Select the application we earlier named AyfiePersonalAssistant.

  4. 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":

  1. Navigate to the Enterprise Application named AyfiePersonalAssistant.

  2. In the left-hand menu, click on Properties under the Manage section.

  3. Locate the Assignment required property and set it to Enabled.

  4. 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):

  1. Navigate to Permissions within the Security menu.

  2. Click on Grant admin consent for [Your Organization].

  3. 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.

  1. 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.

  2. In the 'chat-ui' resource, look for the 'Custom Domain' section in the navigation pane on the left side of the screen.

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

  4. 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.

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

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

  7. 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.

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

  9. 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:

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

  2. 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.

  3. Install from scratch as described in chapter Installing Ayfie Personal Assistant.

    1. If opting to re-use the existing "Service Principal," ensure to update the URLs under Configure the Callback URL with the new values:

      1. callback_url

      2. 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:

  • 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 usually fixed by clicking “Redeploy” on the Deployment.

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.

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:

    • ContainerAppSystemLogs_CL | where Type_s contains "warning"
    • ContainerAppConsoleLogs_CL

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