Step 2: Prepare your Booking System

In order to integrate Evoko Liso with your existing booking system some preparation in the booking system is necessary.

Please select the booking system which you want to integrate with Evoko Home in the list below and follow the instructions in that section.

Note! If you plan to use the standalone system of Evoko Booking you can skip this step 2.

• Step 2a: Microsoft 365
• Step 2b: Exchange 2019 / 2016 / 2013
• Step 2d: Google Workspace
• Step 2e: IBM Domino
• Evoko Booking

Step 2a: Microsoft 365

Formerly known as Office 365.

This article will cover the process of preparing Microsoft 365 for integration with Evoko Home. 

It will cover the steps for both Modern and Legacy Authentication.

Basic Authentication: Commonly referred to as "Legacy Authentication," relies on using username and passwords for the service account.  These credentials are used to connect to Exchange Web Services (EWS) to access data in Exchange.  This data is then synchronized to and from the Evoko Home Service.

Modern Authentication: Commonly referred to as "oAuth." relies on the Global Administrator in your organization to grant permission to the Evoko Home Service to access the EWS application through an oAuth flow in Azure Active Directory.  The Evoko Home Service can the access EWS using a certificate-based authentication flow.

The Legacy/Basic Authentication will be out of support in Late 2020 as Microsoft has announced.  We recommend using Modern Authentication over Legacy.

• Create a Service Account (Required for both Modern and Legacy)
• Grant Impersonation rights to the Service Account (Required for both Modern and Legacy)
• Create Room Mailboxes (Required for both Modern and Legacy)
• oAuth Preparation (Required for Modern Only)

Create a Service Account

The Service Account will be used for authentication and carrying the requests between Evoko Home and Microsoft 365 via EWS.  Therefore we recommend creating a dedicated account for this purpose.

To create the service account, follow the below steps, please note that you will need Administrator permission to do these steps.

1. Go the Exchange Admin Center here: https://portal.office.com/adminportal/home#/homepage and login with your Exchange Admin Account.
   
2. From the users menu, click active users, then add a user, fill in the required fields and press next.
   
3. Select the location of the user and assign a product license for the use, then press next.
   

   Important! The service account needs a mailbox and therefore also a license.

   
4. Leave the optional settings as default and press next.
5. The Summary Window will appear and show the information about the newly created Service Account, check the information and verify it is indeed correct.  Then press finish adding.
6. After a few moments the Service Account User will be ready to be used.

Grant the service account Impersonation rights

