Addovation Sync - Case - Setup Guide (Customer)

Last Updated: 2025-03-07

Overview

This setup guide provides detailed instructions for configuring the Addovation Sync - Case service from the customer's end. The process includes setting up OAuth2 email account access in Azure AD, configuring IFS data, and configuring projections. Additionally, it outlines the steps required to enable Multi-Factor Authentication (MFA) for email account access in Azure AD, if the organization chooses to set it up. Each step is thoroughly explained to ensure a smooth setup process.

IFS Data Configuration

Integration User

An integration user should be created with all required permissions to work with the service.

Permission should be available for;

IFS Projections and methods
IFS Call center module

Basic Data

Required file extension/s (‘MSG’ or ‘EML’) should be registered under EDM basic and as the ‘VIEW’ or 'ORIGINAL' document type.

A class and format should be defined under EDM Basic data ,to use as default class and format which is configured in the config. If no valid class and format are defined, an error will be occurred.

In EDM basic data, select the class that uses as the default class in the Mail2Case service config, If VIEW_FILE_REQ is set to ‘N’ and ‘Override default’ is checked, only the original file will be checked in. If VIEW_FILE_REQ is set to ‘Y’ and 'Override default' is checked, then the view copy should be in the same folder which original file resides , and both original file and view file will be checked in.

Projection Configuration

Deploy Projection using Build Place

Refer Technical Documentation For IFS Cloud - Build Place Deliveries

Test/Verify Projection Endpoints

Sign in to IFS Cloud
Go to API Explorer
Search AddoMail2CaseHandling using filter Panel and go to Projection Name

Select AddoMail2CaseHandling projection -> Specification -> OpenAPI v3

A file will be opened as below depicted and copy the whole json text from that file.

Open Postman
select Import
Then paste the copied Row text on it

Graphical user interface, application, Word
Description automatically generated

Now click on Import button

Graphical user interface, application, Word
Description automatically generated

Go to Collections in Postman and expand AddoMail2CaseHandling, you will be able to see all the endpoints related to the project.
Choose AddoMail2CaseHandling.
Go to Authorization tab
Select Basic Auth from Auth Type combo box
Provide Username and Password

Graphical user interface, text, application
Description automatically generated

Select the method you want to test
Select the Authorization tab and select Inherit auth from parent.

Go to Body Tab
Enter required values
Click Send button then you can see the result.

Graphical user interface, application, Word
Description automatically generated

How to configure projection endpoints in Addovation Sync - Case

All the projection endpoints used in Addovation Sync - Case need to configure in Addovation Portal. This will allow customer to use their own customize projection endpoints. However there are few configuration information we need to setup to support projection endpoints.

ProjectionEndpoint
FieldNames

How to configure projection endpoint

Go to Postman and select the collection
Go to Variables tab
Get the baseUrl current value

Graphical user interface, text, application, email
Description automatically generated

Go to method you want to configure
Get the method name

Graphical user interface
Description automatically generated

Now concatenate base url and method name

Ex: https://ifs.environment.com/main/ifsapplications/projection/v1/AddoMail2CaseHandling.svc/CreateNewCase

Remove IFS extension server url and update rest of the url in to Addovation Sync - Case configuration.

Ex: main/ifsapplications/projection/v1/AddoMail2CaseHandling.svc/CreateNewCase

How to configure FieldNames

Go to Postman and select the method you want to configure
Go to Body tab
Get all the required field names and join them with comma (,) separator

Ex:

CaseId, CaseLocalId, SentFrom, DispName, DescrLight, Descr, Title, DefaultCustomer, Direction, FirstEmail, SendTo, Queue, QueueOrg, SupportKey, SendToCc, Size, Attachment

Graphical user interface
Description automatically generated

An example of final configuration in Addovation Cloud Portal

Graphical user interface, text, application, email
Description automatically generated

Get methods use entire URL with parameters and place the parameters in field names

Graphical user interface, text, application
Description automatically generated

Deployed projections are ready to use. The projection endpoints will be used to configure the Addovation Sync - Case service in the next phase.

Test/Verify Document Management Projection Endpoints

Log in to IFS Cloud
Go to API Explorer
Search AddoDocManagement using Filter Panel -> Projection Name

Select AddoDocManagement projection -> Specification -> OpenAPI v3

A file will be opened as below depicted and copy the whole json text you get in that file.

Graphical user interface, text, application
Description automatically generated

Open Postman and select Import
Then paste the copied Raw text on it

Graphical user interface, application, Word
Description automatically generated

Now click on Import button

Graphical user interface, application, Word
Description automatically generated

Go to Collections in Postman and expand AddoMail2CaseHandling, you will be able to see all the endpoints related to the project.
Choose AddoMail2CaseHandling.
Go to Authorization tab
Select Basic Auth from Auth Type combo box
Provide Username and Password

