Exchange Web Services Module
  • 23 Jun 2022
  • 8 Minutes to read
  • Dark
    Light

Exchange Web Services Module

  • Dark
    Light

Article Summary

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.

Module Details

Core or Github ModuleCore Module
Restart Required? No
Steps Exposed?Yes
Step Location Integration > Exchange Web Services
Settings Location N/A settings are configured for each step
Prerequisites

The Exchange Web Services Module integrates the platform with Microsoft Exchange Servers (ex: Office 365 Exchange) in the form of pre-built steps that search and send emails, manage calendar events and contacts, and set availability with out-of-office replies.












Setting up Exchange Connection Properties

All Exchange Module steps use an ExchangeServerDefinition input with the following properties. This is used to identify the exchange server used for the connection.

Property NameDescription
Exchange Server URLURL of the Exchange server (optional), typically https://<mail-server>/ews/exchange.asmx.  If blank, the Windows AutoDiscovery service requires the User Email Address.
User Email AddressSMTP account (e.g. user@domain.com) for performing Exchange Server activity
Password & OAuth TokenBasic authentication and OAuth tokens are supported  To use OAuth, please refer to the appropriate Microsoft Exchange documentation to set up OAuth authentication and to generate an OAuth Token.
Exchange Server VersionSelect the version of Microsoft Exchange 

Exchange Web Services Steps

Exchange Web Services steps can be located in the Toolbox under Integration > Exchange Web Services. 

Visit File Storage Structure to reference the location of file data from pre-built steps.


Search Emails

The Search Emails step takes in a string input and searches emails on the Exchange Server for that string.

Input ParameterDescription
Exchange Server Server & authentication to use
OffsetHow 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 SizeThe 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

Fetch Exchange Emails

The Fetch Exchange Email step fetches all emails with the full email information including the body and any attachments that match the string from the Search Emails step. 

To prevent requesting large duplicate attachments, avoid using this step repeatedly with the same Email ID.

Input ParameterDescription
Exchange Server Server & authentication to use
IdsAn 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.

Send Exchange Email

The Send Exchange Email step sends an email to a recipient with a subject, body, and attachments. The From address will be populated using the User Email Address field found under the Exchange Server input.

Input ParameterDescription
Exchange Server DefinitionServer & authentication to use
ToAn array of the email address to send the email to
CCAn array of the email address to put in the CC field of an email
SubjectThe text subject of the email
BodyThe main contents of the email message. It can be plain text or HTML.
Reply ToAn alternate email address for recipients to use when replying to this email
AttachmentsAn array of FileData objects to attach to the email

Send Exchange Reply

Send Exchange Reply sends a reply to an email.

Input ParameterDescription
Email IdId 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

The Forward Exchange Email step forwards an email to designated recipients.

Input ParameterDescription
Exchange Server DefinitionServer & authentication to use
Email IdId of the email being forwarded
Forward TextText to insert into the Body of the forwarded email
ToAn array of email address to forward the email to

Get User Availability

The Get User Availability 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. 

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.
Input ParameterDescription
Exchange Server DefinitionServer & authentication to use
Email AddressSMTP Address of the user being queried
From DateStart Date
To DateEnd Date

Get Out Of Office State

Returns information about any automatic replies a given user has set up.

Input ParameterDescription
Exchange Server DefinitionServer & authentication to use
Email AddressSMPT Address of the user

Set Out Of Office State

Sets the Out Of Office properties for a given user on Exchange.

Input ParameterDescription
Exchange Server DefinitionServer & authentication to use
Email AddressSMTP Address of the user being queried
StateDisabled (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 DateStart of scheduled automatic reply
End DateEnd of scheduled automatic reply
Internal ReplyText to send to other users on the domain
External ReplyText to send to users outside of the domain
External AudienceNone, Known, All

Search Exchange Calendar

The Search Exchange Calendar step searches for calendar events with the specified start and end dates/times and retrieves all data about the calendar event or appointment.

Input ParameterDescription
Exchange Server Server & authentication to use
End TimeEnd date and time of calendar
LimitMaximum number of results to return
Start TimeStart date and time of calendar

Create Exchange Calendar Item

The Create Exchange Calendar Item step allows users to create and send calendar invites.

Input ParameterDescription
Exchange Server DefinitionServer & authentication to use
SubjectSubject of the Calendar item
BodyBody of Calendar item
Start TimeStart date/time of calendar
End TimeEnd date/time of calendar
LocationRoom/location name
Required AttendeesA list of email addresses to notify
Optional AttendeesA 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. 

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.
Input ParameterDescription
Exchange Server DefinitionServer & authentication to use
Calendar ItemThe Exchange Calendar Item object to update

Delete Exchange Calendar Item

The Delete Exchange Calendar Item allows users to delete calendar event items.

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.
Input ParameterDescription
Exchange ServerServer & authentication to use
Calendar ItemExchange Calendar Item Id object to update

Search Exchange Contacts

The Search Exchange Contacts step retrieves all contact data that matches the search string specified. 

Input ParameterDescription
Exchange Server Server & authentication to use
Search StringText to search for in the Contacts list.
Page SizeThe maximum number of results to return
OffsetHow 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.

Create Exchange Contact

The Create Exchange Contact step allows users to create contacts on the Microsoft Exchange Server.

Input ParameterDescription
Exchange Server DefinitionServer & authentication to use
Display NameDisplay Name in Exchange
Given NameFirst name
SurnameLast name
Email AddressSMTP email address

Update Exchange Contact

The Update Exchange Contact step allows users to update contact information on the Microsoft Server. 

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.
Input ParameterDescription
Exchange Server Server & authentication to use
ContactThe Exchange Contact object to update

Delete Exchange Contact

The Delete Exchange Contact step allows users to delete a specific contact on the Microsoft Exchange Server. 

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.
Input ParameterDescription
Exchange Server Server & authentication to use
Contact IdThe Exchange Contact Id object to update


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:

Create Exchange Event Handler

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.

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).

ParameterDescription
Flow to RunIdentifies a flow with Exchange Notification Handler Flow behavior to run upon receiving a notification from the Exchange server.
Exchange FoldersLists the folders that this handler should subscribe to. One or more folders can be selected.
Exchange EventsLists the events to be notified of in the selected folders.

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. Four inputs are generated 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.  The Flow must be designed to implement a method that responds to these notifications and request further information about the event. Below is an overview of each input:


ParameterDescription
Event TypeThe Exchange Event (NewMail, Created, etc.)
Exchange FolderThe folder where the event happened (Inbox, Contacts, etc.)
Old Exchange FolderThe source folder when the event is Copied, etc.
TimestampThe time on the Exchange server when the event happened.

For further information on Modules, visit the Decisions Forum.

Was this article helpful?