1. Knowledge base
  2. Yva.ai on-premise installation

Yva.ai deployment manual with Microsoft 365 data source

This documentation describes a system deployment and operation scenario for Self-hosted Yva.ai Solutions on Microsoft Azure infrastructure with Microsoft 365 data source

Yva.ai platform overview 

Yva.ai is an AI-driven real-time employee experience and performance platform based on Smart surveys. Smart surveys is a patented way to conduct short (60-120 sec) individualized peer-to-peer surveys based on Collaboration circles - the objective data “who works with who” in corporate productivity systems. 

Optionally (with employee consent), Yva.ai conducts Collaboration analytics (passive analytics).

The configuration of Yva.ai, administrative activities and access to the results of Yva.ai are carried out through the client’s web interface, which is installed along with the server.

If you are intended to use the Yva.ai Cloud Services, please refer to Yva.ai Cloud Services installation

If you are intended to use the Self-hosted Yva.ai Solutions with Google Workplace source, please contact support@yva.ai for additional information

Service Architecture

Components and communications information system.

(1) Office 365 Mail Server

(2) Platform Yva.ai. 

The principles of microservice distributed architecture (based on Docker) are applied to Yva.ai. Each service operates in a separate docker-container. The connection between the application components is provided by the Consul discovery service. MongoDB is used as a DBMS. The message broker is RabbitMQ.

Operation does not require access to external resources. 

The platform:

  • Receives and processes the list of users and emails from Microsoft 365 via HTTPS / 443 (Microsoft Graph)
  • Authorizes users and administrators via SSO using a username / password pair
  • Sends emails with weekly surveys to users via the SMTP server using the port, specified in the Yva.ai settings. It is possible to use any SMTP relay server without authentication.
  • Provides the system’s web interface to internal users and administrators (on HTTPS / 8080 and HTTPS / 443).
  • Stores email processing data, user and group data in the MongoDB

(3) Internal users and administrators:

Users:

  1. receive invitations to complete weekly email surveys 
  2. have access to their personal account on the Yva.ai server  (HTTPS / 443). The attempt to access the server is authenticated through AD or other authentication sources (SSO)

Administrators:

  1. have access to the web-based platform management interface (HTTPS / 8080)
  2. receive service messages from the platform via email

Step 1. Installing Platform

To start the installation, please follow the link https://github.com/yva/arm

Click “Deploy to Azure” (see the screenshot below)

You will have to use Microsoft Azure administrator account to sign-in

Enter the attributes that need to be filled during the process. Refer to the table below for more information on each of the attributes.

Attribute Name

Common Description

Details

yvaname

Mandatory:

Domain name of the server on which the platform is being installed

Prefix used by Azure to generate the URL gateway. For example, if you specify yvaname, the following URL yvaname.westeurope.cloudapp.azure.com will be created after deployment.

yvalogin

Mandatory:

Username authentication system Yva.ai

This data is provided by the Yva.ai manager . Please contact your account manager for additional information. 

yvapass

Mandatory:

Yva.ai internal authentication password

This data is provided by the Yva.ai manager . Please contact your account manager for additional information. 

securestring

Mandatory:

Administrator’s password

The password that will be used to access the admin panel after deployment.

size

Mandatory:

Number of servers to be deployed.

Values: medium, large, xl

Number of servers required depends on employee quantity. Description on every types of servers (medium, large, xl) is available in System requirements

Yva.ai URL configuration

After the installation, login into the Administrator’s control panel. Your URL should look similar to the following: https://yvaname.westeurope.cloudapp.azure.com/admin/general-settings/lets-encrypt
Configure URL settings of the platform as required. 

Step 2. Creating a Microsoft application for Microsoft 365 data access

The interaction of the Yva.ai platform with Microsoft 365 is implemented using an encrypted protocol via the Microsoft Graph API. A detailed description of the technology is available at https://docs.microsoft.com/en-us/graph/overview

In order to create an application, you will need a Microsoft account. To ensure a successful deployment, you need to use an account that has Microsoft 365 administrator rights.

While deploying Yva.ai in Microsoft Azure, you can create a domain name that will be used later to access the workspace of your company. If you didn't create one, it will automatically be created by Microsoft Azure. 

In this guide, yva.company.com is used as an example. 

To create an application:

  • Click “+ New registration”
  • Enter a name for your application in the Name field and click “Register”

