KLapper v2.0 Upgrade Guide

Prerequisites

1. Azure Cloud Subscription.
   
2. Azure Subscription with following Resource Providers enabled
   
1. Microsoft.BotService
   
2. Microsoft.CognitiveServices
   
3. Microsoft.DocumentDB
   
4. Microsoft.Web
   
3. Azure Cloud Admin account with Subscription level privileges.
   
4. Understanding Azure Cloud Network.
   
5. Windows PowerShell 7.4.7 - https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.5
   
6. Azure PowerShell Module (13.4.0)
   
7. Minimum permission required
   
1. Azure subscription access
   
2. Resource creation – Contributor/Owner at the subscription level or resource group level
   
3. Azure OpenAI service – Cognitive Services Contributor
   
4. Key management – Cognitive Services User
   
5. Resource deletion – Contributor/Owner at the resource group level
   
8. PowerShell execution policy to run unsigned script files
   
9. Whitelist following domains – This is required for downloading installation files and licensing check
   
1. https://admin.klapper.ai
   
2. *.klapper.ai
   
3. https://${BuilderServiceName}.azurewebsites.net/builderapi/*
   
4. https://${BuilderServiceName}.scm.azurewebsites.net
   
5. https://${FMApiServiceName}.scm.azurewebsites.net
   
6. https://${FrameworkServiceName}.scm.azurewebsites.net
   
7. https://${DocumentServiceName}.scm.azurewebsites.net
   
8. https://klapperv2.azurecr.io
   

Azure Requirements

1. App Service Plan
   
1. Tier – PremiumMV3
   
2. OS – Windows
   
2. App Service Plan
   
1. Tier – PremiumMV3
   
2. OS - Linux
   
3. Builder
   
1. Azure App Service
   
4. File Manager
   
1. Azure App Service
   
5. Framework
   
1. Azure App Service
   
6. Document Conversion
   
1. Azure App Service
   
7. Azure Open AI Service
   
1. Model GPT-4o
   
2. 125K token quota is required
   
8. Database
   
1. Azure Cosmos Mongo DB
   
2. Azure Cosmos NoSQL DB
   
3. Pricing model – Provisioned throughput
   
4. Performance tier - Standard
   
9. Azure Entra App
   
10. Azure Translation Service
    
1. Blob Storage

Installation

PowerShell Setup

1. Install PowerShell 7.4.7 from - https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.5
   
2. Open Windows PowerShell as an administrator
   
3. Verify the proper Windows PowerShell version is installed using this script (7.4.7)
   
1. $PSVersionTable.PSVersion
   
4. Run below script
   
1. Set-ExecutionPolicy Unrestricted -Force
   
5. Run below script and check the Azure PowerShell module version is 13.4.0
   
1. Get-InstalledModule -Name Az -AllVersions | Select-Object Name,Version
   
2. If the incorrect version is installed, use this to uninstall that version before downloading 13.4.0: Uninstall-Module -Name Az -Version {Version Number}
   
6. To install the specific version, use below command
   
1. Install-Module Az -RequiredVersion 13.4.0 -Scope CurrentUser -Repository PSGallery
   
7. Run below script
   
1. Get-AzContext
   
8. Run below script
   
1. Connect-AzAccount 
   

Installation Process

1. Download the installation zip file shared.
2. Extract zip file to the folder in a Windows 10, 11 or 2019 server with PowerShell configured
3. Make sure the user performing installation has Provisioning privileges in Azure.
4. Open Inputs.ps1 and fill in the details. No underscores or capital letters should be used for any variables, after the Resource Group Name.
   
1. Any old services should use the old service name as the input value

1. Navigate to the extracted folder in PowerShell
2. Run Upgrade_v2.0.ps1
   

Post installation

Enable NoSQL Features in CosmosDB

1. Open Azure Portal
   
2. Open the newly created resource group
   
3. Open the Cosmos NoSQL DB
   
4. From left pane - Expand "Settings" - Select Features
   
5. Enable below features
   
1. Full-Text & Hybrid Search for NoSQL API (preview)
   
2. Vector Search for NoSQL API
   

Add New Deployment Model

Need to provision the "text-embedding-3-large" model in the Azure OpenAI

