In this demonstration, we will set up an email template along with a MailGun service in DreamFactory. We will then create a limit exceeded event and tie it all together, so that when a limit is hit, the system will fire off an email to our DreamFactory Administrator.
For this example, we are creating a template called, “Limit Exceeded Notification” with the following template Body:
Notice the variables in the template which give us information about the exceeded limit. These variables are available automatically to the script when the event fires. We will be passing these variables to the MailGun service from the script we will create.
Fill out the rest of the information to set up your email template such as your Subject, Recipient Email, etc. and click Save.
This blog will not go into the details of setting up your MailGun service, but for more information, navigate to Sending Email on how to set up an email service. Keep in mind also that you may choose to set up an SMS or other means of notification using the methods in this blog post as well.
Create the Event Script Using V8js
We will create our event script using V8js. The purpose of the event script will be to relay limit information to our MailGun service in order to populate the variables listed there. MailGun will handle the actual notification. The first thing we need to do is to create a payload to POST over to the MailGun service. In Event scripting, the event variable is there to provide you information on the event. You can var_dump(event) at anytime and look at the DreamFactory log file to see all of the information it contains and what information is available to you.
In our payload, we will provide the following. Note that the template variables are the keys and the event information provides the data for our template:
Once we have the payload set up, all we need to do is pass it on via DreamFactory’s internal API to our “my_mailgun" service.
You can create a limit event that fires for each limit that gets exceeded or create one targeting a specific limit. In the Admin App, to see all the limit exceeded events available, navigate to Script -> system -> system.limit.{id}.exceeded.
Notice you have an entry for {id} as well as ones for any specific limits by id. To create an event that fires for all limit exceeded conditions, choose the system.limit.{id}.exceeded (top level) selection. This event will fire for each limit hit:
Every limit you create has a specific event available to it which fires once every time the limit is exceeded. In our example, we have an instance limit covering the entire instance as well as a very specific limit which targets a db service and a user hitting that service.
To see the events bound to these limits, you can make an API GET call to system/event. There is a lot returned here, but find the system.limit.{id}.exceeded entry:
The “id" entries are the ids of the limits we have in the system available for scripting. So, if we wanted to create an event script for our db user limit, the id of the limit would simply fill in between the brackets:
system.limit.36.exceeded
Now that we have a workable script, let’s go ahead and save that script to the system.limit.36.exceeded event in the Scripts tab under system.
For this test, I’ve logged in as the user and set the limit threshold quite low (7 hits). Other ways to test your script would be creating a script service that contains the script itself and then hitting it directly from the API.
Now that the limit has been breached, the script should send an email to the Recipient on the template notifying of the breach.
And there it is! Notice that the variables have all been filled out for us based on the exceeded limit.
Now that you’ve seen limit event scripting in action, you now can see how many options are available to you when you start combining services in this manner. You could choose to not only send an email, but also an SNS to AWS or Push notification to a specific topic. You may want to log an event to a specific log service as well. Building Limit Events in this way gives you the flexibility to do what you need to do with DreamFactory.
Check out the community forum to discuss or let us know what you think in the comments!