Graphical user interface, text, application
Description automatically generated

Select the method you want to test
Select the Authorization tab and select Inherit auth from parent.

Go to Body Tab
Enter required values
Click Send button then you can see the result.

Graphical user interface, application, Word
Description automatically generated

How to configure projection endpoints in Document Management

All the projection endpoints used in Document Management need to be configured in Addovation Portal. This will allow customer to use their own customize projection endpoints. However, there are few configurations information we need to setup to support projection endpoints.

ProjectionEndpoint
FieldNames

How to configure projection endpoint

Go to Postman and select the collection
Go to Variables tab
Get the baseUrl current value

Graphical user interface, text, application, email
Description automatically generated

Go to method you want to configure
Get the method name

Graphical user interface
Description automatically generated

Now concatenate base url and method name

Ex: https://ifs.environment.com/int/ifsapplications/projection/v1/AddoDocManagement.svc/CheckInNewDocument
Remove IFS extension server url and update rest of the url into Document Management configuration.

Ex:

int/ifsapplications/projection/v1/AddoDocManagement.svc/CheckInNewDocument

How to configure FieldNames

Go to Postman and select the method you want to configure
Go to Body tab
Get all the required field names and join them with comma (,) separator

Ex: DocClass,Title,LuName,KeyRef,FileExt,DocumentType,DocumentFormat

Graphical user interface, text, application
Description automatically generated

The final configuration in Addovation Cloud Portal Graphical user interface, text, application
Description automatically generated

Get methods use entire URL with parameters and place the parameters in field names

Deployed projections are ready to use. The projection endpoints will be used to configure the Document Management service in next phase.

IAM Client Configuration

Overview

To enable Sync - Case functionality in IFS Cloud, service users must be configured for authentication and transaction authorization.

This involves registering the service user, issuing a secret for token generation, and granting the necessary permissions for accessing specific projections and resources.

Service users differ from regular users as they are identified by a username and do not require a password. The IAM Client provides a Client ID and a secret token, which the service user uses to generate access tokens. When a token is utilized, IFS validates its authenticity. If the service user lacks the required permissions, a 403 Forbidden error is returned.

Below are the key steps involved in setting up IAM Client Configuration:

Creating a Service User and Granting Permissions
Creating an IAM Client

Each service user is tied to a single IAM Client and is configured for a specific channel, such as Sync - Case. The following sections provide a step-by-step guide on how to complete this setup.

Creating a Service User and Granting Permissions

Navigate to IFS Cloud, -> Solution Manager -> Users and Permissions -> Users -> User.
Now Click the + icon to create a new service user.

Provide the following details:

  - Identity: Enter a unique identity for the Service User. 

  - Email: Enter the user’s email address. 

  - Description: Add a brief description for the user. 

  - User Type: Select “Service User” from the available options. 

  - Activation Status: Set the status to “Active”.

Save the new user.

Navigate to User Permissions and select Grant Permission Set to grant permissions to the service user.
Assign the required permissions associated with Sync - Case, as shown in the screenshot below.
Click Ok to confirm the permissions.

The Service User is now successfully created, and the required permissions have been granted.
Proceed to create an IAM Client to complete the configuration process.

Creating an IAM Client

To create an IAM Client, navigate to IFS Cloud > IAM Client and click on the + option.

Enter a unique Client ID and ensure the Enabled option next to the Client ID is selected.
Enable the options for Service Accounts and Direct Access Grants.
From the dropdown menu, select the service user you created earlier as the username, then click Ok.

Next, go to IAM Client Details from the left navigation menu, select the newly created IAM Client, and copy the secret.
Note: You have the option to regenerate the secret if required. However, avoid regenerating the secret when the application is already running.

Allow Email Account Access

There are two ways to configure Azure App Registration to allow email account access from a Function App:

OAuth2 Email Account Access Setup in Azure AD – Uses token-based authentication and retrieves emails via POP3 or IMAP.
Multi-Factor Authentication (MFA) Setup for Email Account Access in Azure AD – Uses certificate-based authentication and retrieves emails via Graph API.

NOTE: You only need to set up one type of Azure App Registration based on the specific requirement.

Oauth2 e-mail account access setup in Azure AD

Azure Active Directory (Azure AD) is a cloud-based identity and access management service. Azure AD enables your employees access external resources, such as Microsoft 365, the Azure portal, and thousands of other SaaS applications.

Create new app registration

Go to Azure Portal
Search for Azure Active Directory

Select App Registration from left side menu and select New Registration

Provide a unique Name for the app
Select Account types based on the access requirement
Select a platform as Web and provide the default url http://localhost:3000/home
Select Register

