Exchange - Get object(s)

Declaration

<AMEXCHANGE ACTIVITY="get" PROTOCOLTYPE="text (options)" SESSION="text" EMAILADDRESS="text" AUTODISCOVERURL="YES/NO" IGNOREINVALIDCERTIFICATE="YES/NO" IMPERSONATE="YES/NO" USEHTTP="YES/NO" SERVER="text" AUTHTYPE="text (options)"  USERNAME="text" PASSWORD="text (encrypted)" DOMAINNAME="text" TENANTID="text (encrypted)" CLIENTID="text (encrypted)" CLIENTSECRET="text (encrypted)" CURRENTFOLDER="text" TIMEOUT="number" PROXYTYPE="text (options)" PROXYSERVER="text" PROXYPORT="number" PROXYUSERNAME="text" PROXYPASSWORD="text (encrypted)" EXCHANGEOBJECTTYPE="text (options)" RESULTDATASET="text" ATTACHMENTDEST="text" SAVEMODE="text (options)" QUERY="text"><PROPERTY NAME="text (options)" OPERATOR="text (options)" VALUE="text" /></AMEXCHANGE>

Related Topics   

Description

Retrieves information regarding one or more Exchange objects and then places the results in a dataset.

Practical usage

Ideal for gathering Exchange object data to input in subsequent steps for further processing.

Parameters

Connection

Property Type Required Default Markup Description
Connection --- --- --- --- Indicates where user credentials, server settings, and other preferences required to establish a connection to the Exchange server originate. The available options are:
  • Host (default) - Specifies that user credentials, server settings, and advanced preferences are configured individually for this activity. This option is normally chosen if only a single activity is required to complete an operation.
  • Session - Specifies that user credentials, server settings and advanced preferences are obtained from a pre-configured session created in an earlier step with the use of the Exchange - Create session activity. This option is normally chosen if a combination of related activities is required to complete an operation. Linking several activities to a single session eliminates redundancy. Additionally, a single task supports construction and simultaneous execution of multiple sessions, improving efficiency.
NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes.

Connection - Session

Property Type Required Default Markup Description
Session Text Yes, if Connection set to Session ExchangeSession1 SESSION="ExchangeSess21" The Exchange-based session to use with this activity. The default value of this parameter is ExchangeSession1. This parameter is only available and required if the Connection parameter is set to Session.

Connection - Host > Server

Property Type Required Default Markup Description
Protocol Text (options) Yes, after setting Connection to Host EWS (Exchange 2007 & newer, Online)
  • PROTOCOLTYPE="ews2007"
  • PROTOCOLTYPE="webdav"
  • PROTOCOLTYPE="ewsonline"
 Specifies the protocol to use to connect the Exchange server. This parameter is only available and required if the Connection parameter is set to Host. The available options are:
  • WEBDAV (Exchange 2003, 2007) - Uses the Web Distributed Authoring and Provisioning (WEBDAV) protocol. Compatible with Microsoft Exchange Server 2003 and Exchange Server 2007.
  • EWS (Exchange 2007 & newer, Online) - Uses the Exchange Web Services (EWS) protocol. Compatible with Microsoft Exchange Server 2007 and newer versions, and Exchange Online.
  • EWS Online - Uses the EWS protocol to access Microsoft Exchange Online by way of Modern Authentication.
Email address Text Yes (Empty) EMAILADDRESS="test@netauto.com" A valid email address to use to authenticate the connection to the Exchange server.
Refer to these parameters when Protocol is set to WEBDAV (Exchange 2003, 2007).
HTTPS/HTTP Yes/No No HTTPS USEHTTP="YES" Indicates whether to use HTTP (normal HTTP) or HTTPS (secure HTTP) as the Exchange server protocol type.
Exchange server Text Yes (Empty) SERVER="server.domain.com" Specifies the address of the Exchange server.
Authentication type Text (options) Yes Basic
  • AUTHTYPE="Basic"
  • AUTHTYPE="Default"
  • AUTHTYPE="Form"
 Specifies the type of authentication to use to connect to the Exchange server. This parameter is only available and required if the Protocol parameter is set to WEBDAV (Exchange 2003, 2007). The available options are:
  • Basic - Processes basic authentication credentials presented in HTTP headers.
  • Default - Uses the current Windows user's credentials to authenticate. Selecting this option disables the Domain name, Username, and Password parameters.
  • Form - Forms-based authentication lets you use an HTML form to obtain credentials from users who are attempting to access the Exchange server.
