MS Office Variables
(Available from version 7.0 onwards.)
MS Office variables are used to perform actions on and retrieve information about Outlook emails, email attachments, tasks, and appointments.
For instructions on how to create a complex variable, see here.
Example Project
An example workflow is presented for each method described below. All workflows are included in a sample project.
To view the sample project:
-
Download the ZIP file of the sample project here.
-
Copy the unzipped files to the folder%AppData%/Nice_Systems/AutomationStudio/Projects or to any other folder.
-
Open the project Outlook Sample in Automation Studio. Each workflow is named with the name of the function it demonstrates.
Instructions on how to test each workflow are provided within the examples below.
Outlook Application
This type provides a single event, New Mail, which is triggered whenever a new email is received in the Outlook inbox.
This event will not be fired unless the Outlook Application variable itself has been populated using the Get Outlook Application function from the MS Outlook built-in service. See the example provided for that function.
Events
Example
The New_Mail_Notifier event handler below is triggered by the New Mail event. In other words, the event handler is triggered when a new email is received. When triggered, the event handler shows the Email_Receivedcallout.
To test this example in the sample project:
-
Start the project.
-
Send an email to your Outlook inbox.
-
When the email is received:
-
The callout will be displayed.
-
The New_Mail_Notifierevent handler's trigger time will be set.
-
Outlook Mail Item
This type is used to represent a single email. Its properties store information about the email and its methods allow you to perform actions with the email or retrieve additional information about the email.
Properties
Property |
Input Type |
Description |
---|---|---|
Body |
Text |
The body text from the email message. |
CC |
Text |
A semicolon-delimited list of the CC recipients for the email. Where available, the display or alias name is returned, otherwise the email address is returned. |
Conversation index |
Text |
The position of an email item within a particular conversation. Outlook sets this property for each outgoing email, whether it is a new one, a forwarded one, or a reply. |
Conversation topic |
Text |
The normalized subject of an email item without the prefix strings (such as RE: and FW:). |
Date |
DateTime |
The date and time when the email was received. |
EntryID |
Text |
A string representing the unique Entry ID of the email message. The unique ID is created when an email item is created in its store. Therefore, the EntryID property is not set for an Outlook item until it is saved or sent. The EntryID changes when an item is moved into another store, for example, from your Inbox to a Microsoft Exchange Server public folder, or from one Personal Folders (.pst) file to another .pst file. |
Sender |
Text |
The email address of the sender. |
Subject |
Text |
The email's Subject text. |
To |
Text |
A semicolon-delimited list of the TO recipients for the email. Where available, the display or alias name is returned, otherwise the email address is returned. |
An example of a populated Outlook Mail Item variable is shown below.
Methods
Prepares an email to forward the email, and optionally sends the email.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
To |
Text |
The email addresses to enter in the To field of the email. Separate multiple addresses using a semicolon, for example, art@venere.org; lpaprocki@hotmail.com |
CC |
Text |
The email addresses to enter in the CC field of the email. Separate multiple addresses using a semicolon, for example, art@venere.org; lpaprocki@hotmail.com |
Replace the subject |
Boolean |
Set to True to specify a new subject, or False to use the original subject with an FW: prefix. |
Subject |
Text |
Specifies the subject text of the email. Is applied only if Replace the subject is set to True. |
Body |
Text |
Text to insert in the body of the email above the contents of the email being forwarded. |
Send |
Boolean |
Set to True if you want the email to be sent immediately automatically, or False if you want the email to be prepared but prefer that the agent has the opportunity to view the email before clicking the Send button themselves. |
Returns
Nothing.
Example
This workflow forwards the email as follows:
-
The email is forwarded to two recipients.
-
No recipients are on CC.
-
The subject of the email will not be modified.
-
The text Forwarded Email Below will be displayed above the contents of the forwarded email.
-
The email will be prepared but will not be sent automatically.
To test this example in the sample project:
-
Start the project.
-
Send an email to your Outlook inbox.
-
Wait until the email is received.
-
Select the tab for the Forward workflow.
-
Click Run Workflow.
The email will be prepared and displayed.
Returns the body of the email in HTML format.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
none |
|
|
Returns
Returns text.
Example
This workflow stores the body of the email in HTML format in the text variable text.
It then writes the contents of the variable text to the file at c:/temp/email.html.
To test this example in the sample project:
-
Make sure that you have a folder at c:/temp. Create the folder if needed.
-
Start the project.
-
Send an email to your Outlook inbox. Include some text in the body of the email.
-
Wait until the email is received.
-
Select the tab for the Get_Body_as_HTML workflow.
-
Click Run Workflow.
The variable text is populated.
Open the file at c:/temp/email.html in a text editor to view the contents of the email in HTML format.
Returns a list of the attachments to the email as a list of type Outlook Attachment.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
none |
|
|
Returns
Returns a list of type Outlook Attachment.
Example
This workflow retrieves a list of the attachments to the email and stores the list in the variable List_of_Outlook_Attachments which is a list of type Outlook Attachment.
To test this example in the sample project:
-
Start the project.
-
Send an email with multiple small attachments to your Outlook inbox.
-
Wait until the email is received.
-
Select the tab for the Get_List_of_Attachments workflow.
-
Click Run Workflow.
The list List_of_Attachments is populated. In this example, the email had three attachments. The names of those files are listed.
Moves the email to the specified folder.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
path |
List of Text |
The path to the Outlook folder in which to place the email. The first item in the list must be the email address of the user logged into Outlook (case-sensitive). See the example below. |
Returns
Nothing.
Example
This workflow moves the email to the _Work subfolder under the user's Inbox.
To test this example in the sample project:
-
Open the tab for the Move to Outlook Folder workflow.
-
Instead of the email address entered (mark.lee@nice.com), enter your own address.
-
Enter the name of a subfolder in your inbox in place of the subfolder name _Work.
-
Start the project.
-
Send an email to your Outlook inbox.
-
Click Run Workflow.
-
Wait until the email is received.
The email should be located in the Outlook subfolder your specified.
Prepares a reply email to the email and optionally sends it.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
Reply to all |
Boolean |
Set to True to reply to all recipients of the email, or False to reply to the sender only. |
Replace the subject |
Boolean |
Set to True to specify a new subject, or False to use the original subject with an RE: prefix. |
Subject |
Text |
Specifies the subject text of the email. Is applied only if Replace the subject is set to True. |
Body |
Text |
Text to insert in the body of the email above the contents of the email being replied to. |
Send |
Boolean |
Set to True if you want the email to be sent immediately automatically, or False if you want the email to be prepared but prefer that the agent has the opportunity to view the email before clicking the Send button themselves. |
Returns
Nothing.
Example
This workflow replies to the email as follows:
-
The reply will be sent to the sender only.
-
The subject of the email will not be modified.
-
The text Thank you, I completely agree! will be displayed above the contents of the email being replied to.
-
The email will be prepared but not sent automatically.
To test this example in the sample project:
-
Start the project.
-
Send an email to your Outlook inbox.
-
Wait until the email is received.
-
Select the tab for the Reply workflow.
-
Click Run Workflow.
The email will be prepared and displayed.
Saves an email as a .msg (message) file.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
Path |
Text |
Location to save the message file. |
File name |
Text |
The name to give to the message file. The file extension .msg must be included, or the file will be saved without an extension. |
Overwrite |
Boolean |
Set to True to overwrite an existing file of the same name and location if one exists, or False to prevent overwriting. |
Returns
Nothing.
Example
This workflow saves the email as a message file at c:/temp/new_mail.msg and overwrites the file if it already exists.
To test this example in the sample project:
-
Make sure that you have a folder at c:/temp. Create the folder if needed.
-
Start the project.
-
Send an email to your Outlook inbox.
-
Wait until the email is received.
-
Select the tab for the Save_as_Message_File workflow.
-
Click Run Workflow.
-
Navigate to c:/temp and preview the file new_mail.msg.
Returns the email alias of the sender of the email, where possible. This method is primarily useful for email items sent from other users in your organization.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
none |
|
|
Returns
Returns the alias of the sender as text.
Example
This workflow stores the alias of the sender in the text variable text.
To test this example in the sample project:
-
Start the project.
-
Send an email to your Outlook inbox from Outlook, for example:
-
Wait until the email is received.
-
Select the tab for the Get_Sender_Alias workflow.
-
Click Run Workflow.
The alias of the sender is stored in the variable text.
Note that the actual email address of the sender is stored in the Sender property of the Outlook Mail Item variable.
Outlook Attachment
This type is used to represent a single attachment to an Outlook Mail Item.
Properties
Property |
Input Type |
Description |
---|---|---|
File name |
Text |
The file name of the attachment. |
Methods
Saves the attached file with the specified name at the specified location.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
Full Path |
Text |
Location to save the file, including the file name, for example, c:/temp/attachments/newFile.txt. |
Overwrite | Text |
Set to True to overwrite an existing file of the same name and location if one exists, or False to prevent overwriting. |
Returns
Nothing.
Example
This workflow saves all attachments to an email in a folder c:/temp/attachments. Each workflow step is explained below.
-
The workflow invokes the workflow Get_List_of_Attachments which populates the list of type Outlook Attachment called List_of_Outlook_Attachments with a list of all attachments to the email. This step is explained in the example for Get List of Attachments.
-
The workflow waits until the Get_List_of_Attachments workflow ends. The transition to the next step is conditional on the Ended event of the Get_List_of_Attachments workflow.
-
The attachments are then saved.
-
A For Each statement is used to cycle through Outlook attachments in the list List_of_Outlook_Attachments.
-
The Outlook attachment from the current iteration is stored in the Outlook Attachment variable Outlook_Attachment.
-
The Save Attachment method is used to save the file of the current attachment. To specify the full path of the file to save, use the Concatenate function to combine the path (c:/temp/attachments) with the name to give the file. In this example, the file is saved with the same name with which it was received, as stored in its File Name property.
-
To test this example in the sample project:
-
Make sure that you have a folder at c:/temp/attachments. Create the folder if needed.
-
Start the project.
-
Send an email to your Outlook inbox. Include three small attachments.
-
Wait until the email is received.
-
Select the tab for the Save_Attachments workflow.
-
Click Run Workflow.
-
Navigate to the folder c:/temp/attachments.
The files should be saved in the folder.
Outlook Item
This type is used to represent an Outlook task or appointment.
Properties
Property |
Input Type |
Description |
---|---|---|
End Date/Time |
DateTime |
The end date and time of the Outlook item. |
Start Date/Time |
DateTime |
The start date and time of the Outlook item. |
Subject |
Text |
The subject of the Outlook item. |
Functions
Variables of type Outlook Item do not have their own methods. The following functions under the MS Office > MS Outlook built-in service return lists of type Outlook Item.
Follow the links above for details of these functions and examples of their use.