Required Settings for sending E-mail messages
Using your own (corporate) mail server for handling emails has the additional advantage of logging and providing information:
when your messages cannot be delivered to recipients, the Non-Delivery-Reports will be available on your own mail server, so you can act on that information.
Also, all sent items can be found in the mailbox of the used sender – available for review, follow-up, or just evidence that a message has indeed been sent.
The sender you set on the e-mail process node (from-parameter) must have the same domain as the SMTP server, or the SMTP server must be allowed to send mails on behalf of the sender in the from-parameter.
Per portal you can select which SMTP Server you want to use to send e-mail messages from.
The list of available SMTP Servers is managed on Workspace Level (or in DevOps portal for Kubernetes Runtimes).
Go to Manage Projects & Workspaces.
On the specific Workspace, access the context-menu [...] and select SMTP Settings.
On the overlay for SMTP Servers, add or edit an entry.
Parameters to set, are:
Host (smtp server hostname, like smtp.gmail.com or smtp.office365.com).
Port (587 is the standard for secure SMTP via TLS).
Username (the account that can connect to the server and has sufficient rights to send messages on behalf of the from-address you want to use in your project's emails).
Password for that username to access the SMTP server.
After one or more SMTP server profiles have been set up, you can pick one on the Portal Settings to be used specifically for sending out E-mail messages using the Email Process Node.
It is possible to use a (free) Gmail account that you own, as SMTP server.
https://support.google.com/a/answer/176600?hl=en
If you want to use IP-whitelisting on your SMTP-server, or use an Exchange Connector to allow incoming SMTP traffic from your WEM Application, you may need to know the IP-address for the WEM Server that sends out the SMTP traffic.
For portals running in EUR zone, use [185.3.209.154] as the IP-address from which WEM is sending the emails.
For portals running in APAC zone, the outbound mail will come from [52.189.211.222].
The account-username to be used in the WEM SMTP Profile must be an active account in Office365 - you may need to specifically login to Office365 with this account as Microsoft may require this for accounts to be activated and checked with additional information - also check Multi-Factor settings that may cause issues when an application acts as non-interactive-user. This account may be setup as a non-personal account (like smtpsender@yourdomain.com).
The Office365 Account must have a valid office license with a mailbox (so you can also see the Sent Items there and useful info like non-delivery-reports).
The Office365 Account has permissions or aliases to send on behalf of all the addresses used in the FROM parameter of the email nodes in your application (like noreply@yourdomain.com).
The Office365 Account must be setup using MFA and an App Password must be created. This App Password must be used in the WEM SMTP Profile Settings. This is necessary to work around the required Multi Factor Authentication and to enable another application like your WEM Runtime Portal to login to Office365 bypassing the MFA.
Read this link from Microsoft about how to set up App Password.
Click the [Settings] button in the top menu to access all Project and Portal settings.
A Portal is the entity that can be considered the Application, defining the look & feel and the hostname where it can be accessed.
As mentioned in #workspaces-projects-and-portals, a Project can have multiple Portals. But must have at least one, so when creating any project, a Default portal is automatically created for you.
In this Summary block, you can see the following information:
Name and type of the Portal: "Default" and Website;
Home page: the starting point of the portal, defined by a specific Navigation Point which is linked to a specific Flowchart; [click] to change to a different item, or [Ctrl+Click] to locate in tree;
Design Template: the selected design template that defines how the portal will look; [click] to change the selected Template or to change the specific Template Configuration
Default Language; [click] to change the Language Settings;
Timezone setting; [click] to change;
SMTP Mail Sending Server Setting; [click] to change; You will get a list of available SMTP Servers to use for sending mail - these SMTP Server Profiles need to be setup in Workspace or DevOps Portal.
Staging information: date+time last published and the configured hostnames; [click] to change;
Live information: date+time last published and the configured hostnames; [click] to change;
Basic Portal Settings is where you can change the Name of the Portal to something more meaningful than Default.
The Home page is the Navigation item that points to the flowchart that has to be executed when a user first accesses the portal (by hostname). The Home-Navigation Item and the Home Flowchart are automatically created and set as starting point for any new created project. You do have to add at least some nodes to the Home flow (at creation it only gets a start-node).
Read this forumpost for information about the accessibility of the Home page navigation item.
The Design Template is the definition for how your application will look. It defines the base setup for all your pages in the project, generating the necessary HTML that browsers need to present the results to the user. The Design Template defines certain standard "containers" - blocks where standard elements like the Menu's go, what the main container is where all your own Interaction Templates will be put, the standard styling for all elements, fonts and colors.
Any WEM Design Template may support and provide specific setting-properties which you can provide custom values for in the Design Template Settings overlay.
If the available collection of Design Templates does not fit your needs, there are possibilities to get your own Custom Design Template. A WEM Design Template is a complex collection of files and definitions that have to be put together correctly. If you want to manage your own Design Templates, you need to have profound knowledge of LESS, CSS, HTML at least - but there are WEM Partners who can assist if you do not have this knowledge available.
For licensed customers with proper experience, WEM provides a specific tool to create and synchronize your own WEM Master Templates: WMT Design Tool
WEM supports multiple languages. On the Project level you can define which languages you want to be enabled. Thereafter, on each Portal you indicate which of those languages is the Default language. Just select one from the available languages, or click the gear-button next to it to add more. You will see an example of the formatting for numbers, dates and times that the selected language will use when presenting these types of fields.
Then, you select an option for the strategy: should the default language always be used, do you want to follow the user's browser-settings regarding the language, or do you want to let the user actively select the language? For the latter scenario, a dropdown with all available languages (as set on project level) will be displayed in the top-row of each page.
There are other options available to allow the user change a language, or you can even allow users select a language and store it into a preferences profile. You can manage (check and set) the selected language using the appropriate process-nodes.
There are three ways to determine the time zone for end-users:
Working with the WEM Modeler is free of charge, you can create an account and start getting to learn WEM and all its features without costs (just your time). You can also start your project in Preview, to test how it will work out for end-users.
When you want to publish your project to Staging or Live, to make your application available to your targeted end-users, you will need a License Key. This License Key is obtainable via WEM Partners or WEM HQ when an official business license has been agreed upon. Click here for the Main WEM License options, and fill in the form on that page to contact WEM for detailed options and prices.
Hostnames are the addresses by which your application (Portal) can be accessed. Read some info about hostnames.
There is a specific post on the WEM Forum about this feature, as well as a specific documentation page.
This information is important, so please read and understand it to be able to configure hostnames correctly. In the Hostname Configuration page, the documentation is also linked, so you can access it easily when you need it the most.
On the Hostname Configuration, you can see the option [Force https]. If you enable this option, the portal will force each request to run with https (secure, encrypted using SSL/TLS). We do suggest to use this option, but you do need to activate this setting yourself.
For the option [Force https] to work, there needs to be a valid SSL certificate in place for the hostname of the portal. When the hostname is part of the wem.io domain (*.staging.wem.io or *.live.wem.io), it works immediately because those hostnames are automatically covered by our wildcard certificates. But if you use a custom hostname, it is recommended that you first take care of the CNAME DNS setting (as described in the forum post), then go to MyWEM Support and use the [Request SSL Certificate] button to start a request for SSL certificate for your hostname. WEM uses the free LetsEncrypt Certificates, and after initial setup, this certificate will automatically renew each 3 months.
Portals can run under multiple hostnames: they are just different addresses pointing to the same application. This is useful when you want to develop and publish early using the wem.io hostnames, and only when you are ready and have a custom hostname properly set up, add that hostname and start using the new hostname. Another practical use for multiple hostnames, is to provide one application to several different user-groups and make small differentials based on the hostname that the user uses, with the WEM Environment Function Hostname().
In the Add Hostname dialog we added some useful links to information about DNS and related info.
Sometimes an applications runs into an unexpected situation. For several of these situations you want to specify what needs to happen. You can do this by specifying a particular flowchart to which the application should jump when one of these unexpected situations occur. That may be simply displaying a more user-friendly error message, but could also result in executing some workflow/application functionality.
There are 3 possible Error Handlers for which you can define your own specific flow:
Page Not Found: This can happen when a user tries to access a path that does not exist (for example a miss-typed address in the browser), no navigation item with a backing flowchart can be started > then the standard Page Not Found error will be displayed. OR if the portal has not yet been published and someone tries to access the hostname. This event can be caught and by selecting your own flowchart you can provide your own page and message, or redirect the user to the starting page.
Session Expired: This can happen when a user has been active in your application, but then decides to start doing other things, keeping the browser and the application open. Web Applications are typically "disconnected" applications, and sessions are kept alive by sending messages back-and-forth (request from user to server, response from server back to user). When at some point - after the Session Timeout Value has been reached - the server does not receive another follow-up request from the user, the session is regarded as no longer active and will be discarded and disconnected by the server to free up resources for other requests. This may also be regarded as a Security Risk (if users leave their browsers open and computer active and unlocked, other people may dive in). We have a forum post about the Session Timeout Setting, read about it here. In conclusion, when this situation occurs, you can catch this using the Session Expired error handler. For example by redirect the user to the login page, or show a friendly message as to why the application is no longer active.
Unauthorized:
Some elements in WEM have the property [Visible When] / [Allow Access When], for example on navigation items and files. When an item that a user is trying to access, is not visible or available, the Unauthorized situation is triggered, and you can use this custom error handler to determine what should happen (for example, send a mail to administrator to let it be known that unauthorized access was triggered - or just show your own friendly message). This Unauthorized flow can also be used manually in your flows, when you do your own custom check on access.
Whenever a value in these Project- or Portal-Settings has been changed, you need to publish the project, in order to get the changes available in the Staging and Live runtimes.
The Publish Process will be described further down... Publishing Process
WEM allows you to manage several kinds of Security Certificates in your project. These are certificates you typically use to either authenticate your portal to an external service, or to define whose certificates you trust and allow to access your portal.
Client Certificates: These are certificates you use to authenticate your portal to an external service. This certificate must be provided (uploaded or by using the self-signed option) including the private key, because that is the part that makes sure that the external party (who only gets the public part) can be sure that you are who you say you are.
Server Certificates: These are certificates again including the private key, which are used on a server level to indicate that the server providing the Portal can be trusted. This is also typically used when you use a Client Certificate that is provided or signed by a different server or authentication provider that may not be a global trusted Certificate Authority - in that case, providing that specific certificate including the private key, makes sure that when you use the Client Certificate - the external party can trust that Certificate because the server certificate is also provided with private key - indicating that you are you you say you are.
Trusted Clients: These are the certificates that contain only the public part of external clients, that you choose to trust, for example when they access your custom endpoints or webservices that you can make secured using Client Certificates. The external clients that you want to trust and give access, should provide the public parts of their certificates to you so you can add them to your Project. When these clients then access the endpoint of your portal that is secured with certificates, they need to use their certificate (wiprivate key) to sign the request.
Trusted Servers: These Trusted Server certificates hold the public parts of certificates that may be part of the Certificate Chain of a Trusted Client Certificate - and they also need to be trusted if they are "custom" (not on global trust lists). These are typically certificates that are used as Certificate Authority or Intermediate. In the case when a Trusted Client Certificate uses Custom Certificates in its Chain, it can only be fully trusted if all certificates in the chain are added to the Trusted Servers.
WEM offers a way to allow or deny access to your project based on the IP-address of the client trying to gain access. This is also known as Whitelisting (allow specific IP addresses) or Blacklisting (block specific IP addresses).
Each rule is checked in the order as displayed. If the order needs to be changed, select a row by clicking the left-most edge of the row and see it highlighted or indicated, then use the Move Up or Move Down buttons in the toolbar.
Each rule has the following properties:
Action: either allow or deny;
Name: the name you give the rule to identify it;
Start IP address: the starting IP-address of a possible range;
End IP address: the ending IP-address of a possible range;
if both Start and End IP are the same, that indicates that one specific IP address;
Ranges should have the same first segments and only differ in the last segment to make a correct range;
Portal: you can define for which specific portal this rule must be checked, or apply it to all portals;
Runtimes: you can define for which Runtime environments this rule must be checked: preview/staging/live, or apply it to all runtimes;
Endpoint: you can define for which Endpoint this rule must be checked: OData service endpoints, Webservice endpoints, or WEM (normal portal usage via browser).
If you want to have rules applied properly, and only the rules that you have defined, you need to add a final rule to close:
Use the Allow all remaining connections if you are using a Blacklist approach - all other rules before this one are Deny-rules.
Use the Deny all remaining connections if you are using a Whitelist approach - all other rules before this one are Allow-rules;
When these rules are set up or changed, you need to Publish the project to the targeted Runtimes for the rules to come in effect. These rules will then be applied just before the portal is actually reached.
There is also another option to specifically check the IP-address of the user trying to access your portal. In case you want to do something even more finegrained: use the function IpAddress() in an expression. The value will be something like "123.12.12.125" in text form, so you can use any available text-based comparison function to decide what to do.
WEM provides integration according to the OData Protocol. This way, any data that you have in staging or live runtime environment, can be made available to external applications that are able to retrieve data using OData, like Excel or BI tools. The WEM OData Logins security settings allow you to specifically define which data can be accessed with certain logins and what they can do.
You start by creating a username and password. NOTE: the password is encrypted and not retrievable, so make sure you store it somewhere safe!
Next, you specify on which portal the access should be granted (any specific portal, or all portals).
Finally you define to which resources this login has access and which actions are allowed:
This is the place to change your project's name.
The Project Variables section allows you to define your own Setting fields. Then, within each Portal you can give this Setting its own Portal-related value.
The Value you give Setting fields for each portal, can be retrieved in the logic of your project using an expression with the function Setting("fieldname"), which at that point will yield the value for the active portal.
TIP: The project variables are text-only and usages can not be found easily.
With the introduction of Calculated Fields it is better to use that option for settings, because then you can use specifically typed fields (text, date-time, numeric etc) and with Find Usages see where they are used. Use the expression-function PortalId() to distinguish settings per portal and use a default value for all portals that are not specifically mentioned.
So in a way a Project Variable is a variable setting you can define yourself, to hold a value per portal within the project. Its type is always text, and its value is read-only within the logic of the project.
To remove a Project Variable (and all its Portal-level values), click to the left edge of the item to select it and make [x Delete] button becomes available. Then click on the [x Delete] button to remove the project variable.
Portals within a project can either share the data (in the Runtime) or have each their own separated storage.
If the various portals in a project all need their own data and/or prevent users from the other portals to access the data (like with a multi-tenant solution), you should choose to separate the databases (each portal its own storage). On the other hand, if the users of the various portals can or even must share the data, you share the database (this is the default setting when creating a new project).
NOTE: you can only specify the storage strategy (shared or separate), at the time when you create the project or shortly thereafter.
This setting cannot be changed once the project is previewed or published - because either of those actions will create the database container based on the chosen strategy - and, once the container has been created, it cannot be changed.
Here you can add and manage languages to be available in your project.
An overlay shows the languages already in your project and a button to add more.
Clicking [+ Add Language] shows another screen with a dropdown of available languages and a formatting example of the selected option.
If you hover over an already available language, an [x] button appears on the right. Click that [x] to remove the language from the list of available languages.
This part allows you to make changes to certain Project Features. This is introduced to support specific features available to WEM Kubernetes Runtimes (mostly Private Clouds), but which are not yet available on the standard shared clouds for EUR and APAC - also known as Legacy Features.
When you create navigation items, a path will be created using the name of the navigation item that will be added to the staging and live hostnames, so it can be used as a direct link to that specific navigation item. Navigation Items can be nested to a few levels, and the "old - legacy" way to generate URL Paths is "absolute", where only one path-level was created - a combination of hostname + navigation item name, without using the other levels. The new way, which is also standard for new projects, is to create relative paths, which creates several levels. Changing this setting for old projects (and then publish to Runtimes) may cause previously used links to stop working as their paths may have changed - so be careful when changing this setting.
Kubernetes Runtimes only!
From the beginning, Navigation Items added to the Menus in WEM are generated using HTTP POST requests to work properly with WEM User Sessions. The new Kubernetes-powered WEM Runtime can now also support GET requests for Navigation Items, from within the menus. But - this also requires to activate the new "automatic" Session Folder - as the GET requests need this specific Session Folder to keep connected to the user session.
Kubernetes Runtimes only!
This Session Folder Setting is only available when there is no WEM-Session folder created yet. Once this setting is activated, the Session Folder will be created and that action can not be undone (though you can choose not to put fields into that folder). This Project Feature will not be visible anymore when the Session Folder is created.
If your project already has a folder with the same name ("Session") - this folder will either be renamed to "Session Version" or you will be presented with a warning and asked to change its name.
The technical workings of this Session Folder is explained in more detail on the following page:
Query string parameters are name+value pairs added to the URL (https://en.wikipedia.org/wiki/URL) in the browser address bar (or to a link you click on) after the questionmark [?] indicating the end of the path and the start of the parameters. Check this wiki for information.
Let's look at this URL:
http://yourportal.live.wem.io/queryparam?uid=admin&action=resetpw
This URL contains two parameters: uid and action. The values are associated (passed) with the parameters you may want to use in your project.
Using the Project Configuration for Query String Parameters, you can define which parameters your project expects and to which fields in the Project's Data model the values are mapped. These can only be fields of type Text and may not be part of a list (because at the point of mapping from the request, there cannot be an active row on that list to put the values in).
Any parameter that is provided in the URL, but not defined as parameter in the WEM Project, will be ignored.
When the parameters are mapped to fields in the Data model, you can use these fields in your expressions and flows (and be smart to check if they have a value when you do - using the HasValue() function).
Query string Parameters can also be defined on specific Navigation Items (that have a URL-path defined and a deeplink with a flowchart linked) - of course via the context-menu on the navigation item.
The difference between the Parameters on Project level and the Navigation Item level, is that the Parameters on Project level can be used with every path within the Portal. The Parameters defined on a specific Navigation Item will only work when they are combined with the specific path of that navigation item, and then only in the Flowchart linked to this navigation item; not anywhere else.
WEM used to support an old version of Google Analytics. This was the basic version of Google Analytics (not the more advanced AdWords or other features). For information about GA, visit support.google.com. This setting is still available for old projects that have not yet migrated to newer versions.
This implementation for Google Analytics will no longer be supported by Google from July 2024!
A better approach - if you want to support the latest Google Analytics - is to use a Design Template that has the support for the current Google Analytics (or Tag Manager) embedded with a parameterized property for the Google Account ID.
The Design Template Customizable Main has this feature available (it is the only Design Template with this option), so if you use that Design Template, set the Google - Enable Tag Manager option to true (or based on hostname or other situations) and set the Google - Tag ID value accordingly.
If you want to use this feature in your own Custom Design Template, use the WMT tool to get a copy of the Customizable Main template to see the implementation and implement it into your own Custom Template. You will need the correct script to insert from Google, depending on your chosen service from Google Analytics. Use the example in the Customizable Main file mastertemplate.bwmt to see the proper way to make the parameters for the script itself and the Google Account ID.
An example:
This forum document has useful information and some characteristics of a native mobile app.
The WEM modeler supports creating apps for both android and IOS. Making an app in WEM works just like an Web app, with a few different settings and different portals. When creating an app you first give your project a name and select the App as project type, after that you get the localization settings just like with a Web app.
The portal settings are the different for Apps. Instead of one default portal, you start with an Android and an IOS portal which each have their own settings. As with web application settings, the portal actions can be found in the top right corner of the portal settings canvas.
The first one portal action is "Basic settings" for both Android and IOS portals. This allows you to change the portal name and the homepage of the portal. Thereafter, you have the android app settings and the IOS app settings. Here you fill in the Application ID setting, the version setting and the Permissions the app requires.
Both portals have an app icon setting. For Android, a simple PNG picture of your preferred icon sufficient. However, for the IOS icon setting multiple files are required for different sizes of the icon. To add these icons click on the icon size you want to change and a pop up will let you select the file.
The app splash screen is the image that appears when you start up the app. This is a temporary loading screen and does not have any content. You can upload a PNG and choose the background color with hex color codes for both portals.
For now we have one master template per portal (for Android and IOS) with each their own design configuration. Just like web apps you can choose your own design, or a design from the WEM library and personalize it in the design configurations.
Certificates for works a bit different with mobile apps.
To be able to deploy an Apple app you need to create Apple specific certificates and a provisioning profiles in the developer portal of Apple. In this document, you will find a small guide on how to get your IOS app to distribution.
You can only manage your certificates in the security settings not in the web service tab. Mobile apps only support consuming webservices so you will only find those under the webservice tab.
Project variables work just like the web app and allows you to add variables per portal. When you add a variable, the first column represents the android portal and the second one the IOS portal.
The project configuration tab is also where you can configure the languages which your project supports. When you select the languages settings a pop up appears. There you can find the available languages and add more languages to your project.
The Storage strategy allows you to define the database strategy. That is, either all portals use the same database, or each portal has its own database. This setting cannot be changed after the project has been published.
Processes settings for the mobile app is similar to the web app processes settings, and allows you to find process nodes by searching on a process.
Different from the web app project configuration is the absence of Google Analytics, and Query string configuration in the mobile app project settings.
Using the "hamburger menu", you get access to the Portal Context Menu, to change all settings.
Click on the "colour palette" icon to open the list of available Design Templates. WEM provides a range of predefined Design Templates. Each of them has some (or many) additional settings to change to your needs. The[Customizable Main]Design Template is the template with the most options you can set and modify yourself (within limits) and is becoming the most-used template of all.
Use a specific time zone: With this option, you can select one specific time zone from the available list of IANA Standard Time zones; then all times in the application are based on that time zone, and localization to end-users time zone is not useful.
Derive from client IP: This option is the default when new projects are created. With this option selected, the runtime environment will lookup the end-user's time zone based on the IP-address, using a global lookup table with known registered IP-address ranges and their known time zones. You can use the UTC time zone (and related functions) to store specific date+time values, and choose to display them as local time to the end-user based on their time zone. This approach should be used when displaying date+time values for events that are not location-bound (like an online meeting, but not for a local concert at a certain venue - that time is linked to that location specifically).
Use time zone from device: This is only available in Native Mobile Apps and can get the known time zone from the device. With this option you can also work with specific times translated to the user's local time zone.
When a list of Languages is made available in the Project level, you can set the language strategy (default language and how to select) on each portal. In the Multilanguage Dictionary tab, you can add specific labels and translations for each available language. When you remove a language, all translation items in the Dictionary for that language will also be removed.
WEM provides certain special features that perform combined, complex or specific actions by these Processes. In this overlay you can see the list of all available processes, a short description of their purpose, and a button to find their usages. These processes can be used on Flowcharts, using the Process Node. This will be explained in more detail later. The [Send Email] and [Generate PDF document] are probably the most used Processes.