NOTE: If you are unsure of the option to use for this parameter, contact your network administrator
Domain name Text Yes (Empty)
  • DOMAINNAME="server.domain.com"
  • DOMAINNAME="xxx.xxx.xxx.xxx"
 The domain name (for example, domain.exchangeServer.com) or IP address to use to connect to the Exchange server.
Username Text Yes (Empty) USERNAME="theUser" A valid username to use to authenticate the connection to the Exchange server. This value may or may not be identical to the value set in the Email address field.
Password Text Yes (Empty) PASSWORD="text (encrypted)" A valid password, corresponding to the Username parameter, to use to authenticate Exchange connection. This parameter is encrypted in Task Builder.
Refer to these parameters when Protocol is set to EWS (Exchange 2007 & newer, Online).
Username Text Yes (Empty) USERNAME="theUser" The username to use to authenticate the connection to the Exchange server. This value may or may not be identical to the value set in the Email address field.
Password Text Yes (Empty) PASSWORD="text (encrypted)" The password that corresponds with the Username parameter to use to authenticate Exchange connection. This parameter is encrypted in Task Builder.
Domain name (optional) Text No (Empty)
  • DOMAINNAME="server.domain.com"
  • DOMAINNAME="xxx.xxx.xxx.xxx"
 The domain name (for example, domain.exchangeServer.com) or IP address to use to connect to the Exchange server. This parameter is only optional if the Protocol parameter is set to EWS (Exchange 2007 & newer, Online).
HTTPS/HTTP Yes/No No HTTPS USEHTTP="YES" Indicates whether to use HTTP (normal HTTP) or HTTPS (secure HTTP) as the Exchange server protocol type.
Exchange server Text Yes (Empty) SERVER="server.domain.com" Specifies the address of the Exchange server. Click Discover to automatically discover the server based on the email address and password entered.
Authenticate as current windows user --- No Disabled AUTHTYPE="default" If selected, authentication to the Exchange server is by way of the current Windows user's credentials, and the Username, Password and Domain name parameters are disabled. This parameter is disabled by default.
Rediscover server at runtime Yes/No No No AUTODISCOVERURL="YES" If selected, the Autodiscover service automatically performs at runtime (disabled by default). The Autodiscover service makes it easier to configure Outlook 2007 or newer, as well as some mobile phones, by using a user's email address and password to automatically configure a user's profile. Setting this parameter to YES disables the Exchange server parameter.
Refer to these parameters when Protocol is set to EWS Online.
Tenant ID Text Yes (Empty) TENANTID="text (encrypted)" The Directory (tenant) ID to use for authentication. This parameter is encrypted in Task Builder.
Client ID Text Yes (Empty) CLIENTID="text (encrypted)" The Application (client) ID to use for authentication. This parameter is encrypted in Task Builder.
Client secret Text Yes (Empty) CLIENTSECRET="text (encrypted)" The client secret Value to use for authentication. This parameter is encrypted in Task Builder.

Once the Email address, Tenant ID, Client ID, and Client secret parameters are populated, click Verify to perform a test connection to the Exchange Online server.

Connection - Host > Advanced

Property Type Required Default Markup Description
Current folder Text Yes Calendar CURRENTFOLDER="Contact" The Exchange folder of where to perform this activity.
Timeout (seconds) Number No 100 TIMEOUT="120" The total amount of time in seconds that this activity is allowed to execute before a time out error occurs.
Impersonate Yes/No No No IMPERSONATE="YES" If selected, Exchange Impersonation is enabled (disabled by default). Impersonation enables a caller to impersonate a given account so that the operations are performed under the rights of the impersonated account, instead of the rights that are associated with the caller's account. This parameter is only available if the Protocol parameter is set to EWS (Exchange 2007 & newer, Online). The default setting for this parameter is NO.
Ignore invalid server certificate Yes/No No No IGNOREINVALIDCERTIFICATE="YES" If selected, invalid server certificates are ignored. In some cases, the SSL certificate may be expired or invalid and an exception is thrown due to its validity status. You can avoid such SSL certificate errors by selecting this parameter. This parameter is only available if the Protocol parameter is set to EWS (Exchange 2007 & newer, Online). The default setting for this parameter is NO.
Proxy type Text (options) No System default
  • PROXYTYPE="none"
  • PROXYTYPE="http"
 Specifies the proxy type for Automate Desktop to use when attempting network communications through a proxy server. The available options are:
  • System default - Uses the default configurations set for Proxy in the Default Properties section of the Task Administrator (Options > Default Properties > Proxy).
  • None - No proxy is required.
  • HTTP - The proxy type is HTTP.
