Exchange Web Services Module
- 23 Jun 2022
- 10 Minutes to read
- Print
- DarkLight
This documentation version is deprecated, please click here for the latest version.
Exchange Web Services Module
- Updated on 23 Jun 2022
- 10 Minutes to read
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Outlook REST API v2.0 Deprecation
Effective on November 30, 2022, Microsoft will be decommissioning the production and beta API endpoints for Outlook and will be migrating to Microsoft Graph API. This will affect the ability to utilize the below module in Decisions for versions prior to 7.13 or 8.4. Users are recommended to upgrade to 7.13+ or 8.4+ in order to utilize the module without issues.
Effective on November 30, 2022, Microsoft will be decommissioning the production and beta API endpoints for Outlook and will be migrating to Microsoft Graph API. This will affect the ability to utilize the below module in Decisions for versions prior to 7.13 or 8.4. Users are recommended to upgrade to 7.13+ or 8.4+ in order to utilize the module without issues.
Overview
The Exchange Web Services Module in Decisions allows users to integrate with Microsoft Exchange Servers from version 2007-2013 SP1 and Office 365 Exchange. The module provides users with pre-built steps to help users search and send emails, manage calendar events and contacts, and manage a user's availability with out-of-office replies.
Prerequisites:
- A preexisting Microsoft Exchange Account.
- Access to a Microsoft Exchange server.
- Installation and setup of the Exchange Module in Decisions. To learn how to install Modules in Decisions, see Installing Modules.
- OAuth setup for Exchange Web Services. To learn more about OAuth see, Establishing an OAuth Provider and Creating OAuth Tokens.
Setting up Exchange Connection Properties
All of the Flow steps in the Exchange Module take an ExchangeServerDefinition object as an input parameter. This object can be created once and reused in multiple steps, simplifying the Exchange server connection setup to a one-time operation.
An Exchange Server Definition object has the following properties:
| Property Name | Description |
|---|---|
| Exchange Server URL | This property is optional. If the URL of the Exchange server is known or if the user has multiple Exchange servers and wishes to use a specific one, it is entered here. If this property is left blank, Decisions will use the Windows AutoDiscovery service to find the Exchange server that manages information for the given User Email Address. |
| User Email Address | The SMTP address (e.g. user@domain.com) of the account that Decisions should use to perform operations on the Microsoft Exchange Server. This can be the user whose Inbox or Contacts the user wants to get or update or a user that has permission to access folders across multiple email accounts. |
| Password & OAuth Token | The Exchange module supports both basic authentication using passwords and a more secure authentication method using OAuth tokens. To use OAuth, please refer to the appropriate Microsoft Exchange documentation to set up OAuth authentication and to generate an OAuth Token. |
| Exchange Server Version | Select the version of Microsoft Exchange that Decisions will be communicating with. For Office 365 Exchange, select the newest version, Exchange2013_SP1. |
Exchange Web Services Steps
The Flow steps in the Exchange Web Services Module are found in the steps browser at Integration > Exchange Web Services. Each step's parameters can be configured on the Properties panel.
File Storage Location
If saving file data from the email steps the location of data has been updated. To learn more see File Storage Structure.
If saving file data from the email steps the location of data has been updated. To learn more see File Storage Structure.
Search Emails
The Search Emails step takes in a string input and searches emails on the Exchange Server for that string.
| Input Parameter | Description |
|---|---|
| Exchange Server | Server & authentication to use |
| Offset | How many results to skip. Use 0 to retrieve results from the start of the results. This parameter is used to allow pages of results to be retrieved |
| Page Size | The maximum number of results to return |
| Search String | Text to search for in the Inbox. This parameter supports a subset of Microsoft’s Advanced Query Syntax, as documented here: QueryString | Microsoft Docs |
In response to a Search Email request, Exchange only returns a few fields in each email result: Subject, Header, etc. The Body and any Attachments are not returned. To get this data, use the Fetch Exchange Emails step.
Fetch Exchange Emails
The Fetch Exchange Email step fetches all emails with the full email information including body and any attachments that match the string from the Search Emails step.
| Input Parameter | Description |
|---|---|
| Exchange Server | Server & authentication to use |
| Ids | An array of email Ids to retrieve full information about, including Body and any Attachments. A common source for this array is the “Id [All Id]” property of the output of the Search Emails step. |
Email attachments can be quite large. Avoid using this step repeatedly on the same email Id, if possible, to prevent requesting multi-megabyte file attachments across the network more than once.
Send Exchange Email
The Send Exchange Email step allows a user to send an email to a recipient with a subject, body, and attachments.
| Input Parameter | Description |
|---|---|
| Exchange Server Definition | Server & authentication to use |
| To | An array of the email address to send the email to |
| CC | An array of the email address to put in the CC field of an email |
| Subject | The text subject of the email |
| Body | The main contents of the email message. It can be plain text or HTML. |
| Reply To | An alternate email address for recipients to use when replying to this email |
| Attachments | An array of FileData objects to attach to the email |
.gif)
The From section of the email will be the User Email Address in the Exchange Server Definition parameter.
Send Exchange Reply
The Send Exchange Reply allows a user to send reply emails to any received emails.
| Input Parameter | Description |
|---|---|
| Email Id | Id of the email being replied to |
| Exchange Server | Server & authentication to use |
| Reply Text | Text to insert into the Body of the reply |
| Reply To All | A reply will be sent to all of the original email’s recipients and its From address. |
Forward Exchange Email
Forward Exchange EmailThe Forward Exchange Email allows a user to send a forwarded email to another recipient(s).
| Input Parameter | Description |
|---|---|
| Exchange Server Definition | Server & authentication to use |
| Email Id | Id of the email being forwarded |
| Forward Text | Text to insert into the Body of the forwarded email |
| To | An array of email address to forward the email to |
The To Date parameter MUST be at least 24 hours after the From Date. The Exchange Server will return an error for time periods less than 24 hours.
Get User Availability
This step returns True if the requested user has no appointments during the given time period and False if they have at least one calendar event during that period.
| Input Parameter | Description |
|---|---|
| Exchange Server Definition | Server & authentication to use |
| Email Address | SMTP Address of the user being queried |
| From Date | Start Date |
| To Date | End Date |
The To Date parameter MUST be at least 24 hours after From Date. The Exchange Server will return an error for time periods less than 24 hours.
Get Out Of Office State
Returns information about any automatic replies a given user has set up.
| Input Parameter | Description |
|---|---|
| Exchange Server Definition | Server & authentication to use |
| Email Address | SMPT Address of the user |
Set Out Of Office State
Sets the Out Of Office properties for a given user.
| Input Parameter | Description |
|---|---|
| Exchange Server Definition | Server & authentication to use |
| Email Address | SMTP Address of the user being queried |
| State | Disabled (no automatic reply defined), Enabled (an automatic reply is defined and continuously active), or Scheduled (an automatic reply is set up to be active during the time window set in the Duration property) |
| Start Date | Start of scheduled automatic reply |
| End Date | End of scheduled automatic reply |
| Internal Reply | Text to send to other users on the domain |
| External Reply | Text to send to users outside of the domain |
| External Audience | None, Known, All |
The Search Exchange Calendar step searches the Exchange Server for calendar events with the specified start and end dates/time.
| Input Parameter | Description |
|---|---|
| Exchange Server | Server & authentication to use |
| End Time | End date and time of calendar |
| Limit | Maximum number of results to return |
| Start Time | Start date and time of calendar |
Unlike the Search Emails step, the Search Exchange Calendar automatically retrieves all data about a Calendar Item (Event or Appointment) as part of this step.
Create Exchange Calendar Item
The Create Exchange Calendar Item step allows users to create and send calendar invites.
| Input Parameter | Description |
|---|---|
| Exchange Server Definition | Server & authentication to use |
| Subject | Subject of the Calendar item |
| Body | Body of Calendar item |
| Start Time | Start date/time of calendar |
| End Time | End date/time of calendar |
| Location | Room/location name |
| Required Attendees | A list of email addresses to notify |
| Optional Attendees | A list of email addresses to notify (can be empty) |
Update Exchange Calendar Item
The Update Exchange Calendar Item step allows users to update a calendar event item.
| Input Parameter | Description |
|---|---|
| Exchange Server Definition | Server & authentication to use |
| Calendar Item | The Exchange Calendar Item object to update |
The Id property in the Calendar Item parameter must be a valid Calendar ItemId for the user in Exchange. This value is set in the results from the Search Exchange Calendar and Create Exchange Calendar Item steps.
Delete Exchange Calendar Item
The Delete Exchange Calendar Item allows users to delete calendar event items.
| Input Parameter | Description |
|---|---|
| Exchange Server | Server & authentication to use |
| Calendar Item | Exchange Calendar Item Id object to update |
The Calendar Item Id property must be a valid Calendar Item Id for the user in Exchange. This value is found in the results from the Search Exchange Calendar and Create Exchange Calendar Item steps.
Search Exchange Contacts
The Search Exchange Contacts step allows a user to search contacts on the Microsoft Exchange Server using a text string.
| Input Parameter | Description |
|---|---|
| Exchange Server | Server & authentication to use |
| Search String | Text to search for in the Contacts list. |
| Page Size | The maximum number of results to return |
| Offset | How many results to skip. Use 0 to retrieve results from the start of the results. This parameter is used to allow pages of results to be retrieved. |
Unlike the Search Emails step, the Search Exchange Contacts automatically retrieves all data about a Contact as part of this step.
Create Exchange Contact
The Create Exchange Contact step allows users to create contacts on the Microsoft Exchange Server.
| Input Parameter | Description |
|---|---|
| Exchange Server Definition | Server & authentication to use |
| Display Name | Display Name in Exchange |
| Given Name | First name |
| Surname | Last name |
| Email Address | SMTP email address |
Update Exchange Contact
The Update Exchange Contact step allows users to update contact information on the Microsoft Server.
| Input Parameter | Description |
|---|---|
| Exchange Server | Server & authentication to use |
| Contact | The Exchange Contact object to update |
The Id property in the Contact parameter must be a valid Contact Id for the user in Exchange. This value is set in the results from the Search Exchange Contacts and Create Exchange Contact steps.
Delete Exchange Contact
The Delete Exchange Contact step allows users to delete a specific contact on the Microsoft Exchange Server.
| Input Parameter | Description |
|---|---|
| Exchange Server | Server & authentication to use |
| Contact Id | The Exchange Contact Id object to update |
The Contact Id property must be a valid Contact Id for the user in Exchange. This value is found in the results from the Search Exchange Contacts and Create Exchange Contact steps.
Subscribing to Exchange Events
Some users who want to find out whether a new Exchange email or calendar appointment has been created write a scheduled job that calls Search Emails periodically and looks for emails added since that previous run of the job. This involves making calls to Microsoft Exchange even when no new items are there to be found, which can increase network traffic.
A better practice is to create Exchange Event Handlers to subscribe to folders like Inbox and Calendar, and Exchange Event Flows that are run when the Exchange server notifies Decisions that something has happened in that folder. The Microsoft Exchange module allows a user to create multiple handlers and Flows to handle these events. Each handler subscribes to Exchange server events when created and is automatically re-subscribed at Decisions Services Manager startup time.
The Exchange module adds a special system folder at System > Jobs and Events > Exchange Event Handlers:
The Create Exchange Event Handler defines the events to be subscribed to, the Exchange server, and credentials to use to connect.
The Name and Description properties are for identifying handlers. The User Email Address, Password, OAuth Token, Exchange Server Version, and Exchange Server URL properties have the same function as in the Exchange Server Definition used in the Exchange module’s steps.
| Parameter | Description |
|---|---|
| Flow to Run | Identifies a flow with Exchange Notification Handler Flow behavior to run upon receiving a notification from the Exchange server. |
| Exchange Folders | Lists the folders that this handler should subscribe to. One or more folders can be selected. |
| Exchange Events | Lists the events to be notified of in the selected folders. |
Upon receipt of a single incoming email message in the Inbox folder, the Exchange server will generate two events: both a Created and a NewMail event. The “Created” event also occurs upon other events in the Inbox folder (ex. if a user wants incoming email, they would subscribe to the NewMail event only).
Exchange Event Handler Flows
The Create Exchange Event Handler Flow action creates a Flow in the Exchange Event Handlers folder with the correct Flow behavior. It is given four Inputs when the Exchange server notifies Decisions that an event has occurred:
The Exchange server subscription mechanism does not include IDs of new or modified items as part of its event notifications. It is up to flow authors to implement a method to respond to these notifications and request further information about the items involved.
| Parameter | Description |
|---|---|
| Event Type | The Exchange Event (NewMail, Created, etc.) |
| Exchange Folder | The folder where the event happened (Inbox, Contacts, etc.) |
| Old Exchange Folder | The source folder when the event is Copied, etc. |
| Timestamp | The time on the Exchange server when the event happened. |
For further information on Modules, visit the Decisions Forum.
Was this article helpful?
