So this is part 2 of our Getting Integrated Guide but it is sorta actually the beginning. Part 1 was an overview/introduction/table of contents kind of thing, so to see the path of the rabbit hole, check there. Otherwise, read on.
In this installment, we're going to lay the foundation for all the future installments. That seems to be something you do... like when building a house, you tend to not start with the windows or the curtains, but with the foundation. I am sure volumes of metaphors have been written on foundations, about how they are the bedrock of society and that they lay the groundwork for the future and... um where was I going with this... oh yea, integrations. For the next couple of posts, we're going to build out an event integration and we're going to start with a communication plan.
If you want to skip ahead and just see the communication plan we build, I've attached the "BakeryCustomers.zip" file at the bottom of this article.
In our xMatters On Demand application, event integrations leverage our awesome design tools called Communication Plans. Some of you may remember our Muffins Plan from RESTful Debugging the Relaxed Way, and here, we're going to step through building the communication plan used in that article. So my question for you all.... Do you know the muffin man?
Ye Old Tyme Bake Shoppe is a corner bakery that is getting more and more popular and they have engaged the help of xMatters to notify their customers about the awesome muffin creations coming out of their kitchens. For now they are ok with a message panel accessed through the user interface, but in the future will be looking at other ways to kick things off. (hint hint)
I put on my developer hat (the big furry one with blue stripes) and set to work. Actually, developer isn't a great term. Developers tend to deal with code and programming and the like... but for this we just need a good handle on a mouse. No programming or engineering skills or Ph.D needed. For those who like to dig into code, bear with me, we'll get to that later. In this issue, we are going to create a Communication Plan, a Form, some properties for the form and quickly dig into the message design tools. So, without further ado...
I login to xMatters and navigate over to the Developer tab. This is the developer's kitchen. There are two friendly buttons in the upper right, Create Plan and Import Plan. Import Plan allows you to transfer plans from one instance to another and most of our pre built integrations use this feature to quickly get going.
On the other hand, the Create Plan button allows us to create our own plan, so click this button and we are presented with a dialog for entering a name and description. As this is a bakery, let's call it Bakery Customers and add a description below that, then click Create Plan to commit the action.
When plans are created (or imported) they are set to disabled, so check the box to enable the plan. In the bad old days this was true, but after much reflection our engineer types decided that the plan should be enabled when it is first created or loaded.
The Communication Plan is a logical grouping of the Forms. We named this plan "Bakery Customers" to indicate we'll be using the encapsulated forms to interact with the bakery customers. As the bakery matures, we might have an "Incident Management" form to interact with the IT folks or heck, even a form to deal with emergency kitchen appliance issues. If you have any suggestions for other plans for Ye Olde Bake Shoppe, add them to the comments.
The next step is to create a Form. The form will be our point to kick off the messages and as we build out the integration points, will be where we create the Inbound Email Integration and REST web service endpoint. Click the Edit > Forms drop down next to the plan to display the available forms.
Of course, since we just created this plan, there are no forms, so click the Create Form button to display the Create a New Form dialog. Since we're notifying about muffins, let's name this one Muffins Ready and give it a description then click Create Form.
Again, the Form is created in a Not Deployed state, however, this time it isn't as straight forward and just checking the box. We have all these amazing options!! (Such as email!)
Each entry here (except Permissions) is a way to kick off the form. Tic the box next to Enable in Web UI and we'll go over the others in future posts. As long as we're here, click the Sender Permissions entry to view what users and roles can initiate this form. You can grant individual users the ability to access this form or if you have a lot of users, you can grant the ability to an entire role.
Ok, now that we've got all the mundane admin stuff out of the way, it's time to dig into the fun stuff. Along with the list of forms in the plan, you'll notice another tab at the top: Properties. Clicking that will show you a rather blank page. Click the Create Property button to begin creating a property. Instead of just jumping to the property name and description, we are prompted for the "type" of property.
Before we get much further, we have to consider what a property is. Properties allow for users (or integrations!) to input values and have them assigned to a name. In this way we can tell our users that the flavor of the muffin is bashful blueberry or that it contains nuts. Instead of just one big text box, we are going to break these out into individual "fields" which gives us much greater flexibility on the message formats.
So, let's start with Flavor. In the property type dialog, select Text (our bakers can get really creative with the flavors so we don't want to lock them into a pre determined list such as a drop down).
The next dialog asks for more details of the property. Since the flavors can get complicated, let's increase the max size to 200 characters. Click the Create Property to finish up.
If you're following along at home create these other properties, or you can find the answers in the back of the book in the form of the zip file attached to this page.
|Name||Type||Default Value||Drop Down Values|
|Baker's Notes||Text (2000)|
Sweet! Good to go:
Ok, now we've made the Bakery Customers plan aware of the properties, but we have to associate the relevant properties to our Muffin Form. Maybe at some point we'll do a Croissants Ready form and we can reuse some of these properties instead of creating a whole new plan and a bunch of repeated properties. Head back over to the Forms tab and click the Edit > Layout button:
Here is where we build out the, er, layout of the form. As we add and manipulate items on this page, they will become available on our Message Pane. Drag all the properties we just made onto the form, and rearrange so it makes sense and hit Save Changes.
Still with me? We're almost there. The last part is the best part. Click the Messages tab and you'll see three lines, each corresponding to a message format. These are grouped based on how well they display in their archetype. Since our awesome mobile client allows for HTML formatted messages, push message is in with emails, while pagers are in with text message due to their short text constraints. Finally Voice is in a class of its own because there just isn't anything quite like voice.
Click Edit next to Email and you will see a blank canvas, ready to accept our brilliant email template. We get lost in visions of the bakery customers marveling at the artistic array of composition and color and flock to the doors demanding muffins that rival such grace and beauty..... or something like that. Drag some stuff around and set up an image and a table and voila!
I'll leave it up to you to craft your own Text Message and Voice creations. In the meantime, we'll move on and get to testing our plan!
Above, when we tic'd the "Enable in Web UI" box next to our form, it created a messaging panel. This is a direct interface into our form and allows us to kick it off from the user interface. So, click the Messaging tab at the top of the screen and click the "Muffins Ready" link under "Bakery Customers". See how these things are nicely organized? You can imagine larger organizations having more than several of these forms, so having them grouped really helps keep things under control. Notice the layout is just as we put it in the aptly named Layout section:
Thing of beauty, eh? When I enter some details and the "Muffin Customers" group to the recipients and hit Send Message, the details of the latest Baker creation are sent off to our adoring customers via email:
And text message:
Whew. That was intense!
"But wait, this isn't an integration! I am looking to build an integration with xMatters!", you might say.
Yes, I know this isn't probably technically an integration, but we'll need this communication plan to build off of for our first integration. Click the follow link above (make sure you are logged in) to get notified of the next part in this series "Inbound Email Integration (GIG part 3)" where we build out our first integration.
As always, if you have questions or comments leave them below.
Until next time,
Click here for the next installment!