NOTE: If you are unsure of the value to use in this parameter, contact your network administrator.
Proxy server Text Yes, if Proxy type is set to HTTP (Empty)
  • PROXYSERVER="proxy.host.com"
  • PROXYSERVER="xxx.xxx.xxx.xxx"
 The hostname (server.domain.com) or IP address of the proxy server. This parameter is only available and required if the Proxy type parameter is set to HTTP.
Proxy port Number Yes, if Proxy type is set to HTTP 1028 PROXYPORT="3000" The proxy port number to use to connect to the proxy server. Most proxy servers operate on port 1028 ( default), however, a proxy server can operate on other ports. This parameter is only available and required if the Proxy type parameter is set to HTTP.
Proxy username (optional) Text No (Empty) PROXYUSERNAME="username" The username to use to authenticate when connecting through the proxy server. This parameter is only available if the Proxy type parameter is set to HTTP.
Proxy password (optional) Text No (Empty) PROXYPASSWORD="text (encrypted)" The password that corresponds with the username in the Proxy username parameter. This parameter is encrypted in Task Builder. This parameter is only available if the Proxy type parameter is set to HTTP.

Object

Property Type Required Default Markup Description
Object type Text (options) Yes Contact
  • EXCHANGEOBJECTTYPE="contact"
  • EXCHANGEOBJECTTYPE="email"
  • EXCHANGEOBJECTTYPE="task"
 Specifies the type of Exchange object to retrieve information about. The available options are:
  • Appointment - Retrieves appointment-related object information.
  • Contact - Retrieves contact-related object information.
  • Email - Retrieves email-related object information.
  • Task - Retrieves task-related object information.
Create and populate dataset Text Yes (Empty) RESULTDATASET="theContacts" Specifies the name of the dataset to create and populate with Exchange object-related information.
Filter type --- --- --- --- Specifies the object filtering method to use. The available options are:
  • Custom (default) - Click Add button to display the Property Editor dialog where specific Name, Operator, and Value properties are entered, forming a unique filter.
  • Query - Filters objects using a query.
NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes.
Name Text Yes, if the Property Editor dialog is displayed (Empty) NAME="Subject" The property name to use as a filter. This parameter along with the Operator and Value parameters act as a filter for specific property/value combinations.

For example, if the Exchange object type is Email and the custom filter on the Property Editor dialog is set to Name=Subject, Operator=Contains, Value=Meeting, this activity is then configured to retrieve email messages with a subject field containing the value Meeting. This parameter is only available and required if the Property Editor dialog is displayed. For more information, see Property Name/Value Specifications.
Operator Text (options) Yes, if the Property Editor dialog is displayed (Empty)
  • OPERATOR="Contains"
  • OPERATOR="Not_Contains"
  • OPERATOR="Equals"
  • OPERATOR="Less_Than"
  • OPERATOR="Greater_Than"
  • OPERATOR="Less_Than_or_Equal_to"
  • OPERATOR="Greater_Than_or_Equal_to"
 Allows insertion of built-in operators to precisely filter data. This parameter is only available and required if the Property Editor dialog is displayed. The available operators are as follows:
  • Contains - The property name entered contains any word or phrase matching the data entered as the value.
  • Not contains - The property name entered does not contain any word or phrase matching text entered as the value.
  • Equals - The property name entered  is equivalent to the value entered.
  • Less than - The property name entered is less than that of the value entered.
  • Greater than - The property name entered is greater than that of the value entered.
  • Less than or equal to -  The property name is less than or equal to that of the value.
  • Greater than or equal to - The property name is greater than or equal to that of the value.
Value Text Yes, if the Property Editor dialog is displayed (Empty) VALUE="Automate" The value corresponding to the property name specified in the Name parameter . Use this parameter along with the Name and Operator parameters to form a custom filter. This parameter is only available and required if the Property Editor dialog is displayed. For more information, see Property Name/Value Specifications.
Query Text Yes, if Filter type set to Query (Empty) QUERY="theQuery" The Exchange object query to perform. This parameter is only available if the Filter type parameter is set to Query.
Re-occurrences --- --- --- --- If selected, defines a window of time for this activity to react to a recurring appointment. This parameter is disabled by default. This parameter is only available if the Object type parameter is set to Appointment.
NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes.
Start date Number Yes, if Re-occurrences is selected Current Date/Time STARTDATE="%DateSerial(2016,02,17)+TimeSerial(11,00,00)%" The start date/time for this activity to react to the recurring appointment. Click Custom to select a predefined start date. Enable Expression to enter a date/time value in the format of a regular expression.
End date

