Aug
11
Written by:
Michael Washington
8/11/2014 10:39 PM
(This is a guest blog post by Jan Van der Haegen)
Mission statement
Mail customers to confirm a booking, notify superiors of suspicious behavior, alert when a production threshold has been met or an invoice has been created; these kind of requirements are very common in line-of-business applications (LOB apps). Thankfully, there are thousands of code snippets waiting at the other end of a Google Bing search to remind us of the correct C#/VB.Net implementation to send out an email from within our applications. One copy&paste, five minor modifications, one compile and one deploy later, our apps are sending out emails like requested.
There’s one small caveat though: because you hard-code this behavior into your application, you need to change the code, recompile and redeploy each time you want to tweak it.
Have a typo in the body of your email? Write code, recompile, redeploy.
Need to notify your customers of a temporary promotion? Write code, recompile, redeploy, wait for the promotion to end, then write code, recompile and redeploy again.
To avoid these micro-loops in our daily development, we started to wonder if there could be a way where our business rules were not hard-coded, but instead injected into our application dynamically. After some brainstorming sessions, we came up with app-stitch. App-stitch is a Nuget package which you can add to your LightSwitch server application. Once installed (which takes 2 minutes), app-stitch offers a visually simple yet effective designer that allows you to create and modify business rules at runtime. No more code to write, but more importantly: no more compiling and deploying to make tweaks to the business rules in our applications.
In this small tutorial, I’ll use a sample real estate application to demonstrate how to send out an email when a particular new home is listed. The code for this ‘find a home’ sample application can be downloaded here, it is a LightSwitch HTML application with app-stitch pre-installed. We have the app hosted in Azure as well, if you just want to play without downloading the sources.
Once you’ve opened the application and are logged in, you’ll see a “Rules” link in the top left corner, which opens the app-stitch control panel. Keep both tabs open so you can switch between the application and the app-stitch control panel quickly.
Test rule: prevent users from listing new homes
When a Listing is Created or Modified
First off, we’re going to build a rule that prevents users from creating new listings completely. This is just a quick test to see if app-stitch is running correctly and to familiarize ourselves with the app-stitch rules builder. In app-stitch ‘lingo’, the rule we want to build can be summarized as: “when a Listing is Created or Modified, then Stop the action and display: currently not allowed”.
To build this rule, in app-stitch, click the ‘Create new rule’ button on the bottom right.
To start your rule, you have to select the appropriate event to respond to. There are three channels listed: Application Data, Auditing and Timed Events. Each channel bundles related functionality (events, actions, globals, functions, …) Application Data is a channel that is automatically populated with events and actions based on the entities in your LightSwitch application: an event when any entity has been created, modified or deleted, check for a permission, change an entity, look up an entity, … In the app-stitch control panel, click on this Application Data channel to start building our rule.
There are only three entities in this small applications (Listings, Realtors and Pictures), and for each of these entities an event is listed. Since our rule wants to prevent adding a new Listing, select the “Action on Listing”.
Once you have selected any event or action, you’ll always be taken to a page to do some additional configuration. In this case: we need to specify if we want the rule to fire when a Listing is deleted, modified, created or either created or modified. Let’s go with the latter and build a rule when a Listing is either created or modified.
There’s an optional Filter property which you can use to further filter out specific events, but we’ll cover that a bit later. For now, we designed the “when a Listing is Created or Modified” part of our rule and want to add “then Stop the action and display: currently not allowed”. Hit ‘Accept properties’ in the bottom right, so we can chain the right action to this event.
Then prevent the home from being listed
Continue by clicking on ‘Then’, which will show you all channels with available actions.
To stop the user from completing an action, we’ll need the ‘Application Data’ channel again. When you click it, you can see that other possible actions related to your ‘Application Data’ include checking permissions, changing the Listing, creating a new entity or look up an existing entity.
For now, click ‘Stop the action’, then all you’ll need to do is fill in the message to display to the user when the action is stopped, “Currently not allowed” for example.
Finally you can accept the properties (Click ‘Accept properties’ in the bottom right) and finish the rule…
You’ll be prompted to give a description (this helps if you have a lot of rules) and will be taken back to the rules overview, which now lists our “when a Listing is Created or Modified, then Stop the action and display: currently not allowed” rule.
Tab back to the Find a Home application and click the ‘List a home’ button in the bottom right corner. Some sample data will be completed automatically (to speed up this tutorial), but when you try to save, your rule instantly kicks in and…
Besides noting that a rule kicks in instantly, it’s interesting to point out that this rule fired on the server, which means:
- app-stitch will work both for the HTML client and the desktop version. If you have one client now and migrate or add a second client, your business rules are still applied.
- app-stitch will also work if you have a 3rd party client that works directly with the OData source
- your rules will fire if you create a Listing or any other entity directly on the server (using the ServerApplicationContext)as well.
- your rule will fire for every user (Note: app-stitch supports multi-tenancy and building rules for selected users as well, but this is beyond the scope of this article).
Now that we know that app-stitch is working and have some experience with the app-stitch UI, we can get rid of this test rule. Click the big red button next to the rule and confirm you want to remove it.
Tab back to your application, you’ll immediately be able to save your new Listing again.
When a premium property is listed then notify me via mail
When a premium property is listed
After this quick test lap around the app-stitch track, we can focus on some more meaningful business rules. Let’s say you’re a real estate agent looking for a 4 (or more) bedroom house which is rented for less than 1500 USD.
The first part to build this this rule is familiar: in app-stitch, create a new rule, select the ‘Application Data’ channel and have your rule fire when an action happens on Listings, then change the action type to be ‘Created or Modified’.
This time though, we don’t want the rule to fire when just any Listing is added or modified, but only for those premium properties with 4 (or more) bedrooms and a price below 1500 USD.
To do this, we’ll need to filter the events by completing the optional Filter property, this is a ‘linq’ like statement that evaluates to true or false. The filter we’ll want to build should look like: NumberOfBedrooms >= 4 && Price < 1500.
To access the NumberOfBedrooms and Price properties on the Listing, we’ll need to introduce some ‘variables’. For clarification: variables are values that are unknown at design time, but will be replaced by their actual value when the rule fires. Click the ‘+Variable’ button next to the filter. Expand the ‘Listing’ variable and find the Listing’s NumberOfBedrooms property.
When you click on that property, a shortcode will be inserted between {{curly braces}} in the Filter property’s textfield. Complete the filter by adding the ‘>= 4’ manually.
Finally, add ‘&&’ then repeat until your filter is complete
When you tab out of the filter field, you’ll see that these variables are written in pencil, to visualize the fact they’ll be replaced when the rule is executed.
Finally, finish the first part of your event by hitting the ‘Accept properties’ button in the bottom right, and we can move on to sending an email.
Notify me via mail
At the moment, app-stitch comes preinstalled with an SMTP channel (‘Email’). This allows you to send mails using the Simple Mail Transfer Protocol with your own email server, and it includes presets for Microsoft, Google and Yahoo!’s email servers as well. We have full social media channels planned as well, which will allow you to stitch actions to incoming mails, create calendar appointments, send out tweets, and many more.
I’m going to use my outlook.com address to send myself a mail when a home is listed that meets our filter. Click on the ‘Email’ channel, then select the ‘Send an email using Outlook.com’ action, or whatever is appropriate for you.
This action will require the basic email properties: your name, your email and password (which will be securely encrypted with the rest of the rule), a subject and a body.
This body is a rich-formatted one (emails get sent in HTML) so you can go nuts with formatting and colors, and of course use variables (like in any of the fields) by clicking on the ‘+Variable’ button next to the editor…
Finish your rule by clicking ‘Accept properties’, then ‘Finish rule’ until you see the new rule listed in the app-stitch overview.
Tab back to the application and list a new home. If the property has four or more bedrooms and is listed at less than 1500 USD, you’ll see a mail whooshing to the top of your inbox:
In summary: app-stitch makes it easy to send richly formatted mails from within your LightSwitch applications. It is not only faster because you don’t have to write any code, but more importantly: business rules can be created and changed without redeploying the application. For more information, visit us at app-stitch.com or find us on twitter.