Microsoft Office Local Library Object
In APA 7.3, new business entity types and functions added to the Real-Time Designer provide functionality for connecting directly to a Microsoft Office 365 server and handling Microsoft Outlook 365 email resources without having Outlook installed locally on the Real-Time Client computer. From this release, a new library provides the same functions and business entities for handle Outlook email resources through a local installation of Outlook on the Real-Time Client computer.
In APA 7.6, the Move Email to Folder function was added. This moves an email message from one folder to another.
In APA 7.7, the Add Recipient(s) to Outlook Email and Get Active Email functions was added.
For details on incorporating this functionality into your solutions, see Using Microsoft Outlook 365.
This library includes the following business entities:
-
Outlook Email, found in Business Entities > Library Types > Microsoft Outlook, which contains the properties you need to work with Outlook 365 email messages. For details, see Outlook Email Business Entity.
-
Outlook Attachment Info, found in Business Entities > Library Types > Microsoft Outlook, which contains the properties you need to work with Outlook 365 email message attachments. For details, see Outlook Attachment Info Business Entity.
The library functions are exposed under Project > References > Library References > Direct.MsOffice.Local.Library. For details, see Microsoft Office Local Library Functions.
Outlook Attachment Info Business Entity
The Outlook Attachment Info business entity found in Business Entities > Library Types > Microsoft Outlook holds email message attachment details.
The Outlook Attachment Info business entity includes the following properties:
|
Property |
Input Type |
Description |
|---|---|---|
| ContentType | Text | The MIME type of the attachment content. |
| Id | Text | A unique identifier of the attachment, assigned by the server. This is used in the function Download Attachment to identify the attachment to be downloaded. |
| Is Inline | Boolean |
Indicates if the attachment is an inline attachment or a non-inline attachment. Currently only non-inline attachments are supported, so the value of this property is always False. |
| Name | Text |
A friendly string identifier of the attachment. |
| Size | Number | The size of the attachment, in bytes. |
Outlook Email Business Entity
The Outlook Email business entity found in Business Entities > Library Types > Microsoft Outlook holds email message details.
Typically, Outlook Email objects are returned by the functions Get Emails or Get Matching Emails, and can then be manipulated, for example by forwarding or deleting them. The exception is Send Email, for which you need to build an Outlook Email object before you can send it.
The Outlook Email business entity includes the following properties:
|
Property |
Input Type |
Description |
|---|---|---|
| Attachments Info | List of Outlook Attachment Info |
A list of the Outlook Attachment Info business entities that hold the details of the attachments of this email message. |
| Body | Text |
The content of the email message. |
| Cc | List of Text | A list of valid email addresses of the CC recipients of the email message. |
| Has Attachments | Boolean | Indicates if the email message has at least one attachment (True), or no attachments (False) (read-only). |
| Id | Text | The ID of the email message, assigned by the Office 365 server (read-only). |
| Is HTML | Boolean | Indicates if the email message content is HTML formatted (True), or not HTML formatted (False) (read-only). |
| Is Read | Boolean | Indicates if the email message has been read (True) or not (False) (read-only). |
| Preview | Text | A text preview of the email message content (read-only). |
| Received DataTime | DateTime | The date and time the email message was received (read-only). |
| Sender | Text | A valid email address of the email message sender (read-only). |
| Sent DateTime | DateTime | The date and time the email message was sent (read-only). |
| Subject | Text | The email message subject. |
| To | List of Text | A list of valid email addresses of the direct recipients of the email message. |
The Outlook Email business entity includes the following function:
Add Attachment
Adds a specified file to an email message as an attachment.
| Parameter | Input | Description |
|---|---|---|
|
Full Path |
Text |
The full path of the file (text) to be attached to the email when it is sent. |
Returns
N/A
Microsoft Office Local Library Functions
The library functions for accessing and manipulating local Outlook 365 email resources are exposed under Library Objects > Direct.MsOffice.Local.Library.
Add Recipient(s) to Outlook Email
Adds recipients to Outlook email.
| Parameter | Input | Description |
|---|---|---|
|
Outlook Email |
Outlook Email |
An Outlook Email object. |
| To Email Address(es) | List of Text | A list of valid email address(es) to add to the email message. |
| CC Email Address(es) | List of text | A list of text specifying email address(es) of CC recipients. |
Returns
N/A
Delete Email
Deletes an email message.
| Parameter | Input | Description |
|---|---|---|
|
Email Id |
Text |
The ID of the email message to be deleted, as specified by the Id property of an Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
Returns
N/A
Download Attachment
Downloads an attachment from an email message.
| Parameter | Input | Description |
|---|---|---|
|
Email Id |
Text |
The ID of the email message from which to download the attachment, as specified in the Id property of an Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
| Attachment ID | Text | The ID of the attachment to be downloaded, as specified by the Id property of an Outlook Attachment Info object. |
| Path | Text | The local path to which to save the attachment. |
| Overwrite | Boolean | Indicates if an existing file with the same name in the specified folder is overwritten. If the value of this parameter is True and a file with the same name exists in the specified folder, it will be overwritten. If the value of this parameter is False and a file with the same name exists in the specified folder, the file will not be overwritten and the function will fail. |
Returns
Returns a Boolean value of True if the attachment is successfully downloaded, otherwise returns False if the attachment cannot be downloaded for any reason.
Forward Email
Forwards an email message.
| Parameter | Input | Description |
|---|---|---|
| CC | List of text | A list of text specifying email address(es) of CC recipients |
| Comment | Text | Additional text to include with the forwarded email, in the same format the original email. |
|
Outlook Email |
Outlook Email |
An Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
| To Email Address(es) | List of Text | A list of valid email address(es) to which to forward the email message. |
Returns
N/A
Get Accounts
Retrieves a list of the email addresses of all accounts configured in the Outlook application.
Returns
Returns a list of type Text containing the email addresses.
Example
This workflow retrieves a list of the email addresses of all accounts configured in the Outlook application and stores them in the text list List_of_Email_Addresses.
The following email accounts are configured in Outlook:
When executed, the variable List_of_Email_Addresses is populated with the email addresses of the two configured accounts.
Get Active Email
Gets active email from the user's Outlook 365 mailbox.
| Parameter | Input | Description |
|---|---|---|
| Mark As Read | Boolean | Indicates if email message retrieved should be marked as Read (True), or if Unread email message should remain marked Unread (False). |
Returns
An Outlook Email object of the active email.
Get Email Folders
Gets the names of all the Outlook folders for the user. This function does not accept any parameters.
Returns
A list of strings of the Outlook folders for the user, in '\\{Email Address}\{Root Folder}\{Sub-Folder}\{Sub-Sub-Folder}\...' format. For example, '\\john.smith@company.com\Inbox', '\\john.smith@company.com\Deleted Items', '\\john.smith@company.com\Inbox\Manager'. If multiple email accounts are defined, the output will relate to the default account.
Get Emails
Gets email messages from the user's Outlook 365 mailbox.
| Parameter | Input | Description |
|---|---|---|
|
Max Number of Emails |
Number |
The maximum number of email messages to retrieve from the specified folder. The email messages are retrieved from newest to oldest. |
| Folder | Text |
The Outlook folder from which to retrieve the email messages, in '\\{Email Address}\{Root Folder}\{Sub-Folder}\{Sub-Sub-Folder}\...' format. |
| Only Unread | Boolean | Indicates if only unread email messages should be retrieved from the specified folder (True), or if both read and unread email messages should be retrieved (False). |
| Mark As Read | Boolean | Indicates if email messages retrieved from the specified folder should be marked as Read (True), or if Unread email messages should remain marked Unread (False). |
Returns
A list of Outlook Email objects that meet the function criteria.
Get Matching Emails
Gets email messages that match the function criteria from the user's Outlook 365 mailbox. Any criterion that is missing or invalid is ignored. Only email messages that meet all the valid criteria are retrieved.
| Parameter | Input | Description |
|---|---|---|
|
Max Number of Emails |
Number |
The maximum number of email messages to retrieve from the specified folder. The email messages are retrieved from newest to oldest. |
| Folder | Text |
The Outlook folder from which to retrieve the email messages, in '\\{Email Address}\{Root Folder}\{Sub-Folder}\{Sub-Sub-Folder}\...' format. |
| Sender's Email | Text | A valid email address of the email message sender. This criterion is not supported for release 7.4, and should not be used. |
| Subject | Text | An email message will be retrieved as long as the parameter value appears in the subject line. It does not need to be an exact match. |
| From Date | DateTime | The date range of emails to retrieve. Only email messages sent after this date will be retrieved. |
| To Date | DateTime | The date range of emails to retrieve. Only email messages sent before this date will be retrieved. |
| Mark As Read | Boolean | Indicates if email messages retrieved from the specified folder should be marked as Read (True), or if Unread email messages should remain marked Unread (False). |
Returns
A list of Outlook Email objects that meet the function criteria.
Mark Email As Read
Marks an email message as Read.
| Parameter | Input | Description |
|---|---|---|
|
Email Id |
Text |
The ID of the email message to mark as Read, as specified in the Id property of an Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
Returns
N/A
Mark Email As Unread
Marks an email message as Unread.
| Parameter | Input | Description |
|---|---|---|
|
Email Id |
Text |
The ID of the email message to mark as Read, as specified in the Id property of an Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
Returns
N/A
Move Email to Folder
Moves an email message from one folder to another.
| Parameter | Input | Description |
|---|---|---|
|
Email Id |
Text |
The ID of the email message to move, as specified in the Id property of an Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
| Folder | Text |
The Outlook folder from which to retrieve the email messages, in '\\{Email Address}\{Root Folder}\{Sub-Folder}\{Sub-Sub-Folder}\...' format. |
Returns
N/A
Reply Email
Replies to an email message.
| Parameter | Input | Description |
|---|---|---|
| CC | List of text | A list of text specifying email address(es) of CC recipients |
|
Outlook Email |
Outlook Email |
An Outlook Email object retrieved using the functions Get Emails or Get Matching Emails. |
| Reply All | Boolean | Indicates if the reply should be sent to all the email message recipients (True), or only to the email message sender (False). |
| Reply Text | Text | The reply text, in the same format as the original email. |
Returns
N/A
Send Email
Sends an email message with the specified subject and body to the specified recipients.
| Parameter | Input | Description |
|---|---|---|
|
To Email Address(es) |
List of Text |
A list of valid email addresses of the direct recipients to whom to send the email message. |
| Cc Email Address(es) | List of Text | A list of valid email addresses of the CC recipients to whom to send the email message. |
| Subject | Text | The subject of the email message. |
| Body | Text | The textual body of the email message. |
Returns
N/A
Send HTML Email
Sends an email message in HTML format with the specified subject and body to the specified recipients.
| Parameter | Input | Description |
|---|---|---|
|
To Email Address(es) |
List of Text |
A list of valid email addresses of the direct recipients to whom to send the email message. |
| Cc Email Address(es) | List of Text | A list of valid email addresses of the CC recipients to whom to send the email message. |
| Subject | Text | The subject of the email message. |
| Body | Text | The textual body of the email message in HTML format. |
Returns
N/A
Send Outlook Email
Sends an email message using a specified Outlook Email object.
| Parameter | Input | Description |
|---|---|---|
|
Outlook Email |
Outlook Email |
An Outlook Email object that has at least one valid email address defined in its To property. For details, see Outlook Email Business Entity. |
Returns
N/A
Send HTML Outlook Email
Sends an email message in HTML format using a specified Outlook Email object.
| Parameter | Input | Description |
|---|---|---|
|
Outlook Email |
Outlook Email |
An Outlook Email object that has at least one valid email address defined in its To property. For details, see Outlook Email Business Entity. |
| Body | Text | The textual body of the email message in HTML format. |
Returns
N/A
Set Account
Specifies which of the accounts configured in the Outlook application to use when sending, forwarding, or replying to emails. This same account will be used for all sending, forwarding, and replying operations until a different account is specified or until the solution is stopped.
| Parameter | Input | Description |
|---|---|---|
|
Account Email |
Text |
The email address of the account to use when sending, forwarding, or replying to emails. |
Returns
Returns a Boolean value of True if the account was set successfully or False if it was not (for example, if the specified email address does not correspond to an account configured in Outlook).
Example
This workflow specifies that the account with email address ML@nice.com be used to send, forward, and reply to emails. The variable Bool_Var is set to True if that operation succeeds.
The workflow then sends an email.
When executed, an email from the specified address (ML@nice.com) is composed and sent.
Bool_Var is set to True, indicating that the account was set successfully.
Set Account to Default
Specifies that the default Outlook account must be used when sending, forwarding, or replying to emails. This same account will be used for all sending, forwarding, and replying operations until a different account is specified.
Returns
None
Example
This workflow specifies that the default account must be used to send, forward, and reply to emails.
The workflow then sends an email.
In Outlook, the default account is ML@nice.com.
When the workflow is executed, an email from the default account is composed and sent.