Number

 Yes, if Re-occurrences is selected Current Date/Time ENDDATE="%DateSerial(2016,02,25)+TimeSerial(11,00,00)%" The end date/time for this activity to react to the recurring appointment. Click Custom to select a predefined end date. Enable Expression to enter a date/time value in the format of a regular expression.
Save attachment(s) in folder Text No (Empty) ATTACHMENTDEST="C:\Temp\" If selected, specifies the folder of where to save attachments. This parameter is disabled by default.
If filename already exists Text No Do not save
  • SAVEMODE="overwrite"
  • SAVEMODE="unique"
 Specifies the action to perform if an attachment file with the same name already exists in the specified folder. This parameter is only available if the Save attachments in folder parameter is selected. The available options are:
  • Do not save (default) - The new attachment file will not be saved.
  • Save with unique file name - The new attachment file will be saved with a unique name (unique character will append original name).
  • Overwrite existing file - The new attachment file will overwrite the existing one.

Description

Error Causes

On Error

Additional notes

Property Name/Value Specifications

The available property names and dataset fields that are populated vary depending on the Exchange object type specified. The following tables supply available property names for each object type.

Appointments

If the Object type parameter is set to Appointment, the following property names and/or dataset fields are populated.

Property/Dataset Type Description
AllDayEvent True/False Specifies whether the appointment or meeting is scheduled for an entire day. Returns true if the appointment or meeting is scheduled for an entire day, otherwise, returns false.
AllowNewTimeProposals True/False Indicates whether an attendee can propose a new meeting time for a meeting. Returns true if an attendee can propose a new meeting time for a meeting, otherwise, returns false.
AppointmentType Text (options) Specifies the type of an appointment. The available options are:
  • Single
  • Occurrence
  • Exception
  • Recurring Master
Attachments Text Specifies the collection of attachments for this message. This property is read-only.
Body Text Indicates the text body.
BusyStatus Text (options) The busy status of this messaging user for this appointment. The available options are:
  • Free - The messaging user has no conflicting commitments during the time span of this appointment.
  • Tentative - The messaging user has at least one tentative commitment during the time span of this appointment.
  • Busy - The messaging user has at least one confirmed commitment during the time span of this appointment.
  • OOF (Out of Office)  - The messaging user is to be considered out-of-office (OOF).
  • WorkingElsewhere - The messaging user is working in another location during the time span of this appointment.
  • No Data - Left blank.
Categorize Text The list of categories that are associated with this item.
EndTime Date/Time Contains the time an appointment ends. Either a Duration Property or an EndTime is required.
HasAttachments True/False Indicates whether the item has attachments. Returns true if the item has attachments, otherwise, returns false.
Importance Text (options) An enumeration value indicating the importance of the item. The available options are:
  • Low
  • Normal
  • High
IsMeeting True/False Indicates whether the appointment is a meeting. Returns true if the appointment is a meeting, otherwise, returns false.
Location Text The location of this appointment.
OptionalAttendees Text A list of optional attendees for the meeting.
Reminder Date/Time The date and time when the reminder is due for this item.
RequestResponses True/False Whether a response is requested. Returns true if a response is requested, otherwise, returns false.
RequiredAttendees Text A list of required attendees for the meeting.
Resources Text A list of resources for the meeting.
SendInvitationsMode Text (options) Determines how meeting invitations are handled:
  • SendToNone -Meeting invitations are not sent.
  • SendOnlyToAll - Meeting invitations are sent to all attendees, but a copy of the invitation is not saved in the Sent Items folder.
  • SendToAllAndSaveCopy - Meeting invitations are sent to all attendees and a copy of the invitation is saved in the Sent Items folder.
Sensitivity Text (options) The sensitivity of this item. The available options are:
  • Normal
  • Personal
  • Private
  • Confidential
StartTime Date/Time The start time of the appointment.
Subject Text The subject of this item.

Contacts

If the Object type parameter is set to Contact, the following property names and/or dataset fields are populated.

Property /Dataset Type Description
AddressType Text The type of address.
Anniversary Date The contact's anniversary date.
AssistantName Text The name of the contact's assistant.
Birthday Date The birthday of the contact.
Body Text The body of this item.
BusinessFax Number The recipient's business fax number.
BusinessPhone Number The recipient's business phone number.
Categorize Text The list of categories that are associated with this item.
City Text The city where the contact resides.
Company Text The company where the recipient works.
Country Text The country where the contact resides.
CountryOrRegion Text The country or region where the contact resides.
Department Text The department in which the recipient works.
Email Text The recipient's email address.
FileAs Text The name under which this contact is filed.
First Text The recipient's first name.
FullName Text The recipient's full name.
HomePhone Number The recipient's home phone number.
ImAddress Text The list of instant messaging (IM) addresses for the contact.
JobTitle Text The job title of the contact.
Last Text The last name of the contact.
ManagerName Text The name of the contact's manager.
Middle Text The contact's middle initial.
MobilePhone Number The contact's cell phone number.
NickName Text The contact's nick name
Office Text The office location for the recipient.
Profession Text The contact's profession.
Spouse Text The name of the contact's spouse.
State Text The state where the contact resides.
Street Text The contact's street.
WebPage Text The contact's personal or company's website.
ZIPOrPostalCode Number The ZIP code or the postal code where the contact is located.

