The example on the right shows the account of a guest user in XML format created via the Create guest user event action in the context of a related object of the 'Orders' type:

• The default fields of the guest user object, which are anchored as XML attributes directly in the base:GuestUser element), have been omitted here in favor of a clear representation, with the exception of the id attribute.

• Inside the element you can see the structure of the guest user restriction (restriction), which contains a 'map' with exactly one entry (entry) in a field that is also named restriction.

• The key (key) value is the entity type of the reference object (Order).

• The value (value) defines the restriction as an OR junction (DISJUNCTION) of two restrictions:
  
  

  • The OnlySelfCreatedRestriction specifically allows access to orders created by the guest user. For these the following applies (here): creatorId="-5805", since references to guest user IDs are shown negatively to distinguish them from regular users.

  • The WhiteListRestriction, on the other hand, explicitly allows access to the order with the ID (id) '5001'.

The ribbon macro command 'Add guest user' can be triggered by clicking on a ribbon button. The example on the right shows a custom button for this purpose.

Then the dialog shown below appears first, which requires the user to enter an E-Mail address for the newly created guest user.

A click on the 'X' symbol in the upper right corner of the dialog title is considered a cancellation of the ribbon macro without further effects. If applicable, subsequent commands in the same macro will not be executed.

Clicking the Create Button triggers the 'Create guest user' event (see Guest user (Events)), which passes the current reference object as an input value and the E-Mail address entered in the dialog as the value of a guestUserEmailAddress variable.

►NOTE◄ The input for the E-Mail address is not validated in any way. The Create button can also be pressed if no input has been made. Then the variable guestUserEmailAddress contains an empty string ('') and not, for example, 'no value' (null).

▼

E-Mail address in the Variable guestUserEmailAddress
▼

Provided that for the event 'Create guest user' (see Guest user (Events)) event handlings are configured, these are processed. Typically, the Create guest user event action is used to configure the data for a new guest user whose E-Mail address is taken from the guestUserEmailAddress variable.

A corresponding event handler could run checks on the value of the guestUserEmailAddress variable before the Create guest user event action, to ensure the plausibility of the input as an e-mail address:

• If the input is classified as unsuitable, the event handling can – if necessary in connection with a suitable message for the user – be terminated via the Abort. Then the input dialog remains open, so that the user can adjust his input for the e-mail address appropriately and trigger the 'Create guest user' event again by clicking the Create Button.
  
  

• The dialog remains open even if a 'real' error occurs during event handling. If necessary, the user must close this dialog by clicking on the 'X' icon to cancel the macro without creating a guest user.

►NOTE◄ If no event handling reacts to the triggered event 'Create guest user', the dialog is closed without comment and without further effects. This is also the case if event handlings are triggered that are processed without errors without the event action Create guest user being executed.

▼
New guest user in the variable createdGuestUser
with login data in the 'Login token' field (loginToken)

Provided that the Create guest user event action is successfully triggered in response to the 'Create guest user' event (see Guest user (Events)), a message like the one shown on the right will appear when the transaction is completed. This will return the automatically created Login token that the created guest user can use to log in to the system. As a rule, this token should also be sent to the guest user by e-mail. For this purpose, the event action E-Mail is typically executed in the context of the event action Create guest user.

The Configuration (shown expanded on the right) provides the following parameters for assignments for the created guest user account:

• The Locale expects a value from the dynamic enumeration Locale. By default, a value resolver is therefore offered that allows static assignment via a dropdown. Instead, any other value resolver can be configured that returns a value from Locale or a string that exactly matches the internal name of one of these values (otherwise an error occurs).

►NOTE◄ A Locale can be assigned regardless of whether it would be selectable by a dropdown in the Guest users input form. Dynamische Aufzählungsfilter filters or the designation as a 'Supported language' (see Locale) therefore have no restrictive effect. The assigned language is also assigned as the 'Current language' when the guest user logs in and – if applicable entries exist in the Localization or Company specific localization – is taken into account for localizations.

• The Max. logins and Max. concurrent sessions parameters are preassigned analogously to the default Guest users form. Different integers can be assigned statically.
  
  

• The Valid days parameter is used as an offset to assign an absolute date value to the 'Valid until' field of the guest user account, which is calculated 'to the millisecond' relative to the call time.
  
  

• The E-Mail address parameter accepts either direct input of text or (by clicking on the small gray arrow at the bottom left) a value resolver configuration that returns a value readable as text.
  
  ►IMPORTANT◄ Each time a guest user is saved, it is checked whether the length of the double-trimmed string in the E-Mail address (emailAddress) field is at least 5 characters. If this is not the case, an error message occurs (with note: 'Invalid mail address' incl. rollback). The check takes place only after the create event has been triggered when the transaction is completed, so that, for example, within an event handling for the create event (with a type check for 'guest user'), it would still be possible to react to 'defects' in the E-Mail address. Running Create guest user within a Try/Catch actor cannot rectify this error, as it is triggered later on.

