xAPPnow LOW CODE PLATFORM - User Manual 

Still no account yet?
×

Training Frontend Service - Email Connector

 
Related subfolder of the training project: "Automation/Service/Training/Service/Exercise/EmailConnector"
 
 

Chapter Overview

 
In this training chapter you will get familiar with the Email Connector which allows to send an email and fetch a list of unread emails from the inbox.
 
 

Precondition

 
Before you can start working with an Email Connector the following preconditions have to be available
 
  • External System Configuration - configuration of an external system access in the User Portal
  • Connection Object - special kind of a definition object containing the connection configuration
  • Error Object & Error Definition Object - special kind of business object and definition object to store the possible errors returned by the Email connector
  • Error Handler - submodels to handle fatal error of the Email connector
 
 
 
1. External System Configuration
 
As a first step you need to ask your system administrator of the xAPPnow User Portal to configure the system access of the external system for the specific runtime environment. For this sample we will use an external system configuration with a gmail account to send the email and to fetch the unread emails.
 
The screenshot below demonstrates the external system configuration "EmailConnection" used in the tutorial.
 
Training Frontend Service - Email Connector
 
 
2. Connection Object
 
In a second step you have to add a connection object of type "EMAIL" to a Definition Object Model of your project. The name of the connection object "EmailConnection" must be provided by the system administrator (see "External System Configuration" above).
 
 
Tutorial Model: Automation/Data Object/Tutorial/Service/DEF
 
The screenshot below demonstrates the definition connection object "EmailConnection".
 
 
 
Training Frontend Service - Email Connector
 
 
 
REMARK:
 
The connection objects don't have the attribute names and values for a security reason. A developer must never know the access values to any external system. In addition it is never possible to write any access values into a logfile or display them in a UI page etc.
 
 
3. Error Object & Error Definition Object
 
Step number three is very important to handle possible error (e.g. "authentication exception") that could occur during an Email call.
 
For each connector type (DB, REST, Email etc.) you have to add a specific Error Definition Object and the related specific Error Object once within each project, as well as one single generic error BO "GenericError". The Error Object defined that holds the current error category, error code and error details as well as the boolean attribute isBusinessError (false = Fatal Error). The business object "GenericError" is a general error object to accept all kinds of error and is typically used to display an error in the UI page.

 
Tutorial Model: Automation/Data Object/Appollo/CommonBO
 
The screenshot below demonstrates the error object "ErrorFile" which is required for a Email Connector
 
 
 
 
 
 
Tutorial Model: Automation/Data Object/Appollo/CommonDef
 
The screenshot below demonstrates the error definition object "ErrorFile" which is required for a Email Connector and contains the multi-lingual error codes.
Additionally, the error definition "ErrorCategory" contains the multi-lingual connector names to be used in UI pages to display the multi-lingual error category.
 
 
 
 
 
 
4. Error Handling
 
Within this last precondition we will add a submodel for the fatal error handling to the project. The fatal error will be displayed in a  multi-lingual UI Dialog "FatalError" plus the stack trace, which can be analysed by the developer or system administrator.
 
 
Tutorial Model: Automation/Service/Base/API/FatalErrorHandler
 
The screenshot below demonstrates the submodel "FatalErrorHandler"
Tutorial Model: Automation/User Interface/Base/UIPage/FatalError
 
The screenshot below demonstrates the design of UI dialog "FatalError" on the editor
 
 
 
 
 

Model Explanation

 
The model starts with an "Init" script to create the list of emails. Then an Email Connector to fetch the unred emails is called. The UI page "Display Emails" displays the list of unread emails returned by the connector. From this UI Page is possible to open an email as read-only or to create a new email and send it using a second Email Connector "Send Email". 
 
In case an error occurs, the call element "Error Handler" is triggered which displays the details of the fatal error in a modal dialog.
 
Training Frontend Service - Email Connector
 

Exercise - Email Connector

 
In this exercise you will learn how to use an Email connector.
 
Exercise 1: Create the Model "EmailConnector"
 
  • Step 1: Right click at model tree folder "Automation/Service/Training/Service/Exercise/EmailConnector" to open context menu "Create Model"
  • Step 2: Enter model name "EmailConnector" and select option "Model Type: Dynamic Frontend Service" in dialog "Create Frontend Service Model"
  • Step 3: Click button "Search" to open dialog "Select Template" to select model "TMPL_EmailConnector" from folder ".../Template/EmailConnector"
  • Step 4: Click button "OK" to create the model
 
 
 
Training Frontend Service - Email Connector
 
 
Exercise 2: Complete the model "EmailConnector"
 
  • Step 1: Drag&Drop an Email connector from palette and enter label "Fetch Unread Emails" at the right side of the script element
  • Step 2: Draw a flow from script element and other flow from link event to Email connector element "Fetch Unread Emails"
  • Step 3: Draw a standard flow from email connector to UI Page "Display Emails" and a fatal error flow to the call element "Error Handler"
  • Step 4: Drag&Drop an Email connector from palette at the right side of UI Page "Compose Email" and enter label "Send Email"
  • Step 5: Draw a button flow from UI Page "Compose Email" to the email connector "Send Email"
  • Step 6: Right click on button flow to open context menu and select flow label "Send"
  • Step 7: Draw a standard flow from Email connector to the link event "To Fetch"
  • Step 8: Draw a fatal flow from Email connector element to call element "Error Handler"
     
 
 
Exercise 3: ConfigureEmail Connector
 
In this exercise you will configure each Email connector.
 
 
Function "Fetch Emails"
  • Step 1: Select Email Connector "Fetch Unread Emails" and open TAB "Implementation", SubTAB "Configuration" to configure the Email Connector
  • Step 2: Select Function "Fetch Multiple Email", map on Email Object "emailList", on Connection Object "EmailConnection" and Error Object with "errorEmail"
 
 
Training Frontend Service - Email Connector
 
 
Function "Send Email"
  • Step 3: Select Email Connector "Send Email" and open TAB "Implementation", SubTAB "Configuration" to configure the Email Connector
  • Step 4: Select Function "Send Email", map on Email Object "email", on Connection Object "EmailConnection" and Error Object with "errorEmail"
 
 
 
Training Frontend Service - Email Connector
 
 
Exercise 4a: Publish the Model
 
  • Step 1: Click button "Publish" to open dialog "Publish Model"
  • Step 2: Enter username and password
  • Step 3: Click button "OK" to publish the frontend service model
 
 
Exercise 4b: Publish the Fatal Error Handler
 
  • Step 1: Open model "Automation/Service/Base/API/FatalErrorHandler" to publish the fatal error handler
 
 
Exercise 5a: Test Model in User Portal (Standard Execution)
 
 
  • Step 1: Login into User Portal and open menu "Frontend Services" to start service "EmailConnector"
 
 
Training Frontend Service - Email Connector
 
  • Step 2 : Verify the list of emails of the test account
 
 
 
  • Step 3 : Click button "Compose" and enter address, subject and text data to send the email
 
 
 
 
 
 
 
1

Select Template

1. Select Template
Click button "Search" to open dialog "Select Template" to select model "TMPL_EmailConnector" from folder ".../Template/EmailConnector"