You can connect VertiGIS FM with a Microsoft Exchange Server so that specified users can receive email and appointment messages generated by changes made to objects in the application, or occurring at regular intervals, in their Outlook inbox.
VertiGIS FM is compatible with Exchange 2007 and all later versions.
Microsoft Configuration
To connect your Microsoft Exchange Server to VertiGIS FM, you must register and configure a VertiGIS FM Groupware application in the Microsoft Entra admin center.
Register an Application
Begin by navigating to https://entra.microsoft.com/#home and signing in to your account. On the admin center landing page, click Go to Microsoft Entra ID.
Link to Microsoft Entra ID
In the left pane, under Identity, click Applications > App registrations.
App Registrations Link
Click New Registration.
Link to Register New App
You can then enter the name for the application (e.g., VertiGIS FM - Groupware) and select Register an application to integrate with Microsoft Entra ID (App you're developing).
Generic App Name and Integration Selection
In the Name text box, enter a user-facing display name for the application. Under Supported account types, select Accounts in this organization directory only.
Configure the Application
Complete the sections below on the administrative page for your new app.
Properties
On the Properties tab, set the Assignment required? and Visible to users? toggles to No.
Groupware Application Properties
Single Sign On
On the Single sign-on tab, click Go to application.
Groupware Application Single Sign-on
You can then access the Certificates and secrets and API Permissions sections from the new Manage menu that loads.
Certificates and Secrets
In the Certificates & secrets tab, open the Client secrets tab and click New client secret. Enter the string the application uses to prove its identity when requesting a token.
Groupware Application Certificates & Secrets
API Permissions
In the API Permissions section, add permissions for the items below under Microsoft Graph:
API Permissions for Exchange App
Permission |
Admin Consent Required |
|---|---|
Calendars.Read |
Yes |
Calendars.ReadWrite |
Yes |
Mail.Read |
Yes |
Mail.ReadWrite |
Yes |
Mail.Send |
Yes |
User.Read |
No |
Application Access Policy
Create an account with an email license in the Microsoft Entra admin center.
Using PowerShell, create an Application Access Policy to limit access to the Enterprise application you created to this account.
To Create an Application Access Policy
1.Run PowerShell as an administrator.
2.Run cd C:\Users\[your Windows user ID].
3.If you do not already have the Exchange Online Management Module installed, run Install-Module -Name ExchangeOnlineManagement.
4.Run Connect-ExchangeOnline.
5.Run New-ApplicationAccessPolicy -AppId <ID> -PolicyScopeGroupId <Mailbox (UPN)> -AccessRight RestrictAccess -Description "<Description>".
You can then test the policy by running Test-ApplicationAccessPolicy -AppId <AppId> -Identity <Mailbox (UPN)>.
If the mailbox identity matches the one you specified in step #5, the output should resemble the one shown below:
Access Granted for Command with Correct Identity
If the mailbox identity does not match the one you specified in step #5, the output should resemble the one shown below:
Access Denied for Command with Incorrect Identity
VertiGIS FM Configuration
When you've created a Groupware application, you can complete the configuration steps outlined in the sections below in VertiGIS FM.
Server
Connect your Exchange Server to VertiGIS FM in the Server section on the Groupware administration page (Administration > Interfaces > Groupware). Under Server, select Microsoft Exchange and click the Edit (
) button. The server entered here acts as the sending of emails and appointments generated by actions in VertiGIS FM.
Groupware Administration Page
If no Exchange Server has been configured, you can add one by clicking the Add (
) icon.
Exchange Configuration From
The server configuration form includes the fields below.
Exchange Server Fields in VertiGIS FM
Field |
Description |
|---|---|
Type |
The type of server. To configure Exchange, select Microsoft Exchange here. |
Release |
The version of the server (e.g., Exchange2013_SP1). |
Username |
The email address of the sender of emails sent through the server. |
Password |
The Windows user's password. |
Confirm Password |
The Windows user's password re-entered. |
Domain |
Your company's accepted domain in the server. |
E-mail address |
The email address of the person who will be identified as the sender. This field can be left empty. |
Test e-mail to |
|
EWS Url |
Exchange Web Services URL, or address of your Exchange server. The URL should populate automatically if the autodiscover service is activated. If the auto-discover service isn't activated, you can enter the EWS URL manually. |
Service desk integration |
A check box that, if selected, means that all emails sent a specified email address will be open a service desk ticket. Refer to Service Desk Integration for more information. |
Permitted email domains |
The domains to which email or appointment messages are restricted. For example, if the event notified users when a work order is assigned to them, and you assigned the work order to an external contractor whose email address is not in a domain specified in this section, they would not receive an email. You can click the Add ( |
Service Desk Integration
The Service Desk Integration form becomes visible on the server configuration form when you select the Service Desk Integration check box.
Service Desk Integration Check Box and Corresponding Form
Service Desk Integration Form
Field |
Description |
|---|---|
Text confirmation e-mail |
Message indicating a corresponding service desk ticket has been created in the email. |
Text error e-mail |
Message indicating a corresponding service desk ticket was unable to be created in the email. |
Retrieve E-mail starting on |
The date and time the service desk integration with the email account will begin. |
Ticket Template |
Refer to Service Desk Ticket Fields for ticket information on the fields contained in this section. |
Autodiscover Exchange
Ensure the following URL is available to connect your Exchange server with VertiGIS FM:
https://autodiscover.domain.de/autodiscover/autodiscover.xml
Replace domain.de with what appears after the @ symbol in the email addresses for your company's directory.
After you log in with the domain\user and password, the browser will display a string of code that resembles the one below:
<?xml version="1.0 encoding="UTF-8"?>
< Autodiscover xmlns =" http://schemas.microsoft.com/exchange/autodiscover/responseschema/2006 "> < Response > < Error Id =" 2248572075 Time = " 16:02:12.7667649 " > < ErrorCode > 600 </ ErrorCode>
< Message > Invalid request </ Message > < DebugData /></ Error ></ Response ></ Autodiscover >
Contact support if discover.domain.de is not found.
Events
Events describe the conditions under which the server will generate email or appointment notifications. In the Events section on the Groupware administration page, you specify the changes users can make in VertiGIS FM that will trigger emails or appointments.
Exchange Server
When you create an event, you specify the criteria based on which you want users to receive emails or appointments from the server. Some questions you'll need to specify in the event include
•should users receive an email or an appointment message in their inbox?
•should users receive messages based on changes to an object or asset managed in VertiGIS FM, or should they receive an email with a query at a regular interval?
•which users do you want to receive the email or appointment?
•which data from VertiGIS FM do you want to appear in the message subject or body?
The procedure below covers how to address these questions when you create the event.
To Create an Event
1.Navigate to the Groupware administration page (Administration > Interfaces > Groupware).
2.In the Events section, click the Add () icon.
3.In the form that displays, fill out the Name, Active, and Server fields. Refer to Event Details for more information.
4.After you select a server, you can fill the Type, Product, and Object or Interval fields. If you select the Interval check box, you will specify the interval at which you want to send emails with a query and will therefore not select an object. Refer to Event Details for more information.
The Type, Product, Interval, and Object fields cannot be edited after you save the event.
5.Click Save and Close.
Clicking Save and Close creates the event and returns you to the Groupware administration page. Additional fields associated with the event are now available when you edit the event.
6.In the Events section on the Groupware administration page, select the event you just created and click the Edit () icon.
7.Use the Add, Edit, Delete, and Change in Value fields to specify the action(s) that you want to generate the notification for this event. For example, if you want the system to generate a notification when a value is edited or updated in one of the details for the object you selected in the Objects field, select the Change in Value check box. Then click the Add () icon under Change in Value and select the value whose change you want to trigger the event. If you wanted to send an email or appointment whenever an instance of the specified object (e.g., a device order) is added to the system, select the Add () check box and then specify the object.
8.Enter the Subject and Text you want to be included in the message generated by the event. If you selected Email in the Type field, and E-mail heading and HTML Email check box are also shown.
9.Under Recipient, click the Add () icon and type the email address of the person you want to receive the email or appointment.
10.In the Parameter section, you can create variables that display a value from the object or asset whose change will generate the email or appointment in the message Subject or Text. Refer to Event Details for more information. After you create the parameter, you can type the Parameter name where you want the variable to appear in the Subject or Text text boxes.
11.Click Save and Close.
Field |
Description |
Example |
|---|---|---|
Name |
A descriptive name for the event |
Update order Sensor deviation Sensor failure |
Active |
A check box that, if selected, means the event will be active when you save the event form. |
Yes No |
Server |
The server that will send the emails or appointments generated by the event. You can select any servers that have been added to the Server section of the Groupware administration page. |
Microsoft Exchange SMTP Esendex SMS |
Type |
Whether the event should generate email or appointment notifications. If you select Email, the form displays an optional Interval field. |
Appointment SMS |
Product |
The VertiGIS FM product in which the object whose changes will generate the email or appointment is managed. The product selected here determines which objects you can select from the Objects menu. |
VertiGIS FM Maintenance VertiGIS FM Buildings VertiGIS FM Contracts |
Interval |
The interval at which you want an email to be set in terms of days, weeks, months, or years. Use the Interval field when you want recipients to receive an email with a query on a regular basis instead of when changes to an object or asset occur. You can only specify an interval if you select Email from the Type menu. When you select the Interval check box, the Object menu disappears from the form, and you are required to select a query to be sent with the email. Refer to Report and Query Administration for more information. |
Every 2 days Every 3 months Every 1 year |
Query |
The query you want to be sent with an email on a recurring basis. Query emails are an alternative to emails generated based on changes made to an object's data. This field is only visible when you select Email from the Type menu and select the Interval check box. You must select a query associated with the product selected in the Product field. |
Open tickets Device list Device orders |
Object |
The object or asset that will generate the email or appointment when edited or updated. |
Device order (VertiGIS FM Maintenance) Room (VertiGIS FM Buildings) Contract (VertiGIS FM Contracts) |
Report |
A report associated with the object or asset selected in the Object menu that is attached to the email or appointment. |
|
Add, Edit, Delete |
Check boxes that, when selected, will cause an email or appointment to be generated when the object or asset specified in the Object field is added, edited, or deleted, respectively. |
Yes No |
Change in Value (check box) |
A check box that, when selected, means you want an email or appointment to be generated when the |
Yes No |
Change in Value (list) |
When the Change in Value check box is selected, this field contains the field associated with the object or asset specified in the Object field that, when changed, will generate the email or appointment. |
State (Status) Person responsible (RespPersonTable) |
Subject |
For email notifications, the subject line of the email or appointment that will be sent to the recipients. |
The status of the following order was changed |
Text |
The text for the message delivered in the notification, for emails, appointments, or SMS messages. You can include variables defined in the Parameters field if you want the message to include data from the VertiGIS FM database. |
ID: Order ID An order that has been assigned to you in VertiGIS FM has had its status changed by another user. |
Recipient |
The people you want to receive the notification. For emails and appointments, in the drop-down menu to the right of the text box, you can indicate whether you want the recipient to receive the item as a main recipient, or whether you want them to receive a carbon copy (cc). If you're configuring an SMS service, you can enter the recipients' phone numbers. |
12505555555 |
Parameters |
Variables that can be typed in the notification's Subject or Text fields to populate them with data from a field associated with the object selected in the Object field. •Parameter name: a name for the parameter. This is what you'll type in the Subject or Text where you want the data to appear. •Parameter value: the data field whose value you want to appear in the message. You can select any field associated with the object or asset selected in the Object field. •Parameter content: Whether you want the original value or updated value to appear in the email or appointment message. |
•Parameter name: OrderID •Parameter value: Number (OrderID) •Parameter content: After change |
Documents |
Documents you want to attach to the email or appointment message. |
|
Filter |
Filter expressions that can restrict the event's triggering to specified values in data fields. You can click the Add ( |
|
User your own filter expression ("Eigenen Filterausdruck verwenden")
|
An alternative to filter expressions. A developer can provide a script that filters notifications for the event that you can enter in the text box that opens when you select the check box. |
Yes No |
Update expression active |
A check box that, when selected, opens a text box in which you can enter a script that updates objects in VertiGIS FM when the event is triggered. |
Yes No |
Protocol
You can generate logs of when emails or appointments were sent for each event created for the server.
To Generate Logs for an Event
1.In the Events section on the Groupware administration page (Administration > Interfaces > Groupware), select the event for which you want to generate a log of when messages were sent.
2.Click the Protocol (
) icon.
3.In the Protocol section on the page that opens, click the Update (
) icon.
The updated log is shown in the Protocol section.
