The option Create mail content on commit is deselected by default (OFF), which causes all value resolvers in the E-Mail configuration to be processed immediately when the event action is executed.

• If this option is activated (ON), then the value resolvers are only processed when the transaction is completed. Then they also take into account data changes that are triggered only in the1 further course of the transaction after calling E-Mail. Among other things, this affects the automatic assignment for the ID (id) of new entities to be created, if not Fill primary key or Save changes later before E-Mail is executed.
  ►NOTE◄ In addition, the Send immediately option is disabled.

The Send immediately option is deselected by default (OFF), which means that the mail is only sent when the current transaction is completed successfully (without error/rollback or a Abort). Depending on the selection for the option Create mail content on commit, value resolvers in the E-Mail configuration are processed immediately or only on commit.

• If this option is activated (ON), then the mail is created and sent immediately, so that the value resolvers can only process the state at execution time.
  ►NOTE◄ The option Create mail content on commit is deactivated.

If the ‘ID’ (id) of the generated email entity (see E-mails) is required for subsequent steps within event processing, this can be saved in a variable. For this purpose, the name of a variable must be entered in the Store Mail Id as a variable field.

The selection for the Mail save mode defines whether and, if so, under which conditions the message is to be saved as an e-mail object when the event action E-Mail is executed. The creation of E-mails can be:

