The Email Integration template is an easy to use web application that allows users to easily import unread emails from a specific address to their database. While this template can be launched from the browser, it has no HTML layer and has been specifically designed to be run from within m-Power’s scheduling utility.
The general use for this template allows developers to check an email address for unread emails and insert these emails into a table. This action can be fully customized to only insert specific emails, to return additional data to each email’s record, or even to parse the email’s fields to pull out pertinent data such as a customer or invoice number. This template only has one action mode, which is to add a new row.
This template can only modify one table, so no joins are allowed. If needing to insert data into more than one table, consider building a view over the needed tables and fields, and then use that view when building your Email Integration maintainer.
Video Walkthrough
Regardless of what your end goal is, the design will be roughly the same. Users will send emails to a non-monitored email account. These emails would then be automatically saved into your database for either a specific employee to address, or simply the next available one.
To demonstrate this feature, I will show how to create an online suggestion box. Users will have the ability to suggest ways to make my fictitious company, CrazyBikes.com, can improve.
First, it is necessary to create a table to store my email data. I have done this previously and registered this to m-Power. Notice the structure of this table is designed to mimic an email’s structure, with subject, body, header, etc.
Now that we have our table, our next step will be to create an application using the email integration table. The steps to build this type of maintainer do not differ too much from a standard maintainer. First, I will select an application number, title and template. Next, I will select our email table, and all fields within that table. Then, I will set up our ID field as an auto sequencing field by adding it as a sequence key, and then adding *AUTOSEQ to the field description within the field settings section.
Finally, I need to tell m-Power which sections of the email I want to save, and where I want to save it. This is done on the application settings screen with the Template Specific Build Properties feature. On this screen, I can map the subject to my table’s subject field, as well as the rest of the email’s sections.
Now that this is done, we will need to compile. Finally, we need to tell this application which email account to use, as well as what folder within the account to use. This is done in the application properties. Notice that there are sections here for the email address, password, email server, folder to look in, email protocol, as well as any additional properties needed for the email account.
In addition, there are two optional properties that can be set, which includes whether to preferentially use the plain body or HTML version of the email, as well as where to upload any attachments, if wanting to save email attachments on the server.
Now that this is done, we can test this by sending an email to our previously set up email account. Notice how I am filling out the email normally, with a subject, body, and picture attachment. Now that the email is sent, let’s go to a previously built retrieval to see how it looks. Our email is not in the table yet, so we can click the refresh link. There is our email, so let’s view it.
In this example, we used a link to manually check the email account for unread emails, however you would normally schedule this maintainer to run every so often using m-Power’s scheduler, resulting in no additional work to have every unread email inserted into the database.
This is only the tip of this powerful template, and this can be further customized to parse emails for additional data, restrict which emails are uploaded, or even grab additional data outside the email for adding to your database table. For full documentation on this template, be sure to read the online manual. Feel free to also demo this feature yourself. You can send an email to crazybikes.demo@gmail.com, and then go to the link on the screen to see your email automatically be inserted into the database.
Template Notes
Application Settings
Description: Allow developers to specify their application’s description (similar to a name).
Program Name: This will be the application’s number; by default m-Power uses the letter M (Maintenance) followed by a five digit number.
Template: You can select a template by scrolling left or right through the available templates. The templates define the general layout and functionality of the resulting application. This section will list all the available maintenance templates; you will see a small screenshot of what that template looks like at runtime. Learn more about templates.
Compile Options: The compile options allow the developer to map the different parts of the email to fields within their table. The different fields to be mapped include:
- Email Subject
- Email Body
- Email Sender
- Email To Address
- Email CC Address(es)
- Email Reply To Address
- Email Sent Date
- Email Received Date
- Additionally, up to 5 Email Attachments can also be uploaded to a directory of your choosing
Data Selection
Here you will see/modify the table you have selected for your application. When selecting tables, bear in mind that only one table, the primary table, can be used. If needing to insert data into more than one table, consider building a view over the needed tables and fields, and then use that view when building your Email Integration maintainer.
Sequencing
Like all m-Power applications, a sequence key is required. However in the email template, the only requirement for sequencing is that any field you wish to auto-sequence by must also be a sequence key. Otherwise, you may pick any field from the application.
Field Settings
Delete: You can delete fields by clicking the checkbox and clicking Accept. If a field has a red circle with a cross line, that means that the field is being used somewhere else in the application (sequence, calculation, etc.), and, due to this dependency, is not available for deletion. NOTE: deleting a field will remove the field from the application only, the table will be unchanged.
Field Name: This is the same name the field has in the table.
Table: The name of the table where that field exists.
Field Description: This is the text that will appear in the column header for that field, you can modify this field to suit your needs. This field will populate with the field description from the table by default, but it can be customized at the application level.
Type: A drop down list that allows developers to designate whether a field is to be displayed (visible, but not edited on the database), hidden (no action), or updated. There may be situations where a field is needed for calculation purposes, but the field does not need to be displayed at runtime. Note: Sequence keys must be set to update to ensure your application functions properly
Size: This displays the length of a field. If a field has a length consisting of two numbers separated by a comma, the first number will be the integer length and the second the decimal length of the field.
Numeric Format Code: For numeric fields, you can modify the way the numbers will display, this includes displaying commas or not, how to display negative numbers, etc. Multiple formats are built in for developers to use, shall you need a different format code, m-Power allows developers to create their own User Defined Format codes; these codes will add logic for common types of fields such as: Currency, Time, or Dates. Accessing the User Defined Format Codes from the Admin section will also allow developers to modify current codes. Learn more.
NOTE: Do not confuse the User Defined Format Code with the User Defined Functions (UDF). The latter is a feature that allows developers to create or incorporate programing functions into m-Power. Learn more about UDFs.
Lowercase: This option determines whether or not an alpha field can be submitted to the database with lowercase letters. If this is set to “no,” the field will be converted to uppercase when it is submitted.
User def: If you would like a user to be able to upload a file over a field, select the letter ‘U’ from the dropdown. The remaining options have been deprecated.
Validity Rel, Validity Check Value, Default Value for Add: These options are not supported with the Email Integration Template.
Record Selections
Record Selections can be created over any database fields. In the Email Integration template, record selections can be created over fields in order to restrict which emails are inserted into the database.
Calculations
Calculations are not supported in the Email Integration Template.
External Objects
This feature allows developers to connect m-Power application with their current business logic, or to extend m-Power capabilities by allowing developers to write their own Java, RPG, or SQL programs, and integrating these programs into the applications. m-Power utilizes “locations” to connect the external objects, these locations vary depending on what the external object does and when it should be executed. The following locations are supported in this template:
*BEFOREADD This location calls the object only before a user Adds a row.
Click here to learn more.
Note: There are two external objects that ship with m-Power that were designed specifically for use with this template. These include:
Return Data External Object
Regular Expression External Object
SmartLinks
Since the Email Integration template does not have an HTML skeleton, SmartLinks are not used.
Additional Note After performing any changes in the above sections, the application must be recompiled for the changes to load. If the changes are to be displayed at runtime, then the Presentation Layer code (HTML) must be overwritten when recompiling the application.
Application Properties
When accessing the Application Properties, a popup window will open with multiple tabs; let’s go through each of the tabs:
Program Options
email_server: This property controls the address m-Power uses to connect to the email server.
email_address: This property specifies the email address m-Power will connect to for retrieving emails.
email_folder: This property controls the folder that m-Power will search through for unread emails, such as ‘Inbox’.
email_server_password: This property specifies the password for signing in to the email account.
email_protocol: This property controls the protocol used for retrieving emails.
email_server_properties: This property specifies any additional properties needed for the email server.
email_content_type: This property controls whether the Plain Text email body or HTML email body is used preferentially. Note: If the selected body type is not found, the other will be used automatically.
upload_directory: This property specifies where uploaded files will be located on the server. Use $(mpower) to substitute for the location of the m-power installation (ex. C:\production\mrc\m-power). More Information
upload_max_size: The size of uploaded files cannot exceed the value of this property.
ajax_form: AJAX from submit will submit and refresh only the HTML form, unlike traditional form submit, which will refresh the entire page. More Information
skip_db_actions: This property allows developers to specify whether or not database actions are skipped. By default this is set to “No”. This is often used in maintainers to invoke an external object without writing to the database.
hide_header_footer: Selecting “Yes” for this property will hide the header and footer, whereas selecting “No” will display both.
After Actions
add_message: The task group to call after adding a record successfully.
add_application: The application to call after adding a record successfully.
In any of the above cases, use ${FIELD} substitutions to insert submitted form values into the URL where FIELD is the field name.
SQL Statement
Override Properties
This section allow developers to override the default error messages , by selecting the error message you wish to customize, and then simply modifying the “Value” section to whatever you would like your message to say at runtime in place of the default message. More Information