Decisions Exchange Web Services Module

Last Updated: 12/07/2018 Introduced in Version:

Overview

The Exchange Web Services module in Decisions allows you to access Email, Contacts, and Appointments in Microsoft Exchange servers.  It can communicate with Exchange server versions from 2007 to 2013 SP1 and also integrates with Office 365 Exchange. Available in Decisions Version 5.4.0 Revision 60393 and later.

 

Installing the Exchange Web Services module

To install the Exchange Web Services module, navigate to the System > Administration > Features folder, location the Decisions.Exchange module in the list of Available Features, and select the Install action.

 

Setting up Exchange Connection Properties

All of the flow steps in the Decisions.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:

  • Exchange Server URL.  This property is optional.  If you know the URL of your Exchange server, or have multiple Exchange servers and wish to use a specific one, enter it 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 Microsoft Exchange.  This can be the user whose Inbox or Contacts you want to get or update, or it can be a user that has permission to access folders across multiple email accounts.
  • Password & OAuth Token.  The Decisions.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.00
  • Exchange Server Version.  Select the version of Exchange that Decisions will be communicating with.  For Office 365, select the newest version, Exchange2013_SP1.

 

Exchange Web Services Steps

The flow steps in the Decisions.Exchange module are found in the Steps browser at Integration > Exchange Web Services:

Email Steps

Search Emails

Inputs:

Exchange Server Definition – server & authentication to use

Search String – text to search for in the Inbox.  This parameter supports a subset of Microsoft’s Advanced Query Syntax, as documented here: https://docs.microsoft.com/en-us/previous-versions/office/developer/exchange-server-2010/ee693615%28v%3dexchg.140%29

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.

Notes: In response to a Search Emails 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

Inputs:

Exchange Server Definition – 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.

Notes: 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

Inputs:

Exchange Server Definition – server & authentication to use

To – an array of email address to send the email to

CC – an array of 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.  Can be plain text or HTML.

ReplyTo – an alternate email address for recipients to use when replying to this email

Attachments – an array of FileData objects to attach to the email

Notes: The From portion of the email will be the User Email Address in the Exchange Server Definition parameter.

 

Send Exchange Reply

Inputs:

Exchange Server Definition – server & authentication to use

Email Id – Id of the email being replied to

Reply Text – Text to insert into the Body of the reply

Reply To All – If false, the reply email will be sent only to the From address of the original email.  If true, the reply will be sent to all of the original email’s recipients and its From address.

 

Forward Exchange Email

Inputs:

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

 

Exchange User Availability Steps

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.

 

Inputs:

Exchange Server Definition – server & authentication to use

Email Address – SMTP Address of the user being queried

From Date – Start Date

To Date – End Date

 

Important Note: The “To Date” parameter MUST be at least 24 hours after the “From Date”.  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.

 

Inputs:

Exchange Server Definition – server & authentication to use

Email Address – SMTP Address of the user being queried

 

Notes:  The result of this step includes an Internal Reply, an External Reply, and an External Audience setting (None, Known, or All).  It also includes the Out Of Office State, which can be:

Disabled – no automatic reply defined

Enabled – an automatic reply is defined and continuously active

Scheduled – an automatic reply is set up to be active during the time window set in the Duration property

 

Set Out Of Office State

Sets the Out Of Office properties for a given user.

 

Inputs:

Exchange Server Definition – server & authentication to use

Email Address – SMTP Address of the user being queried

State – Disabled, Enabled, or Scheduled

Start Date – Start of scheduled automatic reply

End Date – End of scheduled automatic reply

Internal Reply – text to send to other users on domain

External Reply – text to send to users outside of the domain

External Audience – (None, Known, All)

Calendar Item Steps

Search Exchange Calendar

Inputs:

Exchange Server Definition – server & authentication to use

Search String – text to search for in the user’s Calendar.

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.

Notes:Unlike Search Emails step, the Decisions.Exchange module automatically retrieves all data about a Calendar Item (Event or Appointment) as part of this step.

 

Create Exchange Calendar Item

Inputs:

Exchange Server Definition – server & authentication to use

Subject – Title

Body – Details

Start Time – Start date/time

End Time – End date/time

Location – optional room/location name

Required Attendees – array of email addresses to notify

Optional Attendees – array of email addresses to notify (may be empty)

 

Update Exchange Calendar Item

Inputs:

Exchange Server Definition – server & authentication to use

Calendar Item – The Exchange Calendar Item object to update

Notes: 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

Inputs:

Exchange Server Definition – server & authentication to use

Calendar Item Id – The Exchange Calendar Item Id to delete

 

Notes:

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.

 

Contact Steps

Search Exchange Contacts

Inputs:

Exchange Server Definition – 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.

Notes: Unlike Search Emails step, the Decisions.Exchange module automatically retrieves all data about a Contact as part of this step.

 

Create Exchange Contact

Inputs:

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

Inputs:

Exchange Server Definition – server & authentication to use

Contact – The Exchange Contact object to update

Notes: 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

Inputs:

Exchange Server Definition – server & authentication to use

Contact Id – The Exchange Contact Id to delete

Notes: 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

One way in Decisions to find out whether new Exchange email or calendar appointments have been created is to 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 Exchange even when no new items are there to be found, which increases network traffic unnecessarily.

 

Another method is to create Exchange Event Handlers to subscribe to folders like Inbox and Calendar, and Exchange Event Flows that are run when Exchange notifies Decisions that something has happened in that folder.  The Decisions.Exchange module allows you to create multiple handlers and flows so that you can handle these events the way you require. Each handler subscribes to Exchange server events when created, and is automatically re-subscribed at Decisions Services Manager startup time.

 

The Decisions.Exchange module adds a special system folder at System > Jobs and Events > Exchange Event Handlers:

 

There, you can create Exchange Event Handlers and Flows using the actions at the bottom of the page:

 

Create Exchange Event Handler

The Create Exchange Event Handler allows you to define the events you want it to subscribe to, and the Exchange server and credentials to use to connect.

 

The Name and Description properties allow you to identify what the handler should be called.  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 Decisions.Exchange module’s steps.

 

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.  

Note that upon receipt of a single incoming email message in the Inbox folder, 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, so if you are primarily interested in incoming email, 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 Exchange server notifies Decisions that an event has occurred:

Event Type is the Exchange Event (NewMail, Created, etc.)

Exchange Folder is the folder where the event happened (Inbox, Contacts, etc.)

Old Exchange Folder is the source folder when then event is Copied, etc.

Timestamp is the time on the Exchange server when the event happened.

 

Note: 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.

Additional Resources