We recommend using YvaApp as the name of the application

  • Once the application is created, copy and save the Application ID as it will be required during the setup of the Yva.ai application
  • Go to the “Certificates and Secrets” section and click “+ New client secret”. 
  • On the modal window, enter a description and choose Expires - Never
  • Click “Add”
  • Copy and Save the Client Secret as it will be required during the configuration of the Yva.ai application.
  • Go to the “Api permissions” and click  “Add a permission” then click on “Microsoft Graph”.
  • Click “Delegated permissions” and using Search, select the following rights and click “Ok”
  1. Contacts.Read
  2. Mail.Read
  3. User.Read.All
  4. Directory.Read.All
  • Perform the same operation with “Application permissions”.
  1. Contacts.Read
  2. Mail.Read
  3. User.Read.All
  4. Directory.Read.All
  • Click “Add permissions” then click “Grant admin consent” and follow the instructions
  • Go to the “Authentication” section and add the Redirected URIs.
  1. https://yva.company.com/api/users/callback/oauth2/office365
  2. https://yva.company.com/api/users/callback/oauth2/accounts
  3. https://yva.company.com/sso/externallogin/callback
  4. https://yva.company.com/api/sources/office365/oauth/callback

(where “yva.company.com” is your platform URL, in example on the screenshot it is newoffice.westeurope.cloudapp.azure.com)

  • Click “Save” to save the changes

If the process is successfully completed, you will need to keep the following details:

  1. Application Name
  2. Application ID value
  3. Client Secret value

Step 3. Connecting the source

When the platform is successfully installed and the source configuration is completed, follow the steps below to connect Microsoft 365 to the platform. 

Open the Administrator’s interface https://yvaname.westeurope.cloudapp.azure.com/admin

Go to Integration settings -> Microsoft application and enter a name for the application including Application ID value and Client Secret value (you would have saved these value in the Step 2)

Click “Apply”.

Yva.ai Workspace configuration

To create a workspace for the first time: 

Follow the link https://yvaname.westeurope.cloudapp.azure.com/create-workspace

Specify the name of the workspace

Create a login / password for the first user. With this credential, it will be possible to log in to the system, even if all other authorization methods are disabled or inoperable or sources are not connected. 

To connect the source:

Go to Company Settings -> Manage sources, 

Choose Office 365.

Click “Connect” 

Step 4. Managing Users

The last step of the installation process is to activate the users who will be included in the reports. Here are the key steps to follow:

Select the employees who will be included in the reports

Open the page https://yvaname.westeurope.cloudapp.azure.com/dashboard/admin/users

Access rights

By default, all employees only have access to their personal report. If you need to grant more access rights, check the boxes next to employees.

"Company manager rights" provides access to group reports on employees and the company.

"Administrator rights" provides access to the workspace settings.

Analytics privacy levels

Each company can decide on a comfortable analytics privacy level.  Yva.ai provides the following privacy levels:

  • Regular surveys (active analytics);
  • Smart surveys (active analytics with collaboration circles);
  • Smart surveys with collaboration analytics (active and passive analytics) ;
  • Collaboration analytics (passive analytics).

By default, Yva.ai will not collect passive data from the employees. It will only collect collaboration circles data to drive the peer-to-peer Smart surveys.

From the list of employees “Administrator” should tick the “Send surveys” checkbox for each employee who should receive the regular surveys.

If a company wants to collect “passive feedback” from an employee, “Administrator” should tick the “Collect passive data” checkbox for that employee.

You as an administrator can choose both “Send surveys” and “Collect passive data” for the employees.

If the “Include in 360 feedback” checkbox is ticked, peer review is activated. Peer review helps to form the skill map and skill set for an employee.A group of employees or a peer group, for whom the 360 feedback is activated, will receive questions for peer review.

In the "Administration" section, there are also settings for the interface language and time zone for each employee. They are used for synchronizing an employee's work hours with the time for sending surveys.

Recommended startup settings

For the first two weeks, we recommend that you as an administrator do not grant other employees nor the manager any Administrator rights. We also do not recommend connecting employees to surveys for the first two weeks.

During this time, the company should get used to the feedback system and can gradually involve other employees in participation. Then Manager and Administrator rights can also be distributed and surveys can also be launched.

At the initial stage, we recommend enabling passive data collection only: the system will start collecting data and processing it. In the meantime, HR specialists can set up surveys.