Email

If the Object type parameter is set to Email, the following property names and/or dataset fields are populated.

Property/Dataset Type Description
Attachments Text Specifies the collection of attachments for this message. This property is read-only.
Bcc Text The hidden recipients of the message.
Body Text The primary content of an email message.
Cc Text The secondary recipients of the message.
DateReceived Date The date and time that the message was received.
From Text The authors of the message.
HasAttachments True/False Indicates whether the item has attachments. Returns true if the item has attachments, otherwise, returns false.
HasBeenRead True/False Indicates whether the message has been read. Returns true if the has been read, otherwise, returns false.
Importance Text (options) An enumeration value indicating the importance of the item. The available options are:
  • Low
  • Normal
  • High
ReplyTo Text Represents the recipients to whom the message is addressed.
RequestDeliveryReceipt True/False Indicates whether a delivery receipt is requested. Returns true if a delivery receipt is requested, otherwise, returns false.
RequestReadReceipt True/False Indicates whether a read receipt is requested. Returns true if a read receipt is requested, otherwise, returns false.
Sensitivity Text (options) Represents the sensitivity of the message. The available options are:
  • Normal
  • Personal
  • Private
  • Confidential
Subject Text The subject of the message.
To Text The primary recipients of the message.

Tasks

If the Object type parameter is set to Task, the following property names and/or dataset fields are populated.

Property/Dataset Type Description
ActualWork Number The actual work for the task in hours.
Attachments Text Specifies the collection of attachments for this message. This property is read-only.
BillingInformation Text The billing information set for the task.
Body Text The body of task.
Categorize Text The category set for the task.
Company Text The company name the task is referencing.
DateCompleted Text The completion date of the task.
DueDate Text The due date of the task.
HasAttachments True/False Indicates whether the task has attachments. Returns true if the task has attachments, otherwise, returns false.
Importance Text (options) An enumeration value indicating the importance of the task. The available options are:
  • Low
  • Normal
  • High
IsComplete True/False Indicates whether the task is complete. Returns true if the task is complete, otherwise, returns false.
Mileage Number The total number of miles used for the task.
Mode Text

The mode for the task. The available options are:

  • Normal

  • Request

  • RequestAccepted

  • RequestDeclined

  • Update

  • SelfDelegated

Owner Text The owner of the task.
PercentComplete Text The completion percentage of the task.
Reminder Text The reminder entered for the task.
Sensitivity Text (options) The sensitivity of the task. The available options are:
  • Normal
  • Personal
  • Private
  • Confidential
StartDate Date/Time The start date of the task.
Status Text

The status of a task. The available options are:

  • NotStarted

  • InProgress

  • Completed

  • WaitingOnOthers

  • Deferred

Subject Text The subject of the task.
To Text The primary recipients of the task.
TotalWork Number The total number of hours for the task.

Example

NOTE:
  • Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
  • To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.

Description

This sample task retrieves Exchange appointment objects and populates the a dataset named "text" with results. A loop is then performed. Within each iteration, a message box displays the Exchange address of the current object.

Copy 
<AMEXCHANGE ACTIVITY="create_session" SESSION="NetAutoExchange" PROTOCOLTYPE="webdav" EMAILADDRESS="exchange@netauto.com" SERVER="indra.netauto.com" USERNAME="netauto.exchange" PASSWORD="AM4IaUpiBW8p0jdVSjFibrJx0ilJ97MCLAjaME" DOMAINNAME="netauto" CURRENTFOLDER="Calendar" />
<AMEXCHANGE ACTIVITY="get" SESSION="NetAutoExchange" RESULTDATASET="test" />
<AMLOOP ACTIVITY="dataset" DATASET="test"><AMSHOWDIALOG>%test.Address%</AMSHOWDIALOG></AMLOOP>
<AMSHOWDIALOG>%test.Address%</AMSHOWDIALOG>
<AMLOOP ACTIVITY="end" />
<AMEXCHANGE ACTIVITY="end_session" SESSION="NetAutoExchange" />