Setup Guide Addovation Change

Last Updated: 2025-03-11

1. Introduction

Addovation Change is the cloud enabled and IFS Projections consuming evolution of the Microsoft Excel Add-in. The product is secured and monetized using Addovation’s Cloud Portal.

This guide will provide insight into the setup of the product in two stages:

Stage 1: deploy the add-in to the customer site.

Stage 2: create a subscription to start using the add-in

2. Solution Architecture for Addovation Change

The basic architecture relies on:

1. Manifest used to load the Add-in.
2. A site based on Node.JS (built using React.JS) hosting the logic for the Add-in.
3. A site based on .NET Core which provides an API that is placed behind an Azure APIM instance for Demo and Prod instances.
4. An Addovation Cloud Portal instance used to manage the subscription-based access for Demo and Prod Environments.
5. IFS instances and their Identity Providers.
6. A Cosmos database to maintain settings for the subscription.
7. An Azure Application Insights instance used to track all exceptions raised in the API.

Azure DevOps is used to host the code base and deploy the code base into Dev, QA, Demo and Prod environments.

3. Customer Setup

IFS cloud access by default should be secured. Therefore, the API used by the Add-in needs access to the Rest APIs exposed in IFS. The Add-in needs to identify the user, and the identity provider needs to be the same as used by the customer’s IFS Cloud.

3.1. Deploying the Add-in to Microsoft Excel

The Add-in is loaded into Microsoft Excel using a manifest.xml file. For production, the manifest needs to be centrally deployed. Ref: https://docs.microsoft.com/en-us/microsoft-365/admin/manage/centralized-deployment-faq?view=o365-worldwide. The Key Account Manager for Addovation should handover the manifest to the IT department of the customer. Customer's IT can then deploy the manifest to their users. The file is valid for all customers and does not need modifications.

3.2. Access to Customer’s IFS Cloud Instance

The visibility should be provided by whitelisting the API or using a virtual network (which is recommended), such as VNet. Ref: https://docs.microsoft.com/en-us/azure/virtual-network/virtual-networks-overview

3.3. Identity Provider Access

The users of the add-in will access their IFS Cloud instance as themselves. As such, they need to be identified and this is done using the industry standard for identification, OpenID Connect. Ref: https://openid.net/connect/.

IFS Cloud uses Keycloak for authentication (Entra/Azure Active Directory).

For the Add-in, to get the users authenticated and be used when accessing IFS cloud, the following steps are needed:

• An IAM Client must be created in IFS Cloud.
• A redirect URL for the add-in must be added to the IFS Cloud IAM Client’s Redirect URI listing.
• The URL should be in the format, https://<{Add-in host}>/authentication/login/login.html.
• In production environments this would be: https://addocloudpowertoolsapp.azurewebsites.net/authentication/login/login.html

The client id, realm id, and secret needs to be provided to the Addovation key account manager setting up the subscriptions.

For IFS Cloud the steps needed are:

• A IAM Client defined in IFS Cloud
• A redirect URL for the Add-in to be added under redirect Uris in the IAM Client.The URL should be of the format, https://<{Add-in host}>/authentication/login/login.html

3.4. Permissions in IFS

For customer users of the Add-in to work against the customer’s IFS instance, they need to be:

• Valid users of IFS. i.e. be able to access IFS cloud client
• Have appropriate access to the business objects used on the Microsoft Excel template with the Add-in
• Have read access to the all Projections within IFS cloud.

3.5. Subscription Creation Guide for the Key Account Manager

The Key Account Manager (KAM) needs the Customer to setup access to IFS cloud and the Azure Active Directory Application. This is handled in the previous chapter. Once access is granted, the subscription for Addovation Change can be created using the Addovation Cloud Portal.

When creating the subscription, the customer settings need to be updated with the ClientId and the TenantId for the Azure Active Directory Application used to identify the customer users (as mentioned above) and the customer’s IFS cloud access point.

Once the subscription is created, the primary/secondary key for the subscription and the endpoint for the API needs to be provided to the customer to use in the properties page of the Add-in.