Admin Guide

    Add a header to begin generating the table of contents

    Admin Guide Home Page

    Please select a topic on the left to see its content.
    We recommend that you first complete all Prerequisites.
    If you need any help, please let us know – use the Support form on the Resources page.

    my.agendex.com

    You can go to my.agendex.com to manage your company’s information, buy, change subscription, or invite external users to Agendex.

    Prerequisites

    Auto-discovery of Exchange EWS URL

    Agendex uses a protocol called EWS (Exchange Web Services) to connect to Exchange servers. You must have auto-discovery configured properly. This can be checked from the following Microsoft site:
    https://testconnectivity.microsoft.com/tests/Ola/input

    Optionally, you may enter the EWS URL on the Agendex configuration screen if you prefer not to have auto-discovery enabled.

    Agendex admin account

    You will need at least one Admin account, which will be allowed to configure and manage Agendex. This can be one of the existing Exchange accounts (e.g. yours), or a special account created for this purpose.

    It is a good idea to create an account called Agendex, as it may serve both for Agendex administration, Exchange Application Impersonation (see below), and as an Anonymous Account.

    The default Admin account is the one which you used while registering on the Agendex web site. You may add more than one account, and these can be from different Exchange / MS 365 systems.

    Anonymous account

    One of Agendex’ main features is to enable creation of events by external users, who have no dedicated Exchange accounts. The Agendex Anonymous account is used as a sender address for all events created by external users. This account is not shown in the list of calendars and is not visible anywhere except in Settings.

    Agendex (Service) Accounts

    These are the accounts that will serve to share calendars – public or private. We strongly advise that you create dedicated, licensed accounts and do not use personal accounts belonging to real people.

    Public accounts are visible to anyone accessing Agendex, even without authentication, while Private accounts are visible only to authenticated users – Exchange accounts, Active Directory External Users or Agendex Directory External Users.

    Agendex accounts are standard Exchange mailboxes. When an Exchange user wants to make his primary or secondary calendar visible in Agendex, they can simply share their calendar with one of the Agendex accounts. Or, they can open this account calendar (if given proxy rights) and post an event directly into it.

    Name these accounts carefully and choose a relevant email address that explains what this calendar is for.

    In the picture above, Events, Community, Operations, and Sales are Agendex Accounts with several shared secondary calendars. Under Operations, you see a shared calendar from one user – Emily North.

    Impersonation

    We strongly advise you to have Impersonation enabled for one or more Exchange accounts. Agendex works better, faster, and with less resources when impersonation is used. It allows direct configuration of each shared account, but this will require that you know the passwords of those accounts and enter them into Agendex separately.

    You can add the so-called Application Impersonation rights to an account in one of the following ways:

    1. Power Shell – please check this Power Shell example to see how to add impersonation rights to an account.
    2. Exchange Control Panel or Microsoft 365 Admin UI.
      Note: If you don’t have Application Impersonation role yet, you need to create one.

    Giving rights to each Agendex account

    If you don’t use Impersonation, in order to be able to present full details for events in some Agendex views (e.g. Subject and Organizer), each Agendex account shall be given proper rights to all other users. This is usually done with a Power Shell script.

    We provide a simple script that sets these rights for different types of mailboxes. You can download the script from this link: https://agendex.com/scripts/add-cal-access.ps1

    When run in a Power Shell with Exchange module integration, the script will prompt you for 2 values:

    • Email of the service account to which rights are to be given.
    • Type of mailbox to process: All, Users, or Resources (Rooms or Equipment)

    This operation may be repeated when there are new users, rooms, or equipment mailboxes in the organization.

    How Agendex works

    Agendex enables organizations to easily share events with the public, or with internal teams, by securely presenting calendars and events from pre-defined accounts to both public, external, or Exchange / Active Directory / Agendex Directory authenticated users. Calendars may be viewed in a web browser or in the Agendex mobile app.

    Multiple views of the calendar are provided: Month, Week, Day, Agenda, and Matrix.

    Also, Personal Availability (or MyAvailability) links are generated for each internal user (owner of an Exchange / Microsoft 365 account). These links can be sent via any medium to external users so they can check the person’s schedule and request an appointment.

    For authenticated users, Agendex gives a very convenient way to present colleagues’ and team schedules and availability, check if rooms or resources are free, and book them directly from the Agendex UI (desktop browser or mobile).

    Agendex is also a quick and simple interface to create and edit events, with simplified user interaction and multiple views of the calendar.

    Agendex works as a cloud-based service and as such needs to be able to access your Exchange or Microsoft 365 installation.

    Agendex can work with both Exchange on-premises and Microsoft 365.

    You will need to complete a few steps on the server first. These are: verification of Auto-discovery, creation of Agendex-related accounts, setting up impersonation, and (optionally) running a few Power Shell scripts.

    Licensing and Trial

    Agendex licensing is simple; there are two license levels: “Community” and “Pro”.
    Note: Community license will be available mid-January, 2021.

    The “Community” edition is free and has partial functionality – you can compare licenses here.
    The “Pro” version can be purchased in two plans: Monthly or Yearly. Yearly plan offers two months for free.

    Priority support is also available as an additional option and provides faster response times and external user auditing.

    Both types of licenses provide access via the Browser client and the Mobile App.

    Licensing is “per system”, regardless of the number of accounts configured or number of users using/accessing the system.

    Multi-System

    Agendex can connect to more than one Exchange or Microsoft 365 system. This gives organizations the ability to manage multiple calendars from a single client.

    Each system is configured separately in Agendex’ Settings.

    Agendex keeps track of events that span multiple systems, e.g. the Organizer is from System A, and the recipients are from System A, B and C.

    Important: In such cases, the recipients from the other system, e.g. B and C will see their events created from the Default Account for their system. The event will have an ‘on-behalf’ header with information about the organizer.

    Agendex keeps events synchronized across systems. If the organizer edits or deletes events, the change will be propagated to all systems. Hence. it is very important that events created across systems be edited or deleted only in Agendex. We cannot guarantee multi-system sync of events edited in Outlook.

    Deploying for Exchange On-Prem


    Basic Authentication

    As Agendex uses Exchange-based authentication over the secure HTTPS protocol, you need to enable Basic Authentication for the EWS application under each IIS serving Exchange.
    Open IIS Manager, find the EWS application, and click on Authentication under IIS settings. On the right, make sure that Basic Authentication is Enabled.

    Rooms and Equipment


    Exchange Equipment and Room mailboxes

    In Exchange there are two predefined types of Resources: Equipment, e.g. computer, screen, etc., and Room. Unfortunately, grouping and finding them from an external service like Agendex requires a bit of preparation. Dynamic Groups can be created for Resources and Room Lists for Rooms.

    You will need to tag all the Equipment and Rooms that you want to show in Agendex, in the respective tabs (Rooms and Resources), with a custom attribute and then use this attribute to group resources together.

    First, you need to decide how you want to group these resources. For example, you may group rooms in two lists, like ‘Conference Rooms’ and ‘Labs’, and Equipment in Dynamic Distribution Groups, like ‘Office Equipment’, ‘Mobile devices’, and ‘Cars’.

    Creating Dynamic Distribution Group for Equipment mailboxes

    First, let’s tag an equipment with a custom attribute. In Exchange Admin Center, find the Equipment mailbox under Recipients, and edit the Equipment. Then click “More Settings” and add a Custom Attribute.

    In this example, we assign the string Equipment to Custom Attribute 1.

    Repeat this step for any equipment mailbox and set the value to the name of the group you will create later.

    Next, you define the Dynamic Distribution Group. Go to Groups tab in Recipients and click the plus symbol to create a new Dynamic Distribution Group. Expand the window to see all options.

    Set the name, alias of the Group, and the Member options as shown above (Only Resource Mailbox types), then add a Rule matching Custom Attribute 1 to the string entered in the respective attribute in the Equipment mailboxes that shall belong to this group. Save the group.

    Creating Room Lists for Room mailboxes.

    First, you tag all your Rooms with a Custom Attribute, same as described above for Equipment. Next, you will need Exchange Power Shell to issue a command that will create a Room List, with the rooms marked with the custom attribute as members. Unfortunately, Exchange and Microsoft 365 do not provide a visual interface for doing that.

    Open an Exchange-enabled Power Shell and issue the following two commands:

    $MemberRooms=Get-Mailbox -Filter {(RecipientTypeDetails -eq "RoomMailbox" -and CustomAttribute1 -eq "Labs")}

    Replace ‘Labs” with the value of the Custom Attribute. Then issue the second command:

    New-DistributionGroup -Name "Labs" –RoomList -Members $MemberRooms

    Repeat this for any Room List and Room members you want to create.

    Deploying for Microsoft 365 – Enterprise Edition

    Registering Agendex in Azure AD

    In order to allow Agendex access to Exchange mailboxes in Microsoft 365, you need to register the application in your Azure Active Directory.

    There are two types of Azure applications – single tenant and multi-tenant apps.

    Since v1.1 Agendex is configured as a multi-tenant application and has a very simple mechanism to request you to give the consent required so your instance of Agendex can access Exchange via EWS.

    With multi-tenant apps you do not need to make any changes in your Azure AD manually, the application takes care of this, while Microsoft is asking you to grant the consent in a browser pop-up.

    The General Configuration below explains how this is done in Agendex – Enterprise Edition.

     

    Deploying Community Edition

    Creating Agendex Application in Azure AD

    This section is relevant only for users of Agendex Community Edition. If you are using Agendex Enterprise, please skip to ‘Configuring Agendex‘.

    If you plan to use Agendex against Microsoft 365 Exchange, before deploying Agendex on your infrastructure, you need to create an Agendex App in Azure Active Directory.

    Note:
    You can omit this step if you are connecting to On-Premises Microsoft Exchange.
    In this case Agendex Community Edition is configured much like Agendex Enterprise, so you can jump directly to this section about Docker installation.

    Important: Agendex uses an authentication mechanism, called OAuth v2, which requires Azure authentication servers to be able to contact Agendex’ server after successful user or Service Account authentication. Hence, you will need a valid DNS address for Agendex, accessible from outside your organization via HTTPS (port 443). The example used in this document is agendex.mycompany.com.

    Registering the Application

    Open Azure Active Directory Admin Center, select Azure Active Directory and click on the menu ‘App Registrations’. Then click the Plus button ‘New registration’.

    Next, give a name to the application, leave the first option selected (‘Accounts in this organizational directory only’) and enter the Redirect URI that matches the DNS address of the server where Agendex will be deployed, as described above.
    The URI must always end with ‘oauthresp’, as shown below.

    Click ‘Register’ and you will be automatically redirected to the Authentication page.
    Click ‘Add a platform’, then select ‘Mobile and desktop applications’:

     For Redirect URI’s select the first and the third option then click ‘Configure’:

    Then, back on the page on the left under ‘Implicit grants and hybrid flows’ select ID tokens; this is the mechanism Agendex uses to perform users authentication:

    The next step is to generate an application secret. Be careful: you will only have a single chance to copy the secret’s value.

    From the menu on the left select Certificates & secrets. Click ‘New client secret’, type in a description, select ‘Never’ as expiration and then click ‘Add’:

    At this moment, the secret will be displayed, with the value in the third column and an option to copy it to the clipboard. 

    Please save the secret, as you will need to import it into Agendex’s configuration:

    Now, let’s jump to ‘Manifest’, at the bottom of the temp menu. It may take a few seconds for the Manifest to appear. You need to insert a few lines in it, exactly under the section named ‘requiredResourcesAccess’. These lines describe the access that Agendex needs to Exchange.

     

     {
    "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
    "resourceAccess": [
    {
    "id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40",
    "type": "Role"
    }
    ]
    },

     

    We are almost done!

    The next step is to add permissions to the Agendex App.

    Go to ‘API permissions’, click ‘Add Permission’, and click on ‘Microsoft Graph’. In the next form, please select the four OpenID permissions under ‘Delegated Permissions’ and click ‘Add Permissions’ on the bottom of the screen.

     

    Now click on the ‘Grant admin consent for Agendex’ (or whatever you called the application). You shall see now green check boxes on the right side of each permission.

    And the last step is to configure the information that Agendex needs in the authentication token. Click on the ‘Token configuration’ menu, then click ‘Add optional claim’. From the right menu, select the following three claims under the ID type:

    • auth_time
    • email
    • upn

    and then click ‘Add’:

    Important: Go back to Overview and record the Application’s Overview and record the app’s Client and Tenant ID’s. You will need these along with the secret, generated at step 3, when configuring Agendex.

    Installing Docker

    Docker is one of the most commonly used containerization software solutions in the world. Agendex is deployed as a docker image, and can run on any system for which there is a Docker distribution.
    This link will help you install Docker on your preferred OS:
    How to get Docker.
    Note: for Linux you will also need docker-compose.
    Next, in your welcome email you received your initial configuration and your license file. Please have these handy for the next steps.

    Agendex's Data Directory

    Agendex stores your main configuration, user preferences, and other options in a small embedded database. If you lose this data, your Agendex instance will reset to its original, non-configured state. Although the basic system options are easy to set, users may be frustrated if they need to enter their preferences again.
    Hence, we strongly advise that you create a data folder for Agendex on the server where it will be running and even back it up from time to time. Its size will rarely go above a few dozen megabytes.

    Agendex DNS and address

    In order to access Agendex, you will need a DNS entry, pointing to the IP of the machine where Agendex is running, accessible both from inside and outside your organization (if you don’t want to give users external access, then you may be good with internal DNS entry only).

    Agendex runs by default on a port higher than 3000 and you will need to set up a mapping between the internal Docker port to the port exposed by the machine where Agendex is running in the Docker configuration file.

    Important: Please note that Agendex’ server does not provide SSL over HTTP. You need to use NAT and SSL termination in your network to give secure access to your external users.

    The Docker YAML file

    In your welcome email you received file called docker-compose.yaml. You will need to edit some fields in it in order to deploy Agendex properly.

    First, create the root directory where Agendex will be running, e.g. /opt/agendex, or D:/Agendex. Then save the YAML file to the disk, in the root Agendex directory. Open it with your preferred text editor. Make sure not to change the tabulation of the file!

    Initially the file looks something like that:

    version: '3'
    services:
    agendex-ce:
    image: agendex/agendex-community-edition:latest
    container_name: agendex-ce
    hostname: agendex-ce
    restart: always
    environment:
    AGNDX_ID: mycompany.com
    AGNDX_DOMAIN: mycompany.com
    AGNDX_CLIENT: https://agendex.mycompany.com
    AGNDX_SERVER: https://agendex.mycompany.com
    AGNDX_ADMINS: john@mycompany.com
    AGNDX_COMPANY: My Company Ltd.
    AGNDX_NAME: Agendex
    AGNDX_SECRET: QU7naZyV1DSb
    AGNDX_PORT: '3000'
    volumes:
    - /path/on/host/db:/opt/agendex/db
    ports:
    - '3000:3000'

    Edit the file, so that:
     – AGNDX_SERVER and AGNDX_CLIENT fields both hold the correct URL for Agendex (e.g. https://agendex.mycompany.com). The YAML will have an automatically generated URL: https://agendex.{yourdomain}, where {yourdomain} is the domain with which you registered on https://agendex.com;
     – the first part of the line after ‘volumes:’ matches the Agendex Data Directory, mentioned above.

    Note:
    On Windows the path shall be written using Windows standards, e.g. with backslash (‘\’) as delimiter between directories.

    Edit the port mapping at the end of the file. The left part of the mapping is what the exposed port will be, the right part – the port used by Agendex inside the container. We recommend that you avoid altering this value. In any case the port in the right part of the ‘ports:’ field should match the one after AGNDX_PORT.

    Optionally, you may edit the secret code (AGNDX_SECRET), the company name (AGNDX_COMPANY) and the product name (AGNDX_NAME). The product name must be present, but is reserved for future version of Agendex, capable of ‘white-labelling’.

    Although you may add admin users inside Agendex, you may add additional admins here, separating them with a comma, without any white spaces.

    After editing, the yaml file shall look like this:

    version: '3'
    services:
    agendex-ce:
    image: agendex/agendex-community-edition:latest
    container_name: agendex-ce
    hostname: agendex-ce
    restart: always
    environment:
    AGNDX_ID: mycompany.com
    AGNDX_DOMAIN: mycompany.com
    AGNDX_CLIENT: https://agendex.mycompany.com
    AGNDX_SERVER: https://agendex.mycompany.com
    AGNDX_ADMINS: john@mycompany.com,leah@mycompany.com
    AGNDX_COMPANY: My Company Ltd.
    AGNDX_NAME: Agendex
    AGNDX_SECRET: QU7naZyV1DSb
    AGNDX_PORT: '3000'
    volumes:
    - /opt/agendex/db:/opt/agendex/db
    ports:
    - '8080:3000'

    Note: You can also define a specific interface for the port mapping, e.g.: ‘10.0.0.1:8080:3000’

    Deploying Agendex from Docker Hub

    On Linux

    Please make sure that your system is up to date and you have the latest version of Docker installed.
    Note: In order to use the provided YAML file, you will need also docker-compose, which is not included on Linux with Docker. You can get it here:
    https://docs.docker.com/compose/install/

    Inside the directory created for Agendex, run the following command:

    sudo docker-compose up -d

    Be default the command will look for docker-compose.yaml file. If it is renamed, then you need to provide the name of the yaml file with the -f option:

    sudo docker-compose -f agendex.yaml up -d

     

     

    On Windows

    Make sure you that you have Docker for Windows installed. The installation may require, depending on your version of Windows, installing a patch from Microsoft for Windows System for Linux 2 from here (step 4 and 5) and rebooting your machine.

    After Docker for Windows starts fine (you will see Docker’s white whale icon in the system tray), open an administrative command prompt, go the directory, created for Agendex and execute the following command:

    docker-compose up -d

    Be default the command will look for docker-compose.yaml file. If it is renamed, then you need to provide the name of the yaml file with the -f option:

    docker-compose -f agendex.yaml up -d

    The above command will automatically download and run Agendex with the basic configuration you defined while editing the YAML file.
    After the container deployment is completed, you can access Agendex at the defined local address and port, or – if already configured – at the public DNS address.

    Community Edition Configuration Specifics

    License: After entering the secret code (as it appears in your YAML file), you will be prompted to enter your license. Open the license file, copy the text string inside and paste it in the license prompt.
    Microsoft 365: There is also a small difference between Community Edition and the Enterprise edition when configuring access to Microsoft 365. You need to enter Application ID, Tenant ID and Secret for the Agendex app, defined in your Azure AD in the main Exchange configuration form.

    Configuring Agendex

    General configuration

    After you have enrolled on the Agendex web site (https://agendex.com/get-started) you will receive an email with the URL to your Agendex instance and a secret code to be used for authentication for the initial setup of the product.

    Enter the code and you will see the main configuration page. 

    As you will have nothing configured yet, the first thing to do is to create at least one System.
    Click the plus button to create your first system.

    Once the system is created, you will see four configuration sections. The first one – Exchange – will change slightly, depending if you use Exchange On-Premises or Microsoft 365.

    The image above shows settings for Microsoft 365. Impersonation is mandatory. Please read the Prerequisites section if you haven’t configured it yet, as this is required.

    You will need to use an authentication mechanism called OAuth 2.0 to grant admin consent and to authorize the user for impersonation.

    First, click on Grant admin consent. A Microsoft dialog will open. Select the box ‘Consent on behalf of your organization’. Otherwise each user in your organization will be required to go through this step.

    Next, click on Authorize. A similar Microsoft dialog will popup up. You need to login with the same user that was set as Impersonation user in Microsoft 365.

    If authentication is successful, the impersonation filed will be automatically filled up with the correct account.

    The settings will change if you select an Exchange On-Premises version instead of Microsoft 365:

    We strongly advise you to use impersonation also with Exchange On-Premises. If you select not to do so, you will need to enter password for each service account (see Agendex Accounts section).

        • If you have auto-discovery enabled, leave the switch ON, otherwise enter the EWS URL, as defined for your system.  

    In the popup that opens, you may enter Name and New or Existing Group, then click the + button to add the resource or room.

    Agendex Accounts

    Clicking on the “+” sign next to the Agendex Accounts listbox opens the Add Account dialog.

    The ID field is how the account will be named in the Agendex client.

    The Email is the email address (not alias!) of the Exchange / Microsoft 365 mailbox. In order to be operational, an account must be Enabled. You can temporarily disable accounts you want to hide.

    • There must be at least one default account that is enabled. The default account is used to resolve usernames and addresses, read Room Lists, Resources, etc.

    • Public accounts are Shared Calendars, which are visible to every Agendex user, no matter if they are authenticated or not.

    • Anonymous account is a separate Agendex account, which acts as a sender on behalf of non-authenticated Public users. When booking a meeting from My Availability this account will appear as sender to the recipient.

    • Hide own calendar will make the Agendex Account’s own calendar invisible and only user-shared calendars will be visible under that account. Note that External users won’t be able to send events to this account.

    • Hide for external users – this will make the entire account and all shared folders invisible to users who have no Exchange accounts (logged in via ClaudAuth or LDAP – see Authentication below).

    In the picture above, Agendex is an anonymous account, Events is the default, public account, Community is a public account, while Operations is a private account.

    Rooms and Equipment (Resources)

    If you have Room Lists defined in Exchange, then you can leave the switch to try to get rooms from Exchange to On.

    Enter in the box the email addresses – comma separated, no space – of the dynamic distribution groups, holding equipment mailboxes.

    Authentication

    On this tab, you can configure various authentication options. However, in most cases, the default settings are recommended.

    • Use Exchange for authentication – the default option – check user’s email and password against Exchange.

    • Use AD for authentication – this option allows you to create External users in your Active Directory. External users do not have Exchange accounts, but they can still view Agendex calendars and create events in the Agendex Accounts. Enter the LDAP server, exposed by Active Directory, select if the connection is to be made over SSL

    Global Settings

    In this tab you can set various options:

    • Administrator emails: list of accounts that can manage Agendex.

    • Enable Cloud Authentication: Manage external users in Agendex hosted directory.

    • Always Authenticate: do not allow Guest (anonymous) access to Agendex.

    • Preload body: this instructs Agendex to load and keep in memory the body of an event. By default only basic calendar information is retrieved, which keeps the traffic to the Exchange back-end at a lower volume.

    • Full refresh interval: as Agendex caches data for better performance, this setting defines how often the cache is refreshed.

    • Enable Logging and Debug level: how much info about the system is output by Agendex. Logs are saved in a cloud storage. Please do not turn this on unless you have issues with Agendex and have been instructed to do so by one of our support engineers.

    • Path to myavailability page. The default is: https://{yourcompany}.agendex.app/myavailaibilty/{usertag}). You can replace ‘myavailability’ with something else.

    • Anonymous users blocking time – minimum cool-out period before sending a new request for a meeting to the same participant.

    • Display settings: default view, time step and work hours

    My.Agendex.com Portal

    The portal allows paid Agendex customers to manage their subscription, onboard external users and edit company details.

    Onboarding External Users

    External Users may be created in your own Active Directory in containers dedicated to such users, as explained in the Authentication section of ‘Configuring Agendex’. In this case you need to provide them with their UPN (User principle name, in format user@domain.com) and their password.

    Agendex provides its own cloud-based directory, managed in the customer’s portal at https://my.agendex.com. In order to create users, you must login to the portal with the user who enrolled to Agendex from the Agendex web site. Once authenticated, click on Users.

    After sending the invitation, the user must accept the invite sent to him by email and enter their password.

    After this is completed the person will be able to login to Agendex as an external user and be able to see calendars, post events, and check availability.

    Set your company's details

    In the my.agendex.com portal you can edit the description of your company and make your public calendars searchable.

    Public calendars appear on search.agendex.com and are freely accessible to the public. Calendars may be found by description, location and tags. Location is a single word, but you may add more location specific tags. E.g. have just Montreal as location and add tags Quebec and Canada.

    Should you have any issues configuring Agendex, please contact us via the Support form on the Resources page on agendex.com.

    Adding Calendars to Agendex

    By default, all enabled Agendex Account Calendars will appear in Agendex.

    There are two ways to add shared calendars:

    1. Add more secondary calendars to Agendex Accounts.

    In this case you must login to Outlook or Outlook Web Access and simply create a secondary calendar in the Agendex account. After a few minutes the calendar will appear in Agendex.

    Users create events in this calendar from Outlook or another Exchange-compatible App.

    2. Let other users share their Primary or Secondary Calendars with Agendex Accounts.

    Exchange users share their calendar(s) with the Agendex Accounts they want.

    Agendex will send a notification to the Administrators, defined in Settings, that a new share is pending in the Agendex calendar. Then, an Administrator must login to the account and accept the share.

    Scroll to Top