Scale Up The BuilderAPI

1. Open Azure Portal
   
2. Open KLapper resource group
   
3. Open the KLapper Builder App Service
   
4. Click Settings, from the left-panel, then Scale up
   
5. Change the plan to Premium v3 P1mv3

Update Cosmos MongoDB Version

1. Open Azure Portal
   
2. Open KLapper resource group
   
3. Open the Cosmos MongoDB Database
   
4. Make sure the version is 7.0
   

Update Builder API .NET Version

1. Open Azure Portal
2. Open KLapper resource group
3. Open the Builder Api App Service
4. Settings -> Configuration -> Update the .NET version - .NET 8 (LTS) and save it.
   
   

Retrieve Storage Account Key

1. Open Azure Portal
2. Open KLapper resource group
3. Open the Blob Storage service
4. From the left panel, open Security + networking
5. Click Access keys
6. Copy the Storage account name and Key from key1 
   

Retrieve Translation Service Endpoint & Key

1. Open Azure Portal
2. Open KLapper resource group
3. Open the Translator service
4. From the left panel, open Resource Management
5. Click Keys and Endpoint
6. Copy the KEY 1 and Document Translation values
   

End Point Location:

Click the Json View in Overview section and get the “DocumentTranslation” endpoint.

If you want to set a custom domain, please click the “Set Custom Domain” option in the Overview section. If the custom domain has already been created, this option will not be visible. If you have just created the custom domain, refresh the page and then click the JSON View.

Configuring Environment Variables of OCR Converter Service:

The following environment variables must be set to configure the OCR Converter Service properly. These values may be reused from the FM service configuration where applicable.

Variable Name	Description
MONGODB_HOST	Hostname or IP address of the MongoDB server
MONGODB_USERNAME	Username used to authenticate with MongoDB
MONGODB_PASSWORD	Password used to authenticate with MongoDB
MONGODB_PARAMS	Additional MongoDB connection parameters
MONGODB_DATABASE	Name of the MongoDB database to be used by the service
CONTAINER_ENV	Deployment environment

Note:

 Ensure that the Azure Storage Account is properly configured in the Global Settings. This storage account is used as a temporary location to store documents processed by the OCR service.

Configuring Builder Settings

1. Open KLapper builder App Service URL
2. Login using your email address
3. Validate the settings

Updating KLapper

Note: Before updating to KLapper v2.0.0, the KLapper team must confirm that the Updating Web Job package is up to date.

1. Go to Global Settings
   
   
2. Click update and Proceed
   

After Updating KLapper to 2.0

1. Go to global settings.
2. Add the "Tenant Domain" to the “Microsoft Azure App Details” section.
3. Add the " File Converter URL " to the “General” section.
4. Add the "Embedding Model Name" to the “Microsoft Azure OpenAI Details” section.
5. Add the "Translation Endpoint" and "Translator Key" to the "Translation Service Details" section.
   
6. Add the "Account Name" and "Account Key" to the "Azure Storage Account Details" section.
   
7.  Then click Save to apply changes.
   

Update SharePoint Entra Application

Verify that all of these permissions are granted to the SharePoint Entra Application for KLapper

1. Microsoft Graph:
   
1. Calendars.ReadWrite (Delegated)
2. Directory.Read.All (Application)
3. Group.Read.All (Application)
4. GroupMember.Read.All (Application)
5.  Sites.Read.All (Delegated)
6. User.Read (Delegated)
7. User.Read.All (Application)
2. SharePoint (Delegated):
   
1. AllSites.Read (Delegated)
2. Sites.FullControl.All (Application)
3. Sites.ReadWrite.All (Application)
4. Sites.Search.All (Delegated)
5. TermStore.Read.All (Application)
6. User.Read.All (Application)

How to add a custom domain for KLapper

1. Head to the Azure portal, and navigate to the resource group that was created for KLapper
   
2. Open the KLapper Builder App Service
3. From the left column, select Custom domains
   

From the Add custom domain panel, select the following:

      Domain provider: All other domain services

      TLS/SSL certificate: App Service Managed Certificate      

      TSL/SSL type: SNI SSL      

      Then enter your desired domain name, validate all entries

      Finally press Validate then Add