Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Stardust/Knowledge Base/Integration/Application/Mail

Purpose

Possibility to decide upon the transitions at a split based on the user response submitted per email.

Attachments

The Stardust model (XPDL) and jsp files required by the Mail Application type discussed in this article can be downloaded from here.


Model Description

Suppose a decision is to be made about further transition in the process. At this point an email is sent to the user containing some links that the customer follows depending on his decision. Each link corresponds to a certain value of the variable in the model that is used in the split for transition conditions. Following model is used to implement an example of message transformation application:

Stardust Integration Mail.jpg

Hereby the structured data Customer is assigned with a composite type Customer containing following fields of type String: FirstName, LastName. The primitive data Order Amount and Decision are of type String (see MailApplication.xpdl).

Configuration of Mail Application

In general, the configuration of a mail application is described in the corresponding article in the Stardust documentation. At this point the necessary steps are summarized and listed in following:

  • Open the properties of the mail application. To test the project running on the local server, type the address of your mail server into Mail Server input line. Otherwise, specify the remote server that is used for sending mails.
  • As URL Prefix, specify the root web address of the application. In case of locally running project type http://localhost:<port>/<projectName> as in the figure below.

Stardust Integration Mail App1 Properties.jpg

  • In the Default Settings-Tab, input the default "From" address (arbitrary address) and default "To" address (valid address of the email recipient).
  • In the Plain Text Template-Tab, input the default text that is contained in the mail. For example:
    Hello,customer {0} {1} has placed an order of US$ {2} which exceeds the customer credit limits. Please decide about 
    further proceeding.

    The numbers in curly braces correspond to the template variables that are used as access points for IN Data Mapping in the model to set the corresponding part of  the mail text dynamically (cf. see documentation).

  • In the Output Values-Tab, specify the possible response messages being listed as links in the mail content. The text of the link is specified in the Name column. The value being passed to the process continuation as the return value of the mail application is specified in the Value column. However, the text of the link in the mail is displayed as specified in the Name column only if HTML format is active (flag on the checkbox HTML is set). Note that the entries in the column Value are used in transition conditions in the model (cf. split behavior of the activity Mail Approval in the model).

Stardust Integration Mail App1 Output.jpg

  • After submitting a decision request to the mail application servlet, this servlet will respond with a success page, if the request has been successfully submitted and the process is continued or an error page, if problems with the submission occured (e.g. a decision had already been submitted for this process). In order to specify the information to be displayed in case of successful submition or an error, the success and error pages has to be configured in the web.xml. Therefor, in web.xml, specify these web pages by modifying the param-values for successPage and errorPage for the servlet MailConfirmationServlet as follows:
    <servlet>
      <servlet-name>MailConfirmationServlet</servlet-name>
      <servlet-class>ag.carnot.workflow.mail.servlets.MailApplicationReceptionServlet</servlet-class>
      <init-param>
        <param-name>successPage</param-name>
        <param-value>http://localhost:8080/MailApp/successpage.jsp</param-value>
      </init-param>
      <init-param>
        <param-name>errorPage</param-name>
        <param-value>http://localhost:8080/MailApp/errorpage.jsp</param-value>
      </init-param>
   </servlet>

Note that at this point the web link to the project needs to be adjusted. In this example the name of the project is MailApp and it is running on localhost:8080.

  • In WebContent directory of the project, define the corresponding success and error JSP-pages named according to the servlet definition in web.xml (here: successpage.jsp, errorpage.jsp). The following code shows a simple custom JSP for the success page using request parameters:
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
  <head>
    <style type='text/css'>
    <!--
      body { background-color:#DBDBDB; font-weight:normal; font-family:Verdana; font-size:12px; }
    -->
    </style>
    <title>Custom Mail Confirmation</title>
  </head>
  <body>
    <img src='images/logo.jpg'/>
    <h1>Mail Confirmation</h1>
    <p>You decided to proceed with <b><%= request.getParameter("activity-name") %></b> with</p>
    <p>outputValue: <b><%= request.getParameter("output-value") %></b></p>
    <p>Thank you for your feedback.</p>
  </body>
</html>

Using Configuration Variables

The above sections illustrate the use of the Stardust Mail Application Type and are useful when the mail application settings are static (i.e. mail server, from address, to address etc. are known at model design time). There are however circumstances where these settings need to be dynamic (i.e. provided at run-time) for e.g. when deploying in a production environment vs. UAT. Rather than making changes to the model and redeploying a specific version to each environment, Stardust (starting version 6.0) now provides support for configuration variables where variable references are used within the model while the actual variable value is specified at deployment time.

Note: The model referenced in the following sections may be downloaded from here.


Stardust Integration Application Mail ConfigVars Model.png


As shown in the figure above all mail application settings are passed as IN data mappings and mapped to corresponding Access Points within the "Send Email" activity. An example mapping is shown below:

Stardust Integration Application Mail ActivityDetails.png

The primitive data "Mail_Server" is defined using the convention ${environment_variable_value} as shown below:

Stardust Integration Application Mail Mail ServerDataDefinition.png

The default value for such environment strings can be defined within the model by editing the model properties as follows:

Stardust Integration Application Mail ConfigVars Definition.png


At run-time the actual values to be passed to these environment variables can be provided through the "Configuration Variables" view of the "Administration" perspective as shown below. These values can be changed to suit your deployment scenario (production, UAT) etc, without having to make changes within the model itself and having to redeploy it. It is also possible to import and export these values from a property file. This file needs to be included within a zip file. You can learn more about this technique by exploring the "Export" and "Import" options provided in the above view.

Stardust Integration Application Mail ConfigVars View.png

Back to the top