Impersonation can be granted via either Windows PowerShell (Option #1) or via the Microsoft 365 Admin center (Option #2) and with or without a management scope, we have listed two options below.
For security practices we recommend granting Impersonation with a management scope.

Option #1: With a management scope using Windows Powershell

The below method will grant your service account with impersonation permissions restricted only to resources (room and equipment mailboxes) by applying a “management scope”/“Write scope”.

1. Start off by connecting to your Microsoft 365 environment via Windows PowerShell and authenticate with your Microsoft 365 admin account. This is typically done by running the following commands:

   ## On the “Execution Policy Change” question type “Y” and press “Enter”.
   Set-ExecutionPolicy RemoteSigned
   
   ## This will prompt a pop-up asking for credentials.
   ## Enter the user name and password for your Microsoft 365 admin account and click “Ok”.
   $UserCredential = Get-Credential
   
   ## Create session
   $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection
   
   ## Import session
   Import-PSSession $Session

2. Create a management scope which will be used in the next step to restrict the impersonation right. The below command will limit the scope to resources (room and equipment mailboxes):

   New-ManagementScope -Name "ResourceMailboxes" -RecipientRestrictionFilter { RecipientTypeDetails -eq "RoomMailbox" -or RecipientTypeDetails -eq "EquipmentMailbox" -or PrimarySmtpAddress -eq "service-account@domain.com"}

   Note! Make sure to replace service-account@domain.com in the above command with the equivalent for your service account.
   Important! For modern authentication (oAuth), the service account must be part of the above scope.
3. This will grant the service account Impersonation using the management scope:

   New-ManagementRoleAssignment –Name "ResourceImpersonation" –Role ApplicationImpersonation -User service-account@domain.com –CustomRecipientWriteScope "ResourceMailboxes"

   Note! make sure to replace service-account@domain.com in the above command with the equivalent for your service account.
4. Confirm that impersonation has been granted to your service account:

   Get-ManagementRoleAssignment -Role “ApplicationImpersonation” -GetEffectiveUsers

   The above command will display a table of accounts assigned with impersonation. Please make sure that in the Role column the value is ApplicationImpersonation, and in that same row under the EffectiveUsername is the name of your service account. If so, that means the setup of the impersonation was successful.
5. Disconnect from the Powershell session:

   Remove-PSSession $Session

Option #2: Without a management scope via the Exchange admin center

The below method will grant your service account with impersonation permission for all accounts.

1. Go to https://portal.office.com/adminportal/home and log in with your Exchange Admin Account.
2. Select "Exchange" on the left bar.  Then Select: Permissions --> Admin Roles --> Add (+)
   
3. Under "Name" enter "Application Impersonation."  Under "Description" is up to the user, and the "Write Scope" can be kept at the default.
4. Under the "Roles", click and add the Admin Role: "Application Impersonation.
   
5. Under the members, click and add the Service Account.
6. Save, and close the window.

Create Room Mailboxes

Room mailboxes can also be called resource mailboxes.  These are the calendars that are being used to book rooms for example from Outlook.

Evoko Home will sync the data of the room mailbox's calendar so the meeting will be populated via Evoko Home to the Evoko Liso outside of the meeting rooms.

Please make sure the room resource is not hidden from the global address list in Exchange.

1. Go to https://portal.office.com/adminportal/home and log in with your Exchange Admin Account
2. From the Exchange Admin Center, navigate to "Recipients" and then click on "Resources."
   
3. Click the (+) Button and Select "Resource Mailbox"
4. Enter the "Room Name" and specify the resource accounts "Email Address."  Optionally add a "Location/Capacity" and continue by clicking "Save."
5. If you want to create more resources kindly repeat the above steps.
6. We recommend you configure the resource account with the below cmdlet using Windows PowerShell.

   Set-CalendarProcessing room1@domain.com -AutomateProcessing AutoAccept -AddOrganizerToSubject $False -DeleteComments $False -DeleteSubject $False -RemovePrivateProperty $false

Create room lists using Windows PowerShell (Optional)

Room lists help you to organize your rooms. If your company has several buildings with rooms that can be booked for meetings, it might help to create a room lists per building or even per floor.

Room lists are specially marked distribution groups that you can use the same way you use distribution groups. In Evoko Home you can import room lists which makes it a convenient way to add your rooms.

The below commands will help you to create a single room list and then add rooms, or create a single room list that holds all existing rooms in one go in Microsoft 365 using Windows PowerShell:

• Creates a new room list named “My Rooms”:

  New-DistributionGroup -Name "My Rooms" –RoomList

• Adds a resource account (room1@domain.com) to an existing room list (My Rooms):

  Add-DistributionGroupMember -Identity "My Rooms" -Member room1@domain.com

• Fetches all resources (room mailboxes) and puts them in a single new room list named My Rooms:

  $RoomAlias = Get-Mailbox -RecipientTypeDetails RoomMailbox | select -ExpandProperty Alias New-DistributionGroup -RoomList -Name "My Rooms" -Members $RoomAlias

• Displays a table of all room lists in your Microsoft 365 environment:

  Get-DistributionGroup | Where { $_.RecipientTypeDetails -eq "RoomList" } | Format-Table DisplayName, Identity, PrimarySmtpAddress

Modern Authentication / oAuth Preparation

Step 2b: Exchange 2019/2016/2013

This part will go through the necessary preparations needed in Exchange 2019/2016/2013 to integrate Evoko Liso.

• Create a service account
• Grant the service account Impersonation rights
  
  • Option #1: With a management scope using the Exchange Management Shell
  • Option #2: Without a management scope via the Exchange admin center
• Create resource accounts
• Create room lists using the Exchange Management Shell (Optional)

Create a service account

We recommend using a dedicated service account (e.g. service-account@domain.com) for integrating Evoko Liso with an Exchange 2019/2016/2013 environment. This account will be used for authentication and carrying out requests between the Evoko software and Exchange 2019/2016/2013 via EWS (Exchange Web Services). 

1. Open "Active Directory Users and Computers" and create a user. This is typically done by navigating to the desired Organizational Unit (OU) > right click > "New" > "User".
   
2. Fill in the necessary information for your service account and click “Next” to continue.
   
3. Enter the password for your service account and click “Next”.
   
4. Review the data and click “Finish” to create the user in Active Directory.
   
5. Next go to https://<Exchange server>/ecp/ and login with your Exchange admin account.
   
6. In the Exchange admin center navigate to "recipients" > "mailboxes".
   
7. Click add and select "User mailbox".
   
8. Fill in an alias and select the service account in Active Directory, then click "save".
   
9. Once your service account is created it should appear in the list of mailboxes.
   

Grant the service account Impersonation rights

Impersonation can be granted via either Exchange Management Shell (Option #1) or via the Exchange Admin center (Option #2) and with or without a management scope, we have listed two options below.
For security practices we recommend granting Impersonation with a management scope.

You can read more about our decision on using impersonation rather than delegation in this article.

Option #1: With a management scope using the Exchange Management Shell

The below method will grant your service account with impersonation permissions restricted only to resources (room and equipment mailboxes) by applying a “management scope”/“Write scope”.

1. Start of by launching the Exchange Management Shell on the Exchange server.
2. Create a management scope which will be used in the next step to restrict the impersonation right. The below command will limit the scope to resources (room and equipment mailboxes):

   New-ManagementScope -Name "ResourceMailboxes" -RecipientRestrictionFilter { RecipientTypeDetails -eq "RoomMailbox" -or RecipientTypeDetails -eq "EquipmentMailbox" }

3. This will grant the service account Impersonation using the management scope:

   New-ManagementRoleAssignment –Name "ResourceImpersonation" –Role ApplicationImpersonation -User service-account@domain.com –CustomRecipientWriteScope "ResourceMailboxes"

   Note! make sure to replace service-account@domain.com in the above command with the equivalent for your service account.
4. Confirm that impersonation has been granted to your service account:

   Get-ManagementRoleAssignment -Role “ApplicationImpersonation” -GetEffectiveUsers

   The above command will display a table of accounts assigned with impersonation. Please make sure that in the Role column the value is ApplicationImpersonation, and in that same row under the EffectiveUsername is the name of your service account. If so, that means the setup of the impersonation was successful.
5. Disconnect from the Powershell session:

   Remove-PSSession $Session

Option #2: Without a management scope via the Exchange admin center

The below method will grant your service account with impersonation permission for all accounts.

1. In the Exchange admin center, navigate to “permissions” > “admin roles" > and click the add-button.
   
2. Under "Name" enter “Application Impersonation". The "Description" can be left empty and the "Write scope" can be kept at "Default".
   
   
   Tip! If a management scope is created in your environment (as done in step 2 of option #1) then it will be displayed in the drop-down list under "Write scope" and possible to apply.
3. Under "Roles" click add and add the admin role "ApplicationImpersonation".
   
4. Under "Members" add your service account and then click "Save".
   

Create resource accounts

A resource account or room mailbox is the calendar used to book the room via e.g. Outlook and the calendar Evoko Liso/Home will synchronize meeting data with. One resource account per Evoko Liso is necessary unless you want two or more Evoko Liso synchronizing with the same calendar.

1. In the Exchange admin center navigate to "Recipients" > "Resources".
   
2. Click the "+" and select "Room mailbox".
   
3. Enter the "Room name" and specify the resource accounts "Email address".
   Optionally add a "Location" and enter the "Capacity" and continue by clicking "Save".
   
4. Your resource account should now appear in the list of resources.
   
5. We recommend you configure the resource account with the below cmdlet using the Exchange Management Shell:

   Set-CalendarProcessing room1@domain.com -AutomateProcessing AutoAccept -AddOrganizerToSubject $False -DeleteComments $False -DeleteSubject $False -RemovePrivateProperty $false

Create room lists using the Exchange Management Shell (Optional)

Room lists help you to organize your rooms. If your company has several buildings with rooms that can be booked for meetings, it might help to create a room lists per building or even per floor.

Room lists are specially marked distribution groups that you can use the same way you use distribution groups. In Evoko Home you can import room lists which makes it a convenient way to add your rooms.

The below commands will help you to create a single room list and then add rooms, or create a single room list that holds all existing rooms in one go using the Exchange Management Shell:

• Creates a new room list named “My Rooms”:

  New-DistributionGroup -Name "My Rooms" –RoomList

• Adds a resource account (room1@domain.com) to an existing room list (My Rooms):

  Add-DistributionGroupMember -Identity "My Rooms" -Member room1@domain.com

• Fetches all resources (room mailboxes) and puts them in a single new room list named My Rooms:

  $RoomAlias = Get-Mailbox -RecipientTypeDetails RoomMailbox | select -ExpandProperty Alias New-DistributionGroup -RoomList -Name "My Rooms" -Members $RoomAlias

• Displays a table of all room lists in your Office 365 environment:

  Get-DistributionGroup | Where { $_.RecipientTypeDetails -eq "RoomList" } | Format-Table DisplayName, Identity, PrimarySmtpAddress

Step 2d: Google Workspace

Formerly known as Google G Suite.

• Create a New GSuite Project and Enable APIs
• Create a Service Account
• Grant Service Account API Access
• Create and Configure Resource Calendar 

Create a New Project and Enable APIs

1. Go to https://console.developers.google.com/cloud-resource-manager and log in as a Google Domain Admin.
2. Press "Create Project"
3. Select a name for your project and press "Create."
4. Wait for the project to be created.  Once created created navigate to your new project.
5. In the navigation side bar please select "APIs & Services"
6. Press "Enable APIs and Services"
7. Under "Google Workspace" Select "Google Calendar API"
8. Press "Enable"
9. Again under "Google Workspace" select "Gmail API"
10. Press "Enable:
11. Again under "Google Workspace" select "Admin SDK"
12. Press "Enable"

Create a Service Account

1. Navigate to "IAM & Admin" --> "Service Accounts"
2. Press "Create Service Account"
3. Enter a Service Account Name (We recommend Evoko-Liso) and press "Create and Continue"
4. Select the role this account will be using: "Service Account Admin" and press continue.
5. This should bring you to a list of Service Accounts for the project you have created.  Under the actions menu for this project click on "manage keys."
6. Press the "Add Key" button and generate a "New Key"
7. Select P12 as the type of key.
8. The generated P12 Key will be downloaded to the local machine.  You will need this P12 key when going through the Evoko Home Wizard so make sure it is in a safe place.  Press close on the dialogue box when prompted.
9. This will bring you to a list of service accounts created for your project.  Please click on your newly created service account.
10. Under the "Details" tab you will need to Enable Google Workspace Domain Wide Delegation.
11. You may also be prompted to enter a Product Number for the Consent Screen.  We recommend using Evoko Liso.  Press Save when done.
12. Here it lists the "Client ID (Unique ID)" which needs to be noted and written down as it will be needed during the installation process of Evoko Home.  When the Client ID has been copied down you may press the back arrow.

Grant Service Account API Access

1. Now go to https://admin.google.com and navigate to "Security."
2. Navigate to "API Controls" and click on "Manage Domain Wide Delegation."
3. Click "Add New"
4. Here you will need to input the Client ID that was generated for your Service Account.  You will also need to copy and paste these three comma separated API scopes to your project:

   • https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/calendar, https://www.googleapis.com/auth/gmail.send

5. After clicking on "Authorize" you should now se the Client ID of your Service Account listed with the Appropriate API Scopes Applied.

Create and Configure Resource Calendars

1. Go to https://admin.google.com and navigate to "Apps"
2. Press "Google Workspace"
3. Press "Calendar"
4. Scroll to  "General Settings" and then "External Sharing Options for Secondary Calendars"
5. "External Sharing Options for Secondary Calendars" needs to be set to one of these two options.
6. Next step is to add one or several resource calendars.  To do so, navigate to "Resource."  NOTE - If you already have resource calendars set up in your environment you can skip to the subscribing step.
7. Press "Add New Resource"
8. Add the details for your Resource Account and then click "Add Resource"
9. Now navigate to https://www.google.com/calendar and in the calendar side menu under "Other Calendars" browse for your newly created resource and click the check box icon for access.
10. The Resource Calendar should now show up under "My Calendars," click on the arrow next to the Resource Name and Press "Settings and Sharing."
11. Under "Share with Specific People" assign the email address for your Service Account.  Under Permission Settings, select "Make Changes to Events" and then press "Add Person."  Note: If you require PIN or RFID authentication to book you will need to add the users that can book with "Make Changes to Events" access.
    
12. Note that it can take up to 24 hours to populate all of this information in G Suite.  We recommend waiting at least 24 hours before attempting to configure Evoko Home using these accounts!

Step 2e: IBM Domino

This part will go through the necessary preparations needed in IBM Domino to integrate Evoko Liso.

• Domino Prerequisites
• Install the Evoko database
• Setup mail file access
• Verify installation

Domino prerequisites

• Domino 8.5.3 or above.
• Domino server running the Calendar, Scheduling and HTTP tasks.
• Resources and one administrator account to manage the room resource calendars (in this guide we use a user named "Roommate Evoko/Evoko" as example).
• Resource calendars.

Install the Evoko database

1. Create a user, in our examples called "Roommate Evoko/Evoko" with necessary rights to create databases and rights to sign or run restricted LotusScript /Java agents (you can also use an existing account if preferred).
2. Create or use an existing mailbox for Remote Management and statistics.
3. Check/specify the User ID in the Programmability Restrictions section of the Current Server Document.
   Current Server Document > Security > Programmability Restrictions
4. Make sure that the Evoko database template downloaded from https://www.evoko.se/downloads is available in your local Notes data directory.
5. Start your Notes client.
6. Create a new database.
7. Choose Evoko Room Manager template as template from Server local.
8. Select your server where to install Evoko Room Manager.
9. Enter database Title.
10. Type evoko\evoko.nsf in the filename field and click OK.
11. Sign the new database with an ID with sufficient rights to execute agents (switch user ID before if necessary).
12. From a Domino Administration workstation, launch the Domino Administrator.
13. Click the “Files” tab for the server containing the Evoko Liso database.
14. Select the evoko\evoko.nsf database by right clicking on it and choose sign.
15. Sign “All design documents” and click OK.

Setup mail file access

1. Give the Evoko Room Manager user minimum “Reader” rights to a mail file that will be used for statistics.
2. Open evoko\evoko.nsf on the server and fill in the fields:
   • Username – Roommate Evoko/Evoko (user with the rights to access resources and agents).
   • Remote Manager MailFile – where the statistics and updates is sent.
   • Rooms and Resources – reservation database.
   • Hide Subject on reservations – leave unchecked unless you want to disable Evoko Room Manager access to meeting Subjects.
   • Disable confirmation mail – leave unchecked unless you want to disable confirmation mails when booking reservations.
   • Debug – leave unchecked unless Evoko support have asked you to enable this for troubleshooting or testing.

Verify installation

To test if the web service responds, type the following URL in a web browser: 

https://yourdominoserver.tld/evoko/evoko.nsf/ResourceReservation?OpenWebService

If you get a response like shown below then the web service works:

• Domino(wsdl).
    • GETCURRENTTIME
    • GETAPPOINTMENT
    • CREATEAPPOINTMENT
    • UPDATEAPPOINMENT
    • SHOWALLAPPOINTMENTTODAY
    • SHOWALLAPPOINTMENTDATES
    • SENDMESSAGE
    • RMUPDATE
    • RETRIEVEMAILS
    • GETATTACHMENT
    • RMMARKREAD
    • RMDELETEMONITOREMAILS
    • GETROOMS
    • GETROOM
    • GETUSERS
    • GETUSER

Evoko Booking

Evoko Booking doesn't need any preparation, it is set up during the Evoko Home install, so please continue to Step 3: Evoko Home installation