Scheduling Unblu conversations with Microsoft Outlook

Prerequisites

This article assumes you are familiar with Microsoft Azure.

The Unblu Outlook add-in only supports Microsoft Office 365 Outlook. Older versions of Outlook aren’t supported.
The add-in runs on the following Microsoft Office 365 platforms:
- Outlook web client
- Windows Outlook rich client
- MacOS Outlook rich client
The Unblu Outlook add-in requires that you host and configure the add-in server component as well as distribute the client-side add-in within your organization as described below.
The Unblu Outlook add-in requires the Unblu Auth Gateway component to authorize agents against Unblu using ID propagation.

Architecture

The diagram below shows the architecture of the Unblu Outlook add-in:

Figure 1. Unblu Outlook add-in architecture

The architecture above uses the Auth Gateway component to authorize calls against Unblu using ID propagation. This service is provided out-of-the-box with the Unblu Cloud. For more information about authentication in an on-premises setup, contact the Unblu Services team.

The diagram also shows an optional proxy server. The proxy isn’t required by the Unblu Outlook add-in but may be present in an on-premises setup.

Installing

The add-in is configured and hosted separately for each Unblu installation and must also be deployed separately for each Unblu installation. Check if your organization can deploy the add-in using Centralized Deployment.

Follow the Microsoft recommendations for deploying Office Add-ins in the Microsoft 365 admin center.

Creating a dedicated app registration in Azure

You must create a dedicated app registration in the Azure Portal to deploy the client-side add-in in your organization.

You must create a dedicated app registration for each environment. If you don’t, the access tokens issued are valid across multiple deployments and environments.

When creating the app registration, as described in the dedicated app registration, make sure you:

Define the tenants that should be able to use the add-in deployment. You can change this later.
Add a redirect URI for the authentication.
1. Select the platform Single-page application (SPA).
2. Set the value to https://<YOUR_DOMAIN>/addin/auth.html. You can configure and change this later, too.
Click Register.

Synchronizing scheduled conversations

If you want changes to the conversations you scheduled in Outlook to be reflected in Unblu, you must use the Unblu Outlook add-in server to synchronize events. The configuration of the Unblu Outlook add-in server is described in the next section. The server is disabled by default.

In the Azure portal, you must also:

Go to the API permissions and add the following Application Microsoft Graph permissions:
- Calendars.ReadWrite

Add a new client secret in Certificates & secrets:

Choose a secret name.

Set an expiration time.

You must renew the certificate periodically. We recommend you prepare a reminder.

Copy the secret and use it for the configuration of the CLIENT_SECRET (see Add-in secrets below).

The Application ID or IDs the app registration creates are used to configure the Unblu Outlook add-in server and the Auth Gateway deployment.

Unblu Outlook add-in server

The Unblu Outlook add-in server component is based on Node.js and provides the following functionality:

Serves the resources (HTML, JS, CSS) that contain the UI elements and execution logic that the add-in uses.
Synchronizes Outlook meetings with Unblu scheduled conversations.

Calendar synchronization is disabled by default. To enable it, set syncServerEnabled to true in the ConfigMap. When enabled, the Unblu Outlook add-in server registers itself for calendar event changes through Microsoft Graph API webhooks.

Synchronization only takes place from Outlook to Unblu. Changes made to a scheduled conversation in Unblu, through the Agent Desk or the web API, aren’t synchronized with the Outlook calendar.

Hosting the Unblu Outlook add-in server

The Unblu Outlook add-in server component is provided as a container image that can be deployed in a Kubernetes or OpenShift cluster. The component is configured through the file /home/node/app/addin/configuration/addin.json, which is populated with the values from the ConfigMap you create.

Here’s an example configuration for a Kubernetes deployment:

Listing 1. Kubernetes configuration example

apiVersion: apps/v1
kind: Deployment
metadata:
  name: outlook-addin
spec:
  replicas: 1
  selector:
    matchLabels:
      component: outlook-addin
  template:
    metadata:
      labels:
        component: outlook-addin
    spec:
      containers:
        - name: outlook-addin
          image: outlook-addin
          envFrom:
          - secretRef:
              name: outlook-addin-secrets
          resources:
            requests:
              memory: "128Mi"
              cpu: "100m"
            limits:
              memory: "128Mi"
              cpu: "1000m"
          ports:
            - containerPort: 8080
              name: http
          readinessProbe:
            httpGet:
              port: 8080
              path: /ready
            initialDelaySeconds: 5
            failureThreshold: 1
            periodSeconds: 5
            successThreshold: 1
            timeoutSeconds: 5
          livenessProbe:
            httpGet:
              port: 8080
              path: /live
            initialDelaySeconds: 10
            failureThreshold: 3
            periodSeconds: 15
            successThreshold: 1
            timeoutSeconds: 5
          volumeMounts:
            - name: outlook-addin-config
              mountPath: /home/node/app/addin/config/addin.json
              subPath: addin.json
      volumes:
        - name: outlook-addin-config
          configMap: (1)
            name: outlook-addin-config