• Never (by 'Don't save mail')

• Always (by 'Save always')

• Only in case of errors (by 'Only save on error').

The selection for the Log level concerns the level of detail for the 'Creation log', which documents the processing steps of the event action E-Mail and is traceable from saved E-mails depending on the selection for the Mail save mode in the 'Creation log' (mailLog) field.

• The default selection 'ALL' ensures maximum detail in the creation log.

• With the 'OFF' selection the creation log is always empty.

• For the intermediate levels FATAL, ERROR, WARN, INFO, DEBUG and TRACE the selection always determines the threshold value for the alert level from which entries appear in the log. In the enumeration, categories mentioned earlier are therefore always included, categories mentioned later are excluded.

►NOTE◄ If the Mail save mode is set to 'Don't save mail', the Log level should be set to 'OFF' for optimal performance, otherwise the log will be created temporarily and then discarded.

The text for the Subject of the e-mail is a required field.

It can be defined either by direct input as static Text or – after clicking on the small grey arrow in the text field – as a return value from a value configuration (e.g. via the Value from localization value resolver).

The Body content type parameter requires a static selection for the MIME type of the message body as a required field. Whether the selected type can be correctly displayed by a recipient ultimately depends on the mail client used. The field lists by auto-completion types can be interpreted by most mail programs. Alternative entries are possible, but are only useful as long as the mail client of the recipient also supports these formats.

The Mail body builder parameter defines the body content of the e-mail as a string whose content should match the specified Body content type.

The text for the mail body can be generated in different ways. The examples on the right demonstrate only a few selected procedures that can be used individually or in combination to systematically generate the 'appropriate' content for the message to be sent:

• The first example defines a static text via direct input in the configuration, which neither includes localizations from the Localization nor contents from the reference object or other 'data sources'.

• The second example shows how a value resolver of the Template type can be used to schematically prepare selected data from the data model of the reference object:

  Runtime example

  ■ base:CompanyAccount

  └ id = 1902

  └ creatorId = 1901

  └ ownerId = 702

  └ lastModifierId = 1901

  ►NOTE◄ The Template value resolver is also good for filling in placeholders in a given cloze text, which then do not look as technical as in the example.
  
  

• The third example shows how the value resolver Value from localization can be used to fill a cloze text stored specifically for different languages via parameters with texts that are determined at runtime as return values of the configured value resolvers.
  
  ►NOTE◄ In the example, the reference object is a user account just activated by the administrator, from which the language (locale) for localization is taken in addition to other information (username in the username field, list of selectable companies in the companies field). The new user is thus automatically welcomed in the Locale defined for his account, provided that the corresponding localization is stored for the Bundle EMAIL_NOTIFICATIONS and the Resource 010_WELCOME_NEW_USER. The text for the Default value in English is used if the resource bundle entry is missing completely. It also clarifies here how the parameters {0}, {1} and {2} are included in the text. The parameter {2} is to define the login link. Since this does not need to be localized, only static text is assigned here.

The From tab contains three parameters that can be used to send the e-mail in one of the two alternative ways (see ‘Requirements for sending e-mails’ above).

• The Partner name and Channel name parameters can be used to identify a ‘Partner channel’ (with the ‘Mail’ type), which must contain a suitable configuration for the ‘Outbox’ (via SMTP) so that E-mails can be sent.
  
  

  • As long as neither a Partner name nor a Channel name is specified, the third parameter From is a required field. The e-mail address entered there is then processed in conjunction with the default configuration for sending e-mails from Lobster Data Platform / Integration.

  • If a partner channel is addressed via Partner name and Channel name, the From parameter can still be used to specify a sender address that must be permitted for use in the context of the associated SMPT configuration.

Initially, all three text fields always appear as required fields (see screenshot top right). The text can be defined either by direct input or – after clicking on the small grey arrow at the bottom left of the element – via a value configuration at runtime.

• In the first example, a noreply address was specified by direct input, which is intended to make it clear to the recipient that a reply to this sender is pointless.
  
  

• The second example shows how the value resolver Mail address user can be used to obtain the sender's e-mail address from a specific communication information of the logged-in user. The value resolver returns a list of all entries with the Contact type ‘'E-mail'’ whose value in the ‘Context' field matches the specification for the Context communication info parameter. If several email addresses are specified in the user account for the requested context (here: mailFrom), only the first one found is taken into account for sending.
  
  

• The third example refers to a ‘Partner channel’, which is addressed via Partner name and Channel name:
  
  

  • The Partner name is determined by a value configuration that accesses the value of the Variable FROM_PARTNER as the ‘Partner name’ at runtime.
    
    

  • The Channel name, on the other hand, is defined as the static Text MAILOUT.
    
    ►NOTE◄ A partner whose name is specified in the Variable FROM_PARTNER should therefore have a ‘Mail’ channel with the name MAILOUT so that E-mails can be sent with this configuration.

.

Example 1: Sender address (From) as static text

Example 2: Sender address (From) with value configuration (Mail address user)

Example 3: Reference to a ‘Partner channel’ via Partner name and Channel name

The tabs Recipient, Cc (Recipient for copy) and Bcc (Recipient for blind copy) allow the specification of e-mail addresses for recipients of a message, which can be defined similarly to the From tab either as direct input or via value resolvers.

While the sender (see From tab) of an e-mail must be uniquely determined by definition, multiple addresses can be specified for each recipient type. For this reason, a Repeatable element is offered for the address input, in which instances for the value assignment can be added and removed via the symbols and .

Based on the value assignments for these instances, e-mail participants of the respective types ('To', 'Cc', 'Bcc') are generated for the message according to the following logic:

• The value assignment can be done individually for each instance either by direct input or by a value resolver.

• For direct input, multiple recipient addresses can be concatenated with a semicolon as a separator (see the first example on the right) to assign the entire string all together as a value to a single instance. In this case, however, the addressees do not appear in the e-mail object as individual 'participants', but only as a common entry that is identified by the concatenated address list.

• When a value resolver is configured for an instance, it should return either a text value (string) or a list of text values (string[]), which is the case for the value resolvers E-mail. In both cases, each individual text value is interpreted like a direct input: One e-mail participant of the respective recipient type is created for each text value (single address or concatenated address list).

Examples (right):

• The first example shows how to define a static list of recipient addresses in the first instance of the input field in the Recipients tab as direct input with concatenation via the semicolon.
  
  

• The second example shows how two instances of the input field are used in the Cc tab to read e-mail addresses from the communication information of a specific company (by the Mail address company value resolver) and the company defined via the company attribute with the Company type 'Principal' (by the Mail address company attribute value resolver). In both cases, the same key value is used for the Context communication info (notify). In each case, all matches for the Communication type 'e-mail' are taken into account as Cc recipients that refer to this context.
  
  

• The third example shows how to access a specific text attribute 'E-mail' (EMAIL) in the reference object in the tab Bcc via the Mail address text attributes value resolver, in order to obtain an e-mail address for the recipient of a blind copy. If the text attribute is plural, multiple entries may be taken into account and returned as list values.

Example: Direct input for multiple chained receivers

Example: Value resolver for recipient of a copy (Cc)

Example: Value resolver for receiver of a blind copy (Bcc)

The Attachments tab provides a Repeatable element where parameters for one or more file attachments for the message can be defined.

The and icons can be used to add or remove configurations for file attachments. The following parameters are repeated per attachment:

• The File name (required field) expects a static text value as input for the name under which the file attachment should appear in the message.

• The MIME type optionally defines the 'media type' for the Content to be attached. The text field works with auto-completion to facilitate entering a suitable key value (e.g. application/pdf , image/png , text/xml ...). If no specification is made, then a plausible MIME type is automatically assigned to the attachment based on its Content.

• The following data types can be used as Content for a file attachment, which can be passed individually or as a list:

  • Text (string)

  • Action event content (Content, see Content builder)

  • File information (FileInfo, e.g. from a File element in a form)

  • Document (Document, see Documents)

  • ByteArray (byte[], e.g. from a Load web resource behaviour)

►NOTE◄ If the data object provided as content includes File name and/or MIME type specifications (see table below), these override the corresponding configuration parameters. This is especially helpful if the Content is defined via a value resolver such as Attached document which can return multiple contents.

►NOTE◄ The data type 'Action event content' is also suitable for creating a 'cover' for another content (e.g. text or byte array) via a Create instance, which can then be used to assign a File name and a MIME type.

Examples:

• In the first example on the right, the Object to server xml value resolver is used to attach the data of the reference object as an XML file. Suitable specifications are made for File name and MIME type.

• In the second example on the right, two instances are configured for Attachments in which the Attached document value resolver is used to return the Documents assigned to the reference object for one Document type at a time. The text dummy was entered as File name to fill the required field on a pro forma basis. A MIME type was not assigned, since this is determined automatically together with the name from the data of the Documents (if available).

Example: XML of the reference object (order) is attached as 'order.xml' file

Example: Documents related to the reference object are attached