3.2 - 3.8 - ProcessMaker Functions - Email Functions

Email Functions

---

PMFSendMessage()

The PMFSendMessage() function sends out customized email notifications using a template. For more information, see Trigger Messages.

int PMFSendMessage(string caseUID, string from, string to, string cc, string bcc, string subject, string template, array aFields=array(), array aAttachments=array(), boolean showMessage=true, int delIndex=0, array config=array())

Parameters:

• string caseUID: The UID (unique identification) of a case, which is a string of 32 hexadecimal characters that uniquely identifies each individual case. For the current case use the system variable @@APPLICATION. Other case UIDs can be found with the PMFCaseList() function, the WSCaseList() function, the caseList() web service, or by using the executeQuery() function to query the wf_<WORKSPACE>.APPLICATION.APP_UID field in the database.
• string from: The email address of the person who sends out the email. Use the userInfo() function to get a user's email address. If it is necessary to include the person's name along with the email address, list the name first followed by the email address enclosed inside angle brackets < >. The name may be enclosed inside double quotations, but it isn't necessary:
  'Liliana Iriarte <liliana@example.com>'
         

  or

  '"Liliana Iriarte" <liliana@example.com>'
         

  Note 1: Due to security restrictions, Yahoo!, Gmail and many other email providers will no longer deliver email that doesn't come from the same email address as the account in the Email Configuration at Admin > Settings > Email. To avoid this problem, set the email address for the from parameter to the same email address found in the Email Configuration.

  Note 2: In the email server settings, you enter the Sender Account, Sender Email and Sender Name. Then, the From and Reply to in the email header is as follows:

  1. If the from parameter in the function is empty:
     From: SenderName <SenderAccount>
     Reply to: SenderName <SenderEmail>
  2. If the from parameter in the function is <sample.account@gmail.com> or sample.account@gmail.com:
     From: <SenderAccount>
     Reply to: from
  3. If the from parameter in the function is Sample Account Name <sample.account@gmail.com>:
     From: Sample Account Name <SenderAccount>
     Reply to: from

• string to: The email address(es) to whom the email is sent. If there are multiple recipients, separate each email address with a comma ",". If it is necessary to include the person's name along with the email address, list the name first followed by the email address enclosed inside angle brackets < > as shown above. Use the userInfo() function to get a user's email address.
• string cc: The email address(es) of the people who will receive carbon copies of the email. If there are multiple recipients, separate each email address with a comma. Use the userInfo() function to get a user's email address.
• string bcc: The email address(es) of the people who will receive blind carbon copies of the email. Unlike a normal carbon copy, the other recipients won't see who has received blind carbon copies. If there are multiple recipients, separate each email address with a comma. Use the userInfo() function to get a user's email address.
• string subject: The subject (title) of the email.