---
apiVersion: v1
kind: Service
metadata:
  name: outlook-addin
spec:
  type: ClusterIP
  selector:
    component: outlook-addin
  ports:
  - name: http
    port: 80
    protocol: TCP
    targetPort: http
---
kind: Kustomization
apiVersion: kustomize.config.k8s.io/v1beta1

resources:
  - deployment.yaml
  - service.yaml

configMapGenerator:
  - name: outlook-addin-config (1)
secretGenerator:
  - name: outlook-addin-secrets (2)

1	For information on the `ConfigMap`, refer to Add-in `ConfigMap`
2	For information on the secrets, refer to Add-in secrets

Add-in `ConfigMap`

The Unblu Outlook add-in has the configuration options listed below. The options are set in the ConfigMap you specify in your Kubernetes configuration.

deploymentUrl: The URL the Unblu Outlook add-in server is deployed to. The add-in’s manifest.xml and web resources are served from here.
deploymentAddinEndpoint: The base path to access all add-in endpoints.
unbluOAuthBackendUrl: The URL of the Auth Gateway in front of the Unblu Collaboration Server.
clientId: The application registration ID on the Azure portal.
authority: The application registration ID on the Azure portal.
tenantIds: List of supported Azure tenants.
syncServerEnabled: Enable the Unblu Outlook add-in server. The default value is false.
syncServerAuthGatewayClientId: The client ID of the Unblu Outlook add-in server for the Auth Gateway.
syncServerSubscriptionExpiration: The timeout for calendar event subscriptions given in miliseconds. Subscriptions are renewed automatically after half the time of syncServerSubscriptionExpiration has passed. This option is primarily intended for debugging purposes.
syncServerSubscriptionRenewalLimit: A limit after which a renewal of the subscription is enforced. Overrides syncServerSubscriptionExpiration in case the value is smaller than half of syncServerSubscriptionExpiration. This option is primarily intended for debugging purposes.
syncServerPollingCronInterval: The interval for the Unblu Outlook add-in server to check for almost expired calendar subscriptions. UNIX cron format is used.
logLevel: Server component log level. Possible values are debug, info (default), warning, and error.

The following configuration options are only intended for debugging purposes:

debugMode: Write more logs in the add-in client.
showDebugPane: Shows the task pane used for debugging.

The example below shows an addin.json config file to be used for the config map:

{
    "deploymentUrl": "https://domain.com/",
    "deploymentAddinEndpoint": "addin",
    "unbluOAuthBackendUrl": "https://domain.com/gateway",
    "clientId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "tenantIds": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"],
    "syncServerEnabled": true,
    "syncServerAuthGatewayClientId": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    "syncServerSubscriptionExpiration": "36000000",
    "syncServerSubscriptionRenewalLimit": "72000000",
    "syncServerPollingCronInterval": "*/1 * * * *"
}

The example assumes that the Auth Gateway component is made available through an ingress on the path gateway.

Add-in secrets

If you run the Unblu Outlook add-in server, you must configure the following secrets in Kubernetes:

CLIENT_SECRET: OAuth2 client secret for authentication against the Microsoft Graph API, corresponds to clientId.
SYNCSERVER_AUTH_GATEWAY_CLIENT_SECRET: OAuth2 client secret for authentication against the Auth Gateway proxy authentication server.

Multi-tenancy

To allow multiple tenants to use the add-in, make sure all tenants are supported in the setting tenantIds. The Unblu Outlook add-in sends user authentication requests to https://login.microsoftonline.com/common. You must use /common as the value for your tenant because dedicated tenant-specific logins aren’t supported.

Using the Unblu Outlook add-in

When the Unblu Outlook add-in is installed, an Unblu Conversation button is displayed in the Outlook menu ribbon when creating or editing events.

*Unblu Conversation* button in event menu ribbon

Figure 2. Unblu Conversation button in the edit event menu ribbon

Clicking Unblu Conversation creates an Unblu scheduled conversation and adds a public link to the calendar event that future participants can use to join the conversation.

For information on how participants can use the link, refer to Redeeming a public link invitation.

If a user schedules a meeting in Outlook and adds an Unblu conversation, but then doesn’t save the meeting, the add-in still creates a scheduled conversation in Unblu.

Synchronizing with Unblu

If you enable synchronization (see syncServerEnabled above), changes to an event’s topic or scheduled time in Outlook are synchronized with the scheduled conversation in Unblu. Deleting the event in Outlook also deletes the scheduled conversation in Unblu, provided the conversation’s state is CREATED and the agent is the sole participant.

Make sure the following configuration properties are set to true in Unblu:

Synchronization only takes place from Outlook to Unblu, not the other way around.