Zephyr – a technical deep-dive

There are many things that make Zephyr a great product and one of them is that Zephyr is user friendly – if you are not sure about this statement you should try following the 4 step guide below for easy automation of service requests! But first some basic concepts.

Service Requests in Zephyr

The very foundation of requests in Zephyr is built around Forms. A form is a collection of information and elements, that you fill in and request. The data from the form, directly from the user, or added automatically through other integrations, creates a Request which is essentially a workflow with different states which is run in the Zephyr backend. The states can perform different actions and through them collect more data, integrate the data in external APIs or systems, send mail or perform request approvals.

Everything a user does in Zephyr is considered a Request, and they all are tracked and retained in the tenant’s database.
With this toolbox, you can create a catalog of appealing self-service interfaces for an organization’s users every service need. You can highlight them on the front page, you can group them with tags, and they can search for them.

Zephyr doesn’t stop on the consumer side of your service catalog. We’re growing the catalogue of out-of-the box services to configure for your environment, and you can create your own automation of every Request through custom code in our backend or on premise.

A typical Request timeline, as shown in the user’s Requests view

Automated service requests in four easy steps

For this section, which requires Admin access in your Zephyr tenant, and that you are your own approver (or have approvals turned off for the relevant requests types), we’re going to look at creating a service from user form to the actual automation in just four steps. Can it be that easy?

Let’s start with how you create a form, then proceed to make it smarter, write some custom automation code that uses form data, and finally stitch it all together and run it.

A basic Form

First, start administering your tenant by opening the administrator menu from the cogwheel button in the top bar menu. This menu is where all configuration options for a Zephyr tenant can be accessed.

To set up a Form, click on Forms, and the page that loads is the overview page for all Forms. You might not have anything there in the list, but there is a Create button – Click it! In the right hand panel that appears you have the choice of cloning an existing form, or create a New.

The creation has a lot of options, and may look daunting, but let’s go through it nice and easy:

The first part is called Settings, and it’s where you set name, description, tags, image and so on for the service you are creating a form for. There are other more technical bits further down that we will return to later. Go ahead and give your service a Name. You’ll notice that most options open a side bar on the right that allow further options, for instance adding names in different languages.

The next part is where the fun is – elements! You add elements by clicking the buttons, or dragging them to the right place in the form. You can group elements into Steps, which act as pages in the service request. Go ahead and add as many as you want, and play around with the different types and their options. You can go to the Preview part to see how it will look like to the end user. For this walk-through, I’ll just add a couple of elements:

I’ve added two steps, the first with a textbox for IP address, and a dropdown list of countries with name value pairs like “Sweden – Sweden” and “Norway – Norway” (you will probably want to add the one for your country, keep the value in that option in English for now), and the other with a text area for adding a message.

That’s it for your first form! Go ahead and submit it in the Summary step. You can click the link to the Form creation Request to follow the process in real time, but it should only take a couple of seconds. Then you can see the form in its full glory, for example by searching for it by clicking the magnifying glass icon in the top bar menu, and entering a part of the name. Try it out and see what you get!

Smarter forms

Now this form doesn’t do that much, and let’s make our form a bit smarter and make life easier for our users – it’s tedious having to enter your IP address, when the computer knows it already, right?

So go back to editing your form, and go to the Generators step, it looks a bit like the elements step, but now you’re adding generators. What are those? A generator is a function that operates on form elements. It can among other things set the value, use the value or set visibility of elements. And it does so either through a implementation in the form, or through Hooks in the Zephyr backend (more about those later). A generator has input and output elements, and as soon as any of the inputs change the generator runs and sets the generated value (or visibility) to its output elements.
For this example, we’re going to add a HTTP generator – so click that button and it should add to the list, much like this (with the edit side bar open):

In the Settings modal in the edit side bar, add the following URL: https://api.ipify.org/?format=raw and the Method GET, and set the IP Address question as Output. This is just a publicly available API as an example, but feel free to use your own, as long as it’s SSL encrypted (starts with https).
In the preview you should now get your IP populated – now that’s smart right? Submit the changes to your form and enjoy!

Let’s hook it up

