External Calendar – Outlook Calendar Configuration Example
Creating OAuth Client on Deepser
In the Deepser Configuration in System > Tools > OAuth > Client > Add a new Client with the following values:
Name: You can choose your custom name
Provider: Azure
Type: Azure App Permission
Then you can proceed with saving.
After saving, Deepser will provide to you the “Redirect URI” that you need to copy and use for configuration on Azure Admin Portal.
Creating your APP on Azure
After complete the first step of configuration on Deepser go to the Azure portal and sign in with your Office 365 account.
Once logged in, click on App Registrations
Then click New Registration.
On App Registration we can proceed entering the following information:
- Name for the new App,
- Supported Account as “Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)”,
- Redirect URI as “Web” type (Previously generated and copied from Deepser Oauth Client)
In conclusion you can click on “Register” button.
App Authentication
You can now access your newly registered application and navigate to ‘Manage > Authentication’ from the menu.
From here, you can confirm that the correct Redirect URI is set under the ‘Web’ section, and enable the following tokens:
- Access tokens (used for implicit flows)
- ID tokens (used for implicit and hybrid flows)
App Certificate & Secret
Under “Manage > Certificates & secrets” in the menu, you can create a secret. During the configuration process, you’ll need to set its expiration time and copy its value, which will be used later to complete the configuration in Deepser.
The copied secret value will need to be entered into the field “Client Secret” on the oauth client record in Deepser:
Notes:
- Be sure to copy the value of the secret, not the Secret ID.
- You must copy the secret value during the creation phase, as you won’t be able to access it later (in that case, you would need to recreate it).
- If you set an expiration for the secret, remember to renew it before the expiration date
App API permissions
Under “Manage > API permissions” in the menu, you can add the following permissions for Microsoft Graph and then run the “Grant admin consent” action:
- Read as Application Permission
- ReadWrite as Application Permission
Click on “Add a permission” to open the permission selection prompt:
Then select “Microsoft Graph” as API permission to use:
From this screen you can choose Application permissions and use the search field for research the desired permission to add:
After adding all desired permissions, you can run Grant admin consent command:
Before going back to the Oauth Client in Deepser and complete the configuration, we can note down all the Azure information to be used in Deepser Oauth client configuration. Below is a summary of the Azure information to be reported in Deepser:
- Secret Value
NOTES: Be sure to copy the value of the secret, not the Secret ID.
You must copy the secret value during its creation phase, as you won’t be able to access it later (in that case, you would need to recreate it).
- Application (client) ID
- Directory (tenant) ID
Complete OAuth Client Configuration on Deepser
You can now return to the Deepser Oauth Client record to proceed with the completion of configuration.
Deepser – General Tab
If not already done, please configure “Provider” and “Type” field respectively as “Azure” and “Azure App Permission”.
Then we can proceed to set Client ID and Client Secret:
In the “Client ID” field, enter your “Application (client) ID” from Azure.
In the “Client Secret” field, enter your “Secret Value” from Azure.
Deepser – Provisioning Tab
In the provisioning tab you will need to fill the “Tenant ID” field.
In the “Tenant ID” field, enter your “Directory (tenant) ID” from Azure.
Calendar Configuration
By configuring an External Calendar, you are able to sync all desired entities from Deepser to Outlook Calendar. The synchronization works in the following ways:
- Deepser can create events on the Outlook calendar
- Deepser can delete events (only previously synchronized) on the Outlook calendar
- Outlook Calendar can update previously synchronized events on Deepser
In the example below we configure a sync between tasks of a specified user in Deepser with his calendar on Outolook.
External Source Configuration
An external source is used to link Deepser models, such as operation, activity, or task, with external calendars. An admin user can add an external source by navigating to SYSTEM > CALENDARS > EXTERNAL > SOURCE.
Below an example for an “External Source” based on Task syncronization between Deepser and Outlook Calendar:
- Name: You can choose your custom name
- Model: You need to select “DeepTask – Task” as model.
- Prepared Collection: You need to filter tasks you want to sync. In this example we are configuring an external source for sync all tasks assigned to user “oauth1/example@ex.com”.
- Upload Field Config:
$event[‘name’] = $model->getTitle();
$event[‘description’] = $model->getDescription();
$event[‘start’] = $model->getStartedAt();
$event[‘end’] = $model->getEndedAt();
NOTE: with this field, you can map fields to create events on external calendar.
- Download Field Config:
$model->setTitle($event[‘name’]);
$model->setDescription($event[‘description’]);
$model->setStartedAt($event[‘start’]);
$model->setEndedAt($event[‘end’]);
NOTE: with this field, you can map fields to update tasks on Deepser.
External Calendar Configuration
After External Source configurations, you can proceed with the external calendar configuration for each User you want to configure.
An Admin user can add an External Calendar from SYSTEM > CALENDARS > EXTERNAL > CALENDAR.
Below an example for an “External Source” based on Task syncronization between Deepser and Outlook Calendar for the user “oauth1/example@ex.com”:
Below are the details of the fields to be configured:
- Name: Set your own custom name
- Cron Expression: Set how frequently the synchronization will be executed (every minute in the example).
- Type: Select “Outlook Calendar (Graph v1.0)” for Outlook calendar sync.
- OAuth Client: Select the previously created OAuth client.
- User: Choose the Outlook user you want to sync.
- External Source: Select the previously created source (tasks filtered by the assigned user).
- Unique Id: Specify the calendar on which you want to sync the tasks.
- Start Date: Only events (and changes to events) with a start date and time equal to or later than this will be retrieved from the server.
- Timezone: Select your current timezone to handle dates consistently between Outlook and Deepser.
NOTE: The operations indicated in the “External Source Configuration” and “External Calendar Configuration” sections must be repeated for each user for whom synchronization with the Outlook calendar is to be enabled.