After few seconds, you will be redirected to the newly created application overview

Request Token

Addovation Sync - Case requires token to authenticate email account. Following steps allow pass the token to Addovation Sync - Case at the account authentication.

Go to the Registered Application
Select Authentication
Scroll down to Implicit grant and hybrid flows
Select Access Token from given options
Select Save button

Add API Permissions

Application needs to permit following scopes with the aim of authenticating resources to email account/s.

Follow the steps to add above scopes to application permissions

Go to the Registered Application
Select API Permissions
Select Add a Permission

Go to Microsoft APIs -> Microsoft Graph -> Delegated permissions
Search for IMAP.AccessAsUser.All
Expand ‘IMAP’ and select IMAP.AccessAsUser.All
Select Add permissions

Repeat the same steps for POP.AccessAsUser.All and SMTP.Send

Select Grand admin consent for [Tenant] and select Yes

Required information to configure email account/s

Tenant ID
Client ID

Above information is required from registered Azure AD Application. Follow these steps to obtain them

Go to the Registered Application
Select Overview

Provide the following information to your representative at Addovation
- Directory (tenant) ID
- Application (client) ID

Setting Up Multi-Factor Authentication for Email Account Access in Azure AD

This section applies to organizations that require multi-factor authentication for accessing email accounts in Azure AD.

Creating a New App Registration in Azure

To create a new app registration, go to Microsoft Entra ID in the Azure Portal.
From the left navigation menu, select App Registrations and then click on New Registration.

Provide a unique name for the application and select the Account type based on the access requirements.
Choose the Platform as Web and enter the default URL: http://localhost:3000/home.
Once all details are filled in, click Register.

After a few seconds, you will be redirected to the overview page of the newly created application. This completes the app registration process.

Requesting a Token

To request a token, navigate to the Registered Application in the Azure Portal and select Authentication from the left navigation pane.
Scroll down to the Implicit Grant and Hybrid Flows section and enable the Access Token option.
Ensure that under Advanced Settings, the option Allow public client flows is set to Yes. Once these settings are configured, click Save.

Adding API Permissions

To configure API permissions for the application, you need to grant the required scopes. The application requires the following permissions:
- Mail.Read – Read user mail
- Mail.ReadWrite – Read and write access to user mail
- Mail.ReadWrite – Read and write mail in all mailboxes
- Mail.Send – Send mail as a user
- Mail.Send – Send mail as any user
- User.Read – Sign in and read user profile
To add these permissions, go to the Registered Application in the Azure Portal and select API Permissions from the left navigation pane.
Then click Add a Permission.

Navigate to Microsoft APIs -> Microsoft Graph -> Delegated Permissions.
Search for mail, expand the Mail section, and select Mail.Read, Mail.ReadWrite, and Mail.Send.

Next, switch to Application Permissions, search for mail, and select Mail.ReadWrite and Mail.Send.
Click Add Permissions to finalize the changes.

Then, select Grant admin consent for [Tenant] and confirm by clicking Yes.

Now share the Client ID of the created application with Addovation to complete the setup.

Uploading a Certificate

To upload a certificate, navigate to Certificates & Secrets in the left navigation pane of the Azure Portal.
Under the Certificates section, click on Upload Certificate.

Select the same certificate that was imported earlier and upload it in one of the supported formats: .cer, .pem, or .crt.

Kindly note that as the App Registration, Key Vault, and Certificate are set up within your Azure portal, you have the ability to manage and control the level of access to the specific email account as needed.

Restricting Certificate-Based Authentication to Specific Email Addresses

To ensure that only specific email addresses have exclusive access while restricting access for other domain email addresses, follow these steps:

Navigate to the Microsoft 365 Admin Center portal.
Go to Teams & Groups > Active teams & groups.

Go to Security groups tab and click on Add a mail-enabled security group

Provide a unique name and an optional description for the group.
Click Next.

Click on Assign owners.
Search for the owner, select them, and click Add.
Click Next.

Click on Assign members.
Search for the required members, select them, and click Add.
Click Next.

Provide a group email address.
Click Next.

Review the group details and click Create group.

Once the security group is created, click Close to exit.

Apply the Created Group Policy to the App Registration

Open PowerShell as Administrator.
Connect to Exchange Online by running the following command:

Connect-ExchangeOnline -UserPrincipalName [admin email account]

Create the Application Access Policy using the command below:

New-ApplicationAccessPolicy -AppId [AppID] -PolicyScopeGroupId [Policy Group Email ID] -AccessRight RestrictAccess -Description "Restrict this app to members of the distribution group EvenUsers."

Verify user access by executing the following command:

Test-ApplicationAccessPolicy -AppId [AppID] -Identity [user@domain.com]

Network Configurations

Click here to read details about network configurations.