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 using oAuth

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

As support by Microsoft for Basic Authentication will end on October 1st, 2022 it will also not be supported by Evoko Home.  All preparation for O365 must follow the Modern Auth protocol as of October 1st, 2022.

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 access EWS using a certificate-based authentication flow.

Here are the following steps to prepare O365 for your Evoko Liso.

• Create a Service Account
• Grant Impersonation rights to the Service Account 
• Create Room Resources
• oAuth Preparation

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://admin.microsoft.com/ and login with your Office 365 Admin Account.
   
2. Navigate to Users -> Active Users
3. Press Add a User
4. You will now set up the basics for your Service Account.  You can use any naming scheme that you would like, but we recommend to use something to easily identify that this account is going to be used for the Evoko Liso.  Once you have entered the Name, Display Name and Username you can press Next.
5. it is important that the service account has a mailbox, so we must provide it an Exchange Online License.  In this guide we will be applying it an E1 License.  Press Next.  You may be prompted to add additional licenses.   Proceed once the license has been added.
6. There are no optional settings that need to be applied to this account.  Press Next.
7. This will bring you the Review and Finish page.  Verify your information is correct and press Finish Adding. 
8. You will see the successful message that the account has been created like the one shown here.
9. You should now open an incognito/private window in your browser and make sure you can log into portal.office.com with the newly created Service Account.  It's important that you can access the Outlook Inbox.   If the account is brand new the inbox does not open until the first time the account is logged into.  If you do not log into the account and open the inbox for the first time you will run into issues later when connecting Evoko Home to O365. 
10. Important! Make sure the service account must be excluded from any MFA/Conditional Access Policy which are unsupported by Evoko Home.

Grant the service account Impersonation rights

Impersonation can be granted  via the Microsoft 365 Admin center.

The below method will grant your service account with the Application Impersonation permission.

If you need to use a management scope for only Room Resources in your Organization you can follow this guide here: Create Impersonation Management Scope for Room Accounts Only

1. Navigate to https://admin.exchange.microsoft.com/ and log in with Exchange Admin Account.
2. Navigate to Roles on the left hand side and then to Admin Roles.
3. Navigate to Add Role Group
4. Here we will add some information to the Role Group.  We recommend using a name that can easily identify this role is for Evoko Home.  "Description" is up to the user, and the "Write Scope" should be kept at the default.  Press Next.
5. Scroll to ApplicationImpersonation as shown here and press Next.
6. Now we will assign admins to this group.  Add the previously made Service Account as a member.  Press Next.
7. Press Add Role Group
8. Now that the group has been created-and admin as been added you can press finish.

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 365 Admin Center, navigate to "Resources" and then click on "Rooms and Equipment."
3. Press Add a Resource
4. Resource type should be Room.  Add a Name and Email for the resource account.  Make sure the domain matches the domain of the Service Account you created in the previous step.  Press Save when done.
5. Once the Resource Mailbox is created, you should see a message like this.
6. Click on Edit Booking Options and make sure that Auto Accept Meeting Requests is selected.  You can reference this.
7. Note! to create several resource accounts simply repeat above.

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

This article will cover the process of preparing Google Workspace for Evoko Home integration and during the process you will configure the following:

1. Create a New Project
   1. Configure Project Authorization
   2. Global Calendar Sharing
2. Create and Configure Resource Calendar

Create a New Project and Enable APIs

1. The first step in the process is to create a new project for the integration between Evoko Home and Google Workspace.  To do so; navigate to Google Cloud Platform and log in using your Google Domain Admin account.
2. Navigate to the Create Project button.
3. Enter a name for your project and press Create.
4. A notification should appear in the notification area when the project is created.
5. Click on the notification to reach the API manager or go to Menu Icon -> API & Services -> Enabled API's and Services. 
6. Click on Enable API's and Services
7. The API Library will appear, search for "Google Calendar API," Select Google Calendar API
8. Click Enable.
9. Repeat the previous step adding and enabling "Gmail API"
10. Enable the last needed API "Admin SDK API" for the project.
11. Now we need to create a service account.  Click on the Menu Icon, select IAM & Admin, then select Service Accounts.
12. Click Create Service Account.  Fill in the Name, ID, and the Description and click Create and Continue
13. Assign the service account the Role "Service Account Token Creator" from the drop down menu.
14. Click on Done. The service account should be ready in the list of service accounts.  Press Manage Details to collect the needed information and to create a P12 key.
15. Create a P12 key by clicking on keys, then add key and choose P12.
16. Press Create and save this P12 key as it will be needed during the Evoko Home - Google connection later on. 
17. Navigate to Details and take note of the Client ID and the Service Account Email Address as they will also be needed in later steps with Evoko Home.
18. Now we need to grant the Service Account API Access Permissions.  To do so, navigate to https://admin.google.com and click on Security, then select Access and Data Control, and then select API Controls.
19. Select Manage Domain Wide Delegation
20. Under the API Clients ID, Add a New Client and use your Service Account Client ID from the previous steps.  Then copy and paste the following strings to oAuth Scopes and then press Authorize.

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

    
21.  Under View Details you should see all [3] Scopes Applied.

Create and Configure Resource Calendars

1. To configure the global resource sharing and create a new resource, navigate to https://admin.google.com.  Select Apps then Google Workspace and then Calendar.
2. Select External Sharing option.
3. Then set external sharing options for primary calendars to "only free/busy information (hide events details)
4. Press Save.
5. The next step is to Create one or more calendar resource.  To do so, navigate to Directory -> Buildings and Resources -> Manage Resources
6. Click Create a New Resource
7. Add the details for your resource and then Add Resource.
8. Go to https://www.google.com/calendar and in the calendar side menu next to Other Calendars
9. Press the + icon and browse for your newly created Resource. 
10. Then click the check box icon.
11. Select the newly created resource calendar from My Calendar List and select the menu icon, then Share with Specific People
12. Now make sure to add the service account which will have the settings of show free/busy
13.  We strongly recommend to create a new user specifically for Evoko Home use.  You can us Evoko Admin name, as Super Admin could cause some issues in later steps.  You will also need to grand this user "make changes to events" or "make changes and manage sharing". In the screenshot below we use "Bob Anderson" as the Evoko Admin user.
14. Permissions should look like this:
15. Note: If you require PIN or RFID authentication to book you will need to add the users that can book with the permission: "Make Changes to Events". In this guide we use syed.hasan@smsevoko.com as user that will be using Pin/RFID on the Liso panel.
16. Repeat the steps above for all resources and users within the Project.
17. 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!

Grant User API Permissions

To connect Evoko Home to your Google tenant in our steps further down the road you will need a so called "Admin Email."  This user will be authenticated from Evoko Home during our initial Evoko Home wizard and will act as the Global Admin in the Evoko Home interface.  API permissions are only needed for the user that acts as "Admin Email"

1.  Go to Directory -> Users and click on the user you want to edit.
2. Scroll down and press Admin Roles and Privileges
3. Apply the necessary API permission by selecting any of the default Google Roles: Super Admin, Groups Admin, User Management Admin and Help Desk Admin. If you want the user to be more restricted you are able to create a custom role which we will guide you through in the next step.
4. Make sure to press save.
5. Creating a custom admin role is done by going into Account -> Admin Roles
6. Then press Create New Role
7. Give the new role a name of your liking and click next.  Selecting privileges is done by scrolling down to Admin API Privileges and select Read which you will find under Users.  That is the only permission needed so go ahead and click continue.
8. Press Create Role
9. Apply the newly created admin role to your user that will act as Admin Email in Evoko Home.

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