• string template: The name of the template file in HTML format that produces the body of the email. Include the file extension in the file name (i.e. "negativeResponse.html".

  The template file must be located in the Templates or the Public Files of the current process. The template file can contain system variables, case variables (which weren't defined in the same trigger), or any variables that are passed in the fields parameter. See Notifications to learn how to insert variables into an email template.

• array fields: Optional parameter to define custom variables that can be inserted into the template file. The fields parameter is an associative array where the keys are the variable's name and the values are the variable's value. If no array is included, an empty array is included by default. Case variables defined in the same trigger that calls PMFSendMessage() should be passed to the email template using the fields array. See the example below for how to set the values in the fields array.
• array aAttachments: Optional. An array of complete paths of files to attach to the email. The paths can be paths in the file system of the server where ProcessMaker is installed. For example:
  array('/home/foobar/clients/client_03452342.xls','/var/www/public/profile.pdf')
         

  By default, files are attached using their original file names, which means that Input Documents, Output Documents and attached files are sent with filenames containing their unique ID and version number. It is possible to rename file attachments by setting the new filename as the array key. For example:

  $g = new G();
  array(
      "InvoiceForJohnDoe.xls" => "/home/foobar/clients/client_03452342.xls",
      "scannedInvoice.png" => PATH_DOCUMENT . $g->getPathFromUID(@@APPLICATION) . PATH_SEP . "9743702654e6925b52e1e34098864192_1.png"
  )
         

  If sending files stored by ProcessMaker, it is recommended to use ProcessMaker's predefined system constants, such as PATH_DATA_PUBLIC, PATH_DATA_MAILTEMPLATES, PATH_DOCUMENT and PATH_SEP, to construct the paths:

  • Files in the "public" directory of the Process Files Manager:
    PATH_DATA_PUBLIC . "<PROCESS-UID>" . PATH_SEP . "<FILENAME>"

    Example:

    PATH_DATA_PUBLIC . @@PROCESS . PATH_SEP . "letterheadLogo.png"
  • Template files (without inserted data) in the "mailTemplates" directory of the Process Files Manager:
    PATH_DATA_MAILTEMPLATES . "<PROCESS-UID>" . PATH_SEP . "<FILENAME>"

    Example:

    PATH_DATA_MAILTEMPLATES . @@PROCESS . PATH_SEP . "companyProfile.html"
  • Uploaded Input Document files and attached files:
    PATH_DOCUMENT . $g->getPathFromUID("<CASE-UID>") . PATH_SEP . "<CASE-DOC-UID>_<VERSION>.<EXTENSION>"

    Example:

    PATH_DOCUMENT . $g->getPathFromUID(@@APPLICATION) . PATH_SEP . "9743702654e6925b52e1e34098864192_1.png"
  • Generated Output Document files:
    PATH_DOCUMENT . $g->getPathFromUID("<CASE-UID>") . PATH_SEP . "outdocs" . PATH_SEP . "<CASE-DOC-UID>_<VERSION>.<EXTENSION>"

    Example:

    PATH_DOCUMENT . $g->getPathFromUID(@@APPLICATION) . PATH_SEP . "outdocs" . PATH_SEP ."6960198894e6927e0a40b14004833875_2.pdf"
• boolean showMessage: Optional. If set to true, which is the default, the email message will be displayed in the message history. If set to false, then the email message will not be displayed in the message history, although a record of the email will still be stored in the APP_MESSAGE table.
• int delIndex: Optional. If not set to 0, the message will be associated with a particular task in the case, which is indicated by its delegation index. The delegation index for the current case is stored in the system variable @%INDEX. Note that the delegation index changes with each new task in the case, so look up the index in the APPLICATION.DEL_INDEX field before calling this function.
• string or array config: Optional parameter available in Enterprise Edition to configure an alternative email server to send the message. It could be set with the UID or with an array of the other email server or user account configuration (See Use an alternative email server).

Return Value:

Returns 1 if email was sent to the configured email server; otherwise, returns 0 if an error occurred.

Note: As of ProcessMaker 3.4.0, all Parameters send through the trigger function normally. However, the behavior changes when the function returns an integer number for confirmation: instead of confirming an email has been sent through the email server, the artisan queue:work command adds the ProcessMaker function in the queue with a 0 or 1 to confirm for the job was created. For more information about it, see the artisan command.

When the Trigger Should be Set to Fire:

The PMFSendMessage() function can be used in triggers set to fire after a Dynaform step.

Example Sending Variables to a Template:

The following trigger code is used to send an email template named "LeaveRequestTemplate.html" to the user working on the current case. An array of variables is passed to PMFSendMessage(), so the @#reqUserName, @#reqSup, @#fromReq, @#toReq and @#daysReq fields will be filled in the template:

Example Sending Variables to a Template with different email server and/or user account:

The following trigger code is used to send an email template named "LeaveRequestTemplate.html" to the user working on the current case. An array of variables is passed to PMFSendMessage(), so the @#reqUserName, @#reqSup, @#fromReq, @#toReq and @#daysReq fields will be filled in the template. To allow emails to be sent out with a different email server and/or user account, the config parameter has to be added:

Example Emailing Attachments from the Process Files Manager:

The following trigger sends two files named "companyLogo.png" and "companyProfile.pdf", which are stored in the "public" directory of the Process Files Manager:

Example Emailing Input Document Files:

This trigger emails all the uploaded files in an Input Document whose definition has the ID "8935316924e692b256860c4075654232".

Note: This example only emails the latest version of input document files. To email all versions, remove from the query: AND AD.APP_DOC_STATUS='ACTIVE'

To email all uploaded files from a case, remove from the query: AND AD.DOC_UID='$inDocDef'

Example Emailing a File Uploaded to a Dynaform's File Field:

This trigger emails all the files uploaded to file fields in the current case:

Example Emailing Generated Output Document Files:

This trigger emails the PDF and DOC files of the latest version of an Output Document whose definition has the ID "691319281570bc9938b4460028767596".

PMFSendMessageToGroup()

PMFSendMessageToGroup() sends a notification to a group of users.

int PMFSendMessageToGroup(string groupUID, string caseUID, string from, string subject, string template, array aFields, array aAttachments, string showMessage, int delIndex, string emailServerUID, int limit)

Parameters:

• string groupUID: The group identifier. The email will be sent to all users that are currently part of the group. Note that inactive and on vacation users will NOT receive the email.
• string caseUID: The UID of a case, which is a string of 32 hexadecimal characters that uniquely identifies each individual case. For the current case use the system variable @@APPLICATION. Another case UID can be found with the PMFCaseList() function, the WSCaseList() function, the caseList() web service, or by using the executeQuery() function to query the wf_<WORKSPACE>.APPLICATION.APP_UID field in the database.
• string from: The email address of the person who sends out the email. Use the userInfo() function to get a user's email address. If it is necessary to include the person's name along with the email address, list the name first followed by the email address enclosed inside angle brackets < >. The name may be enclosed inside double quotation marks, but it isn't necessary:
  'Travis Grady <travisGrady@example.com>'

  or

  '"Travis Grady" <travisGrady@example.com>'

  Note 1: Due to security restrictions, Yahoo!, Gmail and many other email providers will no longer deliver email that doesn't come from the same email address as the account in the Email Configuration at Admin > Settings > Email. To avoid this problem, set the email address for the from parameter to the same email address found in the Email Configuration.

  Note 2: In the email server settings, you enter the Sender Account, Sender Email and Sender Name. Then, the From and Reply to in the email header is as follows:

  1. If the from parameter in the function is empty:
     From: SenderName <SenderAccount>
     Reply to: SenderName <SenderEmail>
  2. If the from parameter in the function is <sample.account@gmail.com> or sample.account@gmail.com:
     From: <SenderAccount>
     Reply to: from
  3. If the from parameter in the function is Sample Account Name <sample.account@gmail.com>:
     From: Sample Account Name <SenderAccount>
     Reply to: from

• string subject: The subject (title) of the email.
• string template: The name of the template file in plain text or HTML format that will produce the body of the email. Include the file extension in the file name. For example: "negativeResponse.html" or "caseStatus.txt"
• array aFields: (Optional) Parameter to define custom variables that can be inserted into the template file. An associative array where the keys are the variable name and the values are the variable's value. If no array is included, an empty array is included by default. Case variables defined in the same trigger that calls PMFSendMessage() should be passed to the email template using the fields array. See the example below for how to set the values in the fields array.
• array aAttachments: (Optional) An array of files (full paths) to be attached to the email. Paths can be web addresses or paths in the file system of the ProcessMaker server. For example:
  
  array('/home/foobar/clients/client_03452342.xls', '/var/www/public/profile.pdf', 'http://www.example.com/finances.doc')

  By default, files are attached using their original file names, which means that Input Documents, Output Documents and attached files are sent with filenames containing their unique ID and version number.

  If sending files stored by ProcessMaker, it is recommended to use ProcessMaker's predefined system constants, such as PATH_DATA_PUBLIC, PATH_DATA_MAILTEMPLATES, PATH_DOCUMENT and PATH_SEP, to construct the paths:

  • Files in the "public" directory of the Process Files Manager:
    PATH_DATA_PUBLIC . "<PROCESS-UID>" . PATH_SEP . "<FILENAME>"

    Example:

    PATH_DATA_PUBLIC . @@PROCESS . PATH_SEP . "letterheadLogo.png"
  • Template files (without inserted data) in the "mailTemplates" directory of the Process Files Manager:
    PATH_DATA_MAILTEMPLATES . "<PROCESS-UID>" . PATH_SEP . "<FILENAME>"

    Example:

    PATH_DATA_MAILTEMPLATES . @@PROCESS . PATH_SEP . "companyProfile.html"
  • Uploaded Input Document files and attached files:
    PATH_DOCUMENT . $g->getPathFromUID("<CASE-UID>") . PATH_SEP. "<CASE-DOC-UID>_<VERSION>.<EXTENSION>"

    Example:

    PATH_DOCUMENT . $g->getPathFromUID(@@APPLICATION) . PATH_SEP ."9743702654e6925b52e1e34098864192_1.png"
  • Generated Output Document files:
    PATH_DOCUMENT . $g->getPathFromUID("<CASE-UID>") . PATH_SEP . "outdocs" . PATH_SEP . "<CASE-DOC-UID>_<VERSION>.<EXTENSION>"

    Example:

    PATH_DOCUMENT . $g->getPathFromUID(@@APPLICATION) . PATH_SEP . "outdocs" . PATH_SEP . "6960198894e6927e0a40b14004833875_2.pdf"
• boolean showMessage: (Optional) If set to TRUE, which is the default state, then the email message will be displayed in the message history. If set to FALSE, then the email message will not be displayed in the message history, although a email record will be stored in the APP_MESSAGE table.
• int delIndex: (Optional) If not set to 0, the message will be associated with a particular task in the case, which is indicated by its delegation index. The delegation index for the current case is stored in the system variable @%INDEX. Note that the delegation index changes with each new task in the case, so look up the index in the APPLICATION.DEL_INDEX field before calling this function.
• string emailConfigUID: (Optional) Configure an alternative email server to send the messages. The email server configuration UID can be found using the executeQuery() function to query the wf_<WORKSPACE>.EMAIL_SERVER.MESS_UID field in the database.
• int limit: The limit of emails that can be sent in each batch.

Return Value:

Returns 1 if the emails were sent to the users in the specified group; otherwise, returns 0 if an error occurred.

Note: As of ProcessMaker 3.4.0, all Parameters send through the trigger function normally. However, the behavior changes when the function returns an integer number for confirmation: instead of confirming an email has been sent through the email server, the artisan queue:work command adds the ProcessMaker function in the queue with a 0 or 1 to confirm for the job was created. For more information about it, see the artisan command.

Example:

The following trigger code uses the userInfo function to retrieve the email of the user currently logged in. Then, it sends the emails using the email.html template to the group with the ID: "967043513571685b19ad9a3030022260".

PMFGetUserEmailAddress()

PMFGetUserEmailAddress() returns the email addresses of the specified user(s).

variant PMFGetUserEmailAddress(variant ID, string APP_UID=null, string prefix='usr')

Parameters:

• variant ID: A list of recipients, which can be a mixture of user IDs, group IDs, variable names or email addresses. To find the IDs of the users and groups, go to ADMIN > Settings > Web Services Test and use the userList() and groupList() web services, or look them up in the wf_<WORKSPACE>.USERS.USR_UID field or in wf_<WORKSPACE>.GROUPWF.GRP_UID field in the database. This list can either be an array with each recipient in a separate element, or a string with each recipient separated by commas ",". If the recipients are all the same type, then set that type in the $prefix parameter. If the list contains a mix of different types, then prepend "usr|", "grp|", "dyn|" or "ext|" before each recipient. For the user currently assigned to a case, use "-1" or "usr|-1".
• string $APP_UID: The unique of the ID of the case from which the emails will be retrieved. Notice that the result value will be obtained from the last open delegation of the case specified. If using a variable to get the currently assigned user, specify the unique ID of the case that contains this variable. If using "-1" as the first value to obtain the user currently assigned to the case's email, then the second parameter has to be @@APPLICATION.
• string $prefix: An optional parameter. Specify the type for all the recipients in the list:
  • "usr": All the recipients are users, so the ID is a list of the user's unique IDs. This is the default value if the parameter is not included.
  • "grp": All the recipients are groups, so the ID is a list of the group's unique IDs.
  • "dyn": All the recipients are variables, so the ID is a list of case variable names from the case specified in the $APP_UID parameter.
  • "ext": All the recipients have external email addresses, so the ID is a list of email addresses.

Return Value:
A list of email addresses. If the $id is a string, then a string will be returned with each email address separated by commas. If the $id was an array, then an array of email addresses will be returned. If there were no valid recipients in the $id, then the function returns false.

Examples:
Send an email to the user assigned to the current case:

To send an email to the currently assigned user and two users with the IDs "79498307748c8645cbed0d2037379255" and "6187429034914a77c452de6051925565" in the current case:

To do the same thing with an array of recipients:

Send out an email to the user IDs found in the case variables @@StoreManager, @@RegionalManager, and @@CEO in the current case:

Send out the same email as above, but use the case variables of a case with the ID "1014502514e4556596e2e29033579043":

Send an email to users, groups, variables and email addresses. In this example, the email is sent to the user currently assigned to the current case, all the members of a group with the UID of "6538387794e45573cdaa563079341214", a user whose UID is specified in the field "selectedManager" in a Dynaform, and to the email address "john_doe@example.com":

To do the same thing, using an array:

PMFAddAttachmentToArray()

The PMFAddAttachmentToArray() function is used to add an additional file to an array of files, which can be passed to the PMFSendMessage() function to send out emails with attached files. If a file with the same filename already exists in the array, it will add the file to the array, but rename its index key from "filename.ext" to "filename Copy(X).ext" where X is incremented so the original file doesn't get replaced.

array PMFAddAttachmentToArray(array arrayData, string index, string value, string suffix)

Parameters:

• array arrayData: An existing associative array of files, where the index key is the filename and the value is the file. To understand the format of this array, see the aAttachments parameter of the PMFSendMessage() function.
• string index: The new filename of the file to be added, which will also be the new index in the associative array of files. Note that the added file will be renamed with this value, so it is recommended to include the file extension, such as .doc, .pdf, etc.
• string value: The web address or the path on the ProcessMaker server of the file to be added to the array.
• string suffix: Optional parameter. A string that will concatenated to the index if the filename already exists in the array. Its default value is " Copy({i})", where {i} will be replaced by an auto-incremented number.

Return Value:

The modified associative array of files, with the new file added to it. This return value can be used as the aAttachments parameter in the PMFSendMessage() function.

Example:
In this example, the paths to 3 different files named "accountingGuide.pdf", "expenseReport.doc" and "expenseReport.doc" are in an array. Each file from the array is added as an attachment file to an email. The PMFAddAttachmentToArray() function is used avoid overwriting the existing files in the array of file attachments. Then PMFSendMessage() is used to send out the email with the file attachments.

The above trigger code will send an email to manager@acme.com with the attached files named "accountingGuide.pdf", "expenseReport.doc" and "expenseReport Copy(2).doc".

getEmailConfiguration()

getEmailConfiguration() returns information about the current email configuration.

array getEmailConfiguration()

Return Value:

Returns an associative array with the following information about the email configuration:

array(
"MESS_PASSWORD",	Encrypted password used to log in to the email server, such as: "vKbAqYO+urusxc6+xbp+eIF9"
"MESS_PASSWORD_HIDDEN",	Always set to "" (empty string).
"MESS_ENABLED",	Set to "1" if email notifications are enabled. If not enabled, set to "0".
"MESS_ENGINE",	The email engine, which can be "PHPMAILER" to use the PHPMailer program that supports SMTP, or "MAIL" to use PHP's mail() function to send the email via the mail transfer agent configured for the ProcessMaker server.
"MESS_SERVER",	The IP number or domain name of the email server, such as: "smtp.mail.yahoo.com"
"MESS_RAUTH",	Set to true if login needed to send out messages; otherwise set to false.
"MESS_PORT",	Port number of the email server, such as "25", "465" or "587".
"MESS_ACCOUNT",	The username of the email account. For some email servers, such as Gmail, the account name includes the full email address, such as:"joedoe@gmail.com"
"MESS_BACKGROUND",	HTML code of the background to the email message. Generally set to "" (no background).
"MESS_EXECUTE_EVERY",	Time between attempts to send message. If set to "", then uses the default.
"MESS_SEND_MAX",	Maximum number of attempts to send the message. If set to "", then uses the default.
"SMTPSecure",	The type of secure connection to the email server: "ssl", "tls" or "" (empty string for no secure connection)
"MAIL_TO",	Email address to whom the test email will be sent.
"MESS_FROM_NAME",	Name of the sender, such as: "ProcessMaker Admin"
"MESS_TRY_SEND_INMEDIATLY",	Set to "1" to send out a test email after configuring the email server or "false" to not send it.
"MESS_FROM_MAIL",	Email address of the sender of emails. In most cases this will be the same as the email account.
)

Example:
Check whether email notifications are enabled before sending out an email with PMFSendMessage():