Now it’s time to start automating this service! As you’ve seen you get quite a few mails when you create and change forms and so on, and emails are the most basic form of automation in Zephyr. This means that with a simple click you can have Zephyr send the results of a form to any email address. This is available in the Forms editor settings part. But for now let’s look at what kind of automation you can create in Zephyr by other means, we call them Hooks.

Like with Forms, just go to Hooks in the administrator menu, and click Create.

You can give Hooks a Name and other properties, but for now let’s limit ourselves to setting it as a System Hook, and adding Inputs. For this example, they should match the ID of the elements we want to use from the forms.

In the next section, the Scripts, you can start writing your own code. As a courtesy I’ll provide an example below, but you can use Roslyn C#, PowerShell (with a limited function set), or run the scripts on your own server using an Azure Relay.

Let’s say I have an Azure Automation runbook that I’ve set up with a webhook (not covered here). It could be a task where I manage a virtual server or create an Azure AD user, but the important thing is that it’s an API call, that I can just make (if I have the right key in the call etc). In Zephyr I can just add the script to make that call, like so (with PowerShell):

param($Inputs)
$r=Invoke-WebRequest -Uri https://s9events.azure-automation.net/webhooks?token=7zxgXXXXWGSwXXXXBVnjXXXXqjX9XXXXrXTiXXXXBzI%3d -Method Post -Body “{‘message’:’$($Inputs.message)’, ‘ip’:’$($Inputs.ip)’}” -UseBasicParsing

$s = “Job ID: ” + ($r.Content | ConvertFrom-Json).JobIds[0]

$s

 Now what are these cryptic bits? Well if you’re not familiar with PowerShell, just look at the blue part and understand that it makes a web call to the address starting with https:// (which you would get from your Azure Automation setup). Inside the body of that call are the Hook Inputs. The other parts after it are basically formatting for getting something nicer looking back for showing in the Zephyr logs. The main takeaway here is that basically any API is consumable with a method like this.

Go ahead and Test run if you’ve done the Azure bits (or use another API), and submit when you’re happy with the results.

Go with the flow

Now let’s put all this together. First you can go to your Form and set the Hook you just created to be run on request completion, you do this in the lower part of the Settings section.

Set the activation switch to on, and that should be it! If you Submit the change, and request the service with the form, you should get a result, maybe something like this (from the Azure Automation Job output console):

Webhook = @{WebhookName=message; RequestBody={‘message’:’This is an epic message!’,’ip’: ‘1.22.33.44’}; RequestHeader=}

WebhookDataBody = {‘message’:’This is an epic message!’,’ip’:’1.22.33.44′}

This is an epic message!

Now, we could probably stop there, but we haven’t looked at State flows yet, and we should. As it is now, all users that want to send the message will have their request going through an approval (which is default), so let’s take this away for this form.

Go to State flows from the administrator menu, and have a go at cloning the Request form flow by clicking Create, then choosing it as the one to copy in the side bar, and finally Copy.

All states in the flow are in the list in the center, and can be edited by clicking on them and getting a property side bar, as usual. For this exercise what we may want to do is removing the Approval step, so that our users can send the messages freely. So give the stateflow a Name, and click on the Approval step and then at the Remove button at the lower right to remove it. Now to not disrupt the flow, you need to set the Success state of the previous step (“Created”) to the new next one (“Performing hook”).

Have a look around to see how Actions for Hooks and email sending are run and Conditions are set up, you might get more ideas!

Now, it should be ready to save by clicking Submit in the Summary view. To use it in your form, or any subsequent creations, just pick it in the State flow drop down list in the Form settings.

Wrapping up

That’s it – four easy steps I told you! This might seem complicated, but try it and see for yourselves, and it might be that you figure out something else to try! To summarize, what we’ve actually been doing:

• Created a Service Request Form with form elements that collect user provided data
• Added automation to the form to fill in a field automatically, before the user submits the request
• Added backend automation for request fulfilment without manual interaction
• Adjusted the backend process and approval configuration for this service request

Keep posted for other walk throughs and info about Zephyr, and as exercise until the next time: Why don’t you try and see if you can get the Country Element populated automatically?

*Spoiler Hint* A Hook might be able to turn an IP into a country with for example this API call (use a real IP at the end): https://www.iplocate.io/api/lookup/11.22.33.44