• A valid return value must be present for the Role and Company parameters at runtime, otherwise an 'Invalid configuration' error (including rollback for the current transaction) will occur when the configuration is processed (and not just when the transaction is completed). Static assignments can be defined with the value resolvers Role and Company value (see Sitzungsbasiert (Wertauflöser)). For dynamic associations, the relevant data object of the 'role' or 'company' type may have to be determined via the value resolver Input object (type safe) or via a Search (Event action).

In the Then actors block, event actions can be added by clicking the icon. In addition to the reference object that is valid unchanged within the Then actors section, they also have access to the new guest user object created on the basis of the Configuration via the Variable createdGuestUser, which is only created when the transaction is completed.

►NOTE◄ Event actions that are configured as Then actors typically could be placed as successors below the Create guest user event action. Access to the reference object and the createdGuestUser variable also exists for event actions outside the Then actors block after executing Create guest user. So, adding event actions as Then actors emphasizes the binding to the guest user account creation in purely organizational terms.

For the Triggering event 'Create guest user', an event handler is created and configured as shown below:

• The Validating rule is a Typprüfung that ensures that if the rule passes, the Actions on passed rule are executed only in the context of an entity whose type belongs to the 'business transaction objects' category. If or under which conditions the triggering ribbon button is available in a form for a certain concrete entity type from this category can be controlled independently of the type check via Association criteria.

The Actions on passed rule are first presented here in an overview. For selected configurations, the details follow below:

• The If then else event action is to cancel event handling according to the caption if the e-mail address entered via the input dialog automatically displayed at runtime is evaluated as unacceptable.
  
  ►NOTE◄ The acceptance criteria for a text as an e-mail address will not be covered in detail here. For this purpose, an arbitrarily complex logical link can be created. The decisive factor is that an Abort is executed if the input is not accepted. The user can be referred to the check criteria in the text of the message when aborting.
  
  

• If an 'acceptable' e-mail address is present, then the Create guest user event action is executed to create a new account with the described Configuration. In the block Then actors follows a E-Mail event action, which provides the new 'guest user' with a login link via e-mail.

The Configuration within the Create guest user event action can be seen expanded on the right side:

• The value for the Locale in which the guest user should work when logged into Lobster Data Platform / Orchestration is 'looked up' from the corresponding setting in the'Principal's' company account specified in the business transaction object.
  
  

• The value 0 for Max. logins allows an unlimited number of logins until the account expires for a limited time.
  
  

• The value 1 for Max. concurrent sessions defines that multiple concurrent logins with the same guest user are not allowed.
  
  

• The value 7 for Valid days schedules the expiration of the guest user account relative to the time of creation.
  
  

• The E-Mail address is taken here from the Variable guestUserEmailAddress filled via the input dialog.
  
  

• The Role is statically assigned as 'XF_GUEST' by the Role value resolver.
  
  

• As a Company, reference is again made to the company association (company field) in the company and address attribute for the 'Principal' in the business transaction object.
  
  ►NOTE◄ The button is only available via the Association criteria for the ribbon macro if a company is selected in the selected business transaction object as the 'Principal'. This is because the event action and therefore the transaction in its entirety fails with an error message ('Invalid configuration') when no company is referenced.

The configuration for the event action E-Mail within the Then actors is shown expanded on the right:

• Since the Send immediately option is not selected, the mail is sent only at the end of the transaction, so that the new guest user is notified only if the account was actually created.
  
  

• In Subject, a value resolver of the Template type is used to demonstrate how to access the Variable createdGuestUser via an XPath expression, which is contained in the print XML (core:Print) as an input (entry) with its name (key) and the data of the guest user object as its value (value). The subject of the e-mail should contain the expiration date for the account, which can be read in the validTo field (with the dateValue and timeZone attributes). The $date() function (see Template) creates a user-friendly text from this (see the runtime example below).
  
  

• The Mail body builder demonstrates another method to include features of the guest user object in the text. Here, the value resolver is used to access the loginToken Object property, which is set as a value for a URL parameters of the same name in the 'login link' by Concat strings.

►NOTE◄ The message was kept very compact in the example and implemented without reference to Localization. In practice, the subject and/or the mail body will also contain information about the business transaction object, which is the reference object in the context of the Then actors. In addition, the Locale assigned in Configuration (see above) for the guest user login should also be taken into account with regard to notification. In this case, a value resolver of the Value from localization would be recommended, via which a localization entry is referenced with parameters to which the corresponding details from the guest user or the business transaction object can be assigned at runtime.

Runtime example:

The example on the right shows the notification that is sent to 'j.doe@acme.net' when the e-mail address is entered.

►NOTE◄ Typically, the link in the mail body of the message will be clickable in the mail client, even though the Body content type is assigned to text/plain. However, the preview in the mail object, from which this screenshot is taken, does not automatically format it as a link.