Email.MSGraph

The email action library that uses the Microsoft Graph API. This action library allows creation of an email at run time, with optional attachments. The emails are sent by using a Microsoft Office 365 account. The email recipient, subject, and body can be set at run time. If attachments are added to the email, they have total size limit of 3 MB. The actions in this action library must be used together and cannot be mixed with other email action libraries.

Properties and methods

Method ms_login: Login to Office 365 using the Microsoft Graph API.

Syntax

bool ms_login (string clientId , string tenantId , string username , string password)

Parameters

clientId: Application (client) ID from Azure Active Directory - App registrations.
tenantId: Directory (tenant) ID from Azure Active Directory - App registrations.
username: Username of Office 365 account.
password: Password of Office 365 account.

Smart parameters are supported for all parameters.

The parameters (clientId, tenantId, username, password) can be encrypted by storing them in the Advanced section of the Custom tab in the Application Manager.

To retrieve parameters that are stored in the Advanced section, use a smart parameter similar to @APPVAR(values/adv/password) where password is the name that is entered for the value in the Application Manager.

Returns

True, if the login succeeds. Otherwise False.

Level

All levels.

Details

This action will login to the Office 365 mail service, allowing emails to be sent from Datacap at runtime. When you are logged in, the other actions in this email library can be used to create an email to send. The action uses a username and password to login to the mail system. If a client API key is required for login, then see the action ms_login_ClientSecret.

To use the authentication service provided by Azure Active Directory to enable Microsoft Graph, you need to:

Register the application with Azure Active Directory.
For Authentication, under "Advanced settings", set "Yes" to "Allow public client flows."
For API permissions, under "Request API permissions", click "Microsoft Graph", choose "Delegated", add "User.Read" and "Mail.Send", and Grant admin consent.

Example

ms_login("00000000-0000-0000-0000-000000000000", "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "user@organization.com", "@APPVAR(values/adv/password)") 
ms_SetMessage("touser@organization.com","ccuser@organization.com","bccuser@organization.com","Document Integrity","Document Page Types and counts are accurate. Thanks for your help.") 
ms_SendMail() 
ms_logout()

If more than one login (ms_login or ms_login_ClientSecret) is used, second action is ignored unless the authentication fails or ms_logout() was used before the second action to disconnect.

Properties and methods

Method ms_login_ClientSecret: Login to Office 365 with a Client Secret by using the Microsoft Graph API.

Syntax

bool ms_login_ClientSecret (string clientId , string tenantId , string clientSecret , string impersonatedUserId)

Parameters

clientId: Application (client) ID from Azure Active Directory - App registrations.
tenantId: Directory (tenant) ID from Azure Active Directory - App registrations.
clientSecret: Client Secret from Azure Active Directory - App registrations.
impersonatedUserId: User ID of Office 365 account to impersonate

Smart parameters are supported for all parameters.

The parameters (clientId, tenantId, clientSecret, impersonatedUserId) can be encrypted by storing them in the Advanced section of the Custom tab in the Application Manager.

To retrieve parameters that are stored in the Advanced section, use a smart parameter that is similar to @APPVAR(values/adv/clientSecret) where password is the name that is entered for the value in the Application Manager.

Returns

True, if the login succeeds. Otherwise False.

Level

All levels.

Example

ms_login_ClientSecret("00000000-0000-0000-0000-000000000000", "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "@APPVAR(values/adv/clientSecret)", "user@organization.com") 
ms_SetMessage("touser@organization.com", "ccuser@organization.com", "bccuser@organization.com","Document Integrity", "Document Page Types and counts are accurate. Thanks for your help.") 
ms_SendMail() 
ms_logout()

If more than one login (ms_login or ms_login_ClientSecret) is used, second action is ignored unless the authentication fails or ex_logout() was used before the second action to disconnect.

Properties and methods

Method ms_logout: Disconnect from the Office 365 mail service.

Syntax

bool ms_logout ()

Parameters

None.

Returns

Always True.

Levels

All levels.

Details

Closes the connection to the Office 365 mail service. Call one time for each batch after ms_login and ms_login_ClientSecret() is completed.

Example

Send Mail Ruleset 
- Batch Level Open Rule 
- - Function 
- - ms_login_ClientSecret("00000000-0000-0000-0000-000000000000", "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "@APPVAR(values/adv/clientSecret)", "user@organization.com") 

- Page Level Rule 
- - ms_SetMessage("touser@organization.com", "ccuser@organization.com", "", "Email for batch: +@BATCHID","Here is the text file for page +@ID") 
- - ms_SetAttachment("@PILOT(BATCHDIR)+\+@ID+.txt") 
- - ms_SendMail() 

- Batch Level Close Rule 
- - ms_logout()

This example shows how to setup a ruleset that sends emails on multiple pages within the batch. The first ruleset performs the login, which would typically occur only one time for the batch. Next the page level ruleset is called for pages that use it. For example, if the application has "Main" and "Trailing" pages, then this rule might be attached to just the "Main" pages, or specific page types. Then the page rule is called for each of the pages that are attached to the rule, potentially generating multiple emails. At the end of the batch level close event, the email logout is called.

Properties and methods

Method ms_SendMail: Send Mail by using the Microsoft Graph API.

Syntax

bool ms_SendMail ()

Parameters

None.

Returns

False, if the rule does not include a previous ms_SetMessage() action, or if the email cannot be sent. . Otherwise True.

Level

All levels.

Details

Sends an email that is assembled by previous actions from this action library by using ms_SetMessage and ms_SetAttachment. When an email is complete, use ms_SendMail to send the new message. After ms_SendMail is called, another email can be generated by using ms_SetMessage, if necessary.

After you send the email, this action will discard the contents of the email in memory. Calls to the email actions after ms_SendMail() cause the creation of a new email message.

Examples

ms_SetMessage("touser@organization.com", "ccuser@organization.com", "bccuser@organization.com", "Document Integrity", "Document Page Types and counts are accurate. Thanks for your help.") 
ms_SendMail()

The preceding example shows the combination of actions to create an email and send it. If multiple emails are to be created, ms_SendMail must be called to complete the email before calling ms_SetMessage again.

ms_SetMessage("touser@organization.com", "ccuser@organization.com", "", "Email for batch: +@BATCHID","Here is the text file for page +@ID") 
ms_SetAttachment("@PILOT(BATCHDIR)+\+@ID+.txt") 
ms_SendMail()

This example is similar to the first example. However, it adjusts the text in the email subject and body based on runtime data. One file is attached and then the email is sent.

Properties and methods

Method ms_SetAttachment: Set Attachment by using the Microsoft Graph API.

Syntax

bool ms_SetAttachment (string path)

Parameters

path: The file’s path, name, and extension.

Smart parameters are supported.

Returns

False, if the file does not exist or cannot be attached. Otherwise, True.

Levels

All levels.

Details

Attaches the specified file to the current email created by the action ms_SetMessage.

ms_SetAttachment can be called multiple times to attach multiple files to an email before the action ms_SendMail. The Microsoft Graph mail API limits the total number of attachments that can be added to less than 3 MB.

Examples

ms_SetMessage("touser@organization.com", "ccuser@organization.com", "bccuser@organization.com", "Document Integrity", "Document Page Types and counts are accurate. Thanks for your help.") 
ms_SetAttachment("h:+\+MyDir+\+MQSW+\+export+\+@BATCHID+.txt") 
ms_SendMail()

This example attaches the Export file of the current batch to the email. It looks for a text file that is named by using the current batch ID. It is expected that some previous step has created this text file by using the current batch ID.

ms_SetAttachment("@PILOT(BATCHDIR)+\+@ID+.txt")

In this example, it is assumed that the action is called on a page object and it attaches a text file that is associated with the current page. It is assumed a previous step created a text file for the page.

Properties and methods

Method ms_SetMessage: Set Message by using the Microsoft Graph API.

Syntax

bool ms_SetMessage (string to , string cc , string bcc , string subject , string body)

Parameters

to: The To: recipients for the message.
cc: The Cc: recipients for the message.
bcc: The Bcc: recipients for the message.
subject: The subject of the message.
body: The body of the message.

Multiple email recipients can be specified by separating email addresses with a comma. Smart parameters are supported for all parameters.

Returns

False, if the mail object cannot be initialized. Otherwise, True.

Level

All levels.

Details

This action creates email message to be sent at run time. The recipients, subject, and body are created for the email by using the action's parameters.

Examples

ms_SetMessage("touser@organization.com", "ccuser@organization.com", "bccuser@organization.com", "Document Integrity", "Document Page Types and counts are accurate. Thanks for your help.") 
ms_SendMail()

The preceding example creates an email by using static text for the recipients, subject, and email body.

ms_SetMessage("touser@organization.com", "ccuser1@organization.com,ccuser2@organization.com", "", "@P\SubjectField", "This was run in batch +@BATCHID+ and the page total is: +@P\TotalField") 
ms_SetAttachment("@PILOT(BATCHDIR)+\+@ID+.tif") 
ms_SendMail()

In this example, it is assumed that the actions are running on a page level object. The email's subject is created by using the text contents of the field "SubjectField", off of the current page. The email subject is created by using a mix of static and dynamic text. The current batch ID and the text value from the field called "TotalField" is placed into the email. The TIF for the current page is attached and then the email is sent.