Quick start: creating a simple app to order some lunch

What we will do

In this module, we will quickly build a very simple application with BMC Helix Platform - just about the simplest one that touches on all the major elements of this platform. Of course, I'm talking about process, view, and record. The idea here is to help folks get their hands on BMC Helix Innovation Studio to do something useful, without diving into any power features or even real-world use cases. You could consider this exercise like the proverbial "Hello, World!" application inspired by the "C" programming language, although this application will do a bit more than just print out a greeting.

Because this could be your very first experience of BMC Helix Innovation Studio, for this particular exercise only, every step is going to be elaborately spelled out for you to follow. Don't worry, as we get a little further into the tutorial, and as you are presumed to have the hang of using the BMC Helix Innovation Studio designers, the steps in this tutorial will be described in a much less detailed way.

What you will need

In terms of skills, no experience of BMC Helix Platform, or any other development platform for that matter, is required. As mentioned above, you do not need to have consulted documentation for Developing applications, but it will not hurt, and you will certainly want to be able to do that in later modules.

You will need to have access to BMC Helix Innovation Studio, which means there is a sandbox or some other development system available to you.

The problem at hand

Our hypothetical problem today is that managers allow staff to submit lunch orders by email with the understanding that the lunches will be delivered before noon. However, this isn’t tracked anywhere, and there have been employee complaints. The manager is interested in having a record of when each lunch order was delivered. So, the user stories are pretty simple.

As an employee, I want to be able to order lunch in a quick way.
As a manager, I want to be able to know what time lunches are being actually delivered.

We can build a simple application to take care of this. Applications based on BMC Helix Platform are made up of a few different parts. First, we need somewhere to store our lunch orders, we do this via a record definition (that represents every order). Of course, we need a user interface in which users can submit the orders, called views in BMC Helix Platform. In the background we need to define what is called a process to make sure the delivery time is tracked properly.

As you become more familiar with BMC Helix Innovation Studio, the steps in this tutorial will become less detailed in describing exactly where to click and what to type. For this first exercise, this guide will walk through every step in detail of how to do this. Please also refer to the BMC Helix Innovation Studio documentation, as needed, found here.

Create the Application

From the Workspace page, create the new application as described in Developing codeless applications. You can really give the application any name you like (the Developer ID and Application ID are automatically determined by your instance).

That's it. You will now be in the application page for your new application. By default, the Records tab is selected, which is perfect, because that is the type of definition we need to create next.

Your first record definition

Create a new record definition with default fields by clicking the New → Regular Record button in the Records tab of the new workspace. Set the Name to Order right away using the Details pane on the right of the designer.

You might notice that your new record definition contains a few default fields, including Display ID, Last Modified, and so on. Don't worry about too much for now, we won't need all of them. We can add all kinds of additional fields to the Order definition. For now, we will mostly use a few of the default fields, such as ID, Status, and Description.

Status is called a Selection type field, which means that at run-time it has one of a set of enumerated values. We can use this pre-created field to indicate where a particular Order is in terms of its lifecycle. The values created for us automatically aren’t that applicable to something like lunch orders, so we will change the options now. To keep things simple, for now, let’s assume that there are exactly two states that an order can be in: Submitted (the default state), and Delivered (meaning it is fulfilled). Don’t worry – we will add a much more interesting lifecycle for Order later on.

Select Status and Edit the Options as found in the Details pane.

If you remove New from the Status list, then set each option's Name and Integer Value (use 0 and 20 to leave room for more values in the sequence in the future).

Let’s also add one custom Date/Time field called Delivery, using the New Field pulldown button. The idea is that this will be automatically computed to keep track of the date and time the Status field value changes to Delivered in the lunch ordering process.

Save and close the record editor.

We could actually start creating sample Order data right now using the Edit Data feature, but we might as well create a simple view that end-users could use to create and view orders.

You can find out more in Defining record definitions to store and manage data.

Your first View

The view designer is very powerful and flexible, but again, let’s keep our application simple. A single view will be used for submitting new Order records, and listing the existing ones.

Go to the Views tab
Click on New and then Container (this creates an empty view with a flexible layout). You are now in the view designer.
Set the Name as New Order, similar to the way we named our record definition.

Note: you should periodically use the Save button to store your view definition so that you can work on it later in a different browser session if you choose.

This designer has a palette with the available view component types, and a canvas area that is blank, and will allow components to flow vertically. We will drag in two view components to this simple layout.

First, users must specify the order details as follows:

Drag in a Record Editor component for submitting new Order information.
The Name property of this component is optional (it's only useful when you have multiple components of the same type).
Pick the Record Definition Name - this is an easy one, Order, since you only have one right now. This tells the system that this editor will be working with that kind of record.
Switch the Mode from Edit to Create. This tells the system that this editor will only be used to create new Order record Instances, and lets you off the hook for providing the ID of an existing record to edit.
Drag in a Text Area component right into the record editor's drop area, where it says Drop fields from the Palette here.... .
With the text area still selected, the Properties on the right allow you to set the Field Name to Description. Remember that this is your view, so you can give it a more appropriate label within this view if you like, such as Details.
Leave the Value empty - this is only used to initially set the value when the editor is displayed.

Let's add a component that will allow the end users to submit the new Order record.

Drag in an Action Button.
Change the Label from New Button to something appropriate, like Save.
Click on the Add/Remove Actions link so we can specify what this button should do when it is clicked.
1. Drag in Save from Available Actions into the empty Selected Actions list.
2. Use Click to build an expression to bring up the Edit Expression dialog. This is where we configure which component will be saved.
3. From the Available Values tree, unfold the View → Components node to find the Record Editor (Order)marker. Drag this into the Expression for View Component canvas (alternatively, you can click on its small circular + icon). This means that whatever values are in that record editor will be persisted to the database when the button is clicked.
4. Save the actions.

At this point, your view actually functions to create Order records. You could preview this now, but without easily seeing the data you create, it is not very interesting. So to make it more usable, let’s add a component to the canvas that will show the orders you have created. We also need to make sure that it refreshes every time a new Order is added.

Drag a Record Grid component onto the canvas, below the record editor.
As before, select Order as the Record Definition.
Use the Add/Remove Grid Columns link to configure the columns. Set them up however you like - in fact, you could actually stop here). However, here are some suggestions:
1. Add the Delivery date/time field as a column. This could make it easier to test the business logic of the application later on.
2. You can update the Column Header of the Description field to match the label Details in the record editor.
3. You can remove the Display ID and Modified Date columns.
4. Created Date is more useful here; you could give it a simpler label of Submitted; this also has the advantage of matching the initial Status value more closely.
5. As a best practice, get used to also adding the ID field as a column, but turn off the Visible by Default option. You don't really need this now, but when building a "real" application, you very often will.

Preview your view to try out what you have created so far.

Save your view definition
Click Preview
In the browser tab that appears, create some orders by typing into the Details field and clicking Save (you will have to click the small refresh icon just under the Save button to see the newest orders in the Grid).

Note: you will become very familiar with previewing what you are defining. A useful tip is to keep this browser tab around, and instead of using the Preview button every time, simply refresh this browser tab after making changes to the definition.

You can find out more in Defining the user interface through view definitions.

Challenge Yourself

Enhance your View so that the grid is automatically refreshed whenever an new order is placed. See if you can figure out how to do this without any additional instructions... Note that to preview your changes after a save, simply refresh the existing browser tab with the existing preview.

Make your view look a little nicer by adding a Rich Text component at the top and type in some kind of header.
Place your button in a Button Bar component to have more control over layout (like alignment)
Lay out the grid so that it appears to the right of the record editor and Save button.

Set up the modern shell

You have seen how to use Preview to run your view. But how will actual end-users access it? The answer is that every application comes with a built-in landing page and default menu system called the BMC Modern Shell. You can think of it as a special view that every application has. You can and should configure it so that it has a top-level menu link to get to your New Order view. Luckily this is very simple.

From the application page, click on the Navigation link. This brings up the shell in a special view designer.

In the designer, you will see a special Palette of components designed for the shell. Remove the Home menu item from the top level menu bar that is there by default.

Add a new Menu Item and configure it as shown:

Save and close the shell's designer.

Now you can quickly test the application, by clicking on the Visit Deployed Application link on the application page.

This brings up the application, running in the context of your developer account. It's worth noting here that if you want to test as other users, is you very well may later on in order to test notifications, permissions, and so on, you would not use this link but would instead paste the link it generates into a different browser (or another browser window with a different session context - in Google Chrome you can do this by opening a tab in "Incognito Mode").

You can find out more at documentation for configuring the Modern Shell.

Your first Process

Congratulations, you have successfully created an application that creates and displays data. But that's all it does at the moment. How do you get the application to really handle your lunch requests? You need to introduce business logic into the operations; this is often the complicated part of building applications, but the good news is that BMC Helix Platform doesn't expect you to write complicated pieces of code, instead we declare the business process and the system implements it for us.

Think of the process as the engine of your application, you are describing how a request is being handled. In our lunch application. We will do this by describing the business process that you could informally call the lifecycle.

If you would like to read about the process designer first, you consult Defining the application business logic through processes, though these instructions may be sufficient.

Create a new, empty process by clicking on the New button on the Processes tab of the Workspace. By now, you know the drill – give it the Name of Simple Order Lifecycle. You should notice that the process designer has a lot in common with the view designer and you may already feel you know your way around it.

The process we will build will have a very simple flow. All it will do is the following:

Wait for an Order record to have its Status field value changed to Delivered
Update the Delivery field value for that Order to the current date and time.

Before we start building the flow of the process, though, we need to somehow tie this process to Order records (remember that you can have many different processes, working on multiple kinds of data, and triggered by many different kinds of events). For now we will just define an input parameter that represents an order.

Click on Add/Remove Variables in the process Properties (the GENERAL tab). Set up the properties of a new input parameter called Order as shown below (the Variable ID can be left blank).

That’s it. Now, anywhere in your process flow, you can refer to a particular Order and its fields. It also means that when this process is invoked, we will be required to provide a particular Order record as its context.

For the flow itself, we need to create a path between the Start and End event elements that are already in your brand-new process (the End element may be scrolled off to the far right; you can drag it in closer to Start). To keep things very simple for our “Hello World”, all we need to do in this process is two things:

1. Use a User Task to wait for an Order record to have its Status changed to Delivered.
2. Update the Delivery field value for that Order to the current date and time.

As you might guess, this will mean dragging in two activities from the Palette to the canvas, and connecting them with flows. Let’s try it.

First, the User Task. This is a very flexible activity in the process designer, sometimes called the "Swiss Army Knife" of business processes. We will use it here specifically to cause the process to pause until a particular record is updated so that its Completion Criteria are met (specifically, until its Status field's value is changed to Delivered).

Drag in new a new User Task activity and connect the Start element to it. Now select it to configure its properties.

The Label doesn't really matter as long as it is unique. For this simple application, you can put the type of activity into the Label as a prefix to make it easier to understand at a glance.
Make sure you change the Mode from the default of New Record to Existing Record (because we will be waiting for a specific order record instance to change its status).
Now you can select Order as the Record Definition; this exposes two required properties that you will set next.
Configure the Record ID using Click to build an expression.
Use the resulting Edit Expression dialog to pick the ID field of the input Order (be careful not to pick the Display ID field - that is not the right field for working with data in the process designer). You are instructing the activity to wait for some condition about this particular order. Pay attention to the small glyph on the tag with an arrow going into a box - this has the meaning of "input".
To set the Completion Criteria, use its Click here to build an expression. Again using the Edit Expression dialog again, make sure that you first select the Status field from the User Task element itself (unlike the last step, do NOT use the Order input parameter here. Be sure that the glyph has the "bent arrow" glyph - meaning "output" - in front of it, as shown in the following screenshot). The reason for this is that the process needs to read the active status as soon as it changes within the User Task.

Why set it to be "greater than" Submitted instead of "equal to" Delivered? Of course, since we only have two possible states, the behavior will be the same. The difference is that using the inequality gives us more flexibility later on to test for additional status changes without blocking here. After all, this phase is really about still being in Submitted state, and less about being in some other specific state. We will take advantage of this later on.

The business logic now calls for the process to automatically update the Order record's Delivery date field value after it has been delivered. All we have to do is drag in, and configure, an Update Record activity from the Palette (you may have to scroll down to find it), and then connect the flows through to the End element.

Leave the Record Source as Database (this means it will be operating on the persisted record, not just the current transaction), and select the Record Definition Name as Order.

This again exposes Record ID, which you can set to input variable Order → ID field in exactly the same way as the previous step.

Click on Add/Remove Input Map Fields in order to select the fields that will be getting new values from this operation. We only are updating the Delivery field in this case.

All that's left for the Update Record configuration is for you to specify the value, which is the current date and time of process execution. The Edit Expression dialog comes to our rescue again; there is a keyword under the General set of expressions for Current Date and Time. When the process actually runs for an order, this step will execute just after the delivery, and this keyword will essentially timestamp it accordingly.

Before you click Save, be sure there are no errors or warnings in the messages area, and if there are, be sure to correct them before proceeding.

You have now created a useful process to wait for an order to be delivered, then capture the delivery date and time.

Your first Rule

In BMC Helix Platform, you can define all sorts of process definitions, but they do not execute by themselves. This was part of the design intentionally to give you flexibility about decided exactly when a process should be instantiated and run and with what input data. Although there is a REST API that can be used to invoke a process, the easiest and best way to kick one off is usually by creating a rule to tie the record data to the process. This works well because rules naturally are triggered with regard to data transactions, such as when a record is created or updated.

In English, you could say that you would like a rule with the following meaning:
Whenever a new Order record is created, as part of that processing, start an instance of the Simple Order Lifecycle Process.

We specify this as follows:

We relate the rule to the Order record definition.
We specify one of the rule's Trigger conditions as After Create.
We add an action to the rule that performs a Start Process, and pass in its current record context as the Orderparameter that the process is asking for.

Let's try it, step by step.

First, go to the Rules tab of the Workspace.

Click on New.

Now define the rule.

In the rule editor, give the rule a Name, such as Start Order Lifecycle after Create.
Click on Add/Remove Record Definitions and add the Order record definition.
Select the Trigger and select After Create. This will cause the rule to run as soon as a new Order record instance has finished being created.
Drag in and configure the Start Process action.
Note the Order parameter that must be specified. It is there because of the Order input parameter we specified in Simple Order Lifecycle. You must specify the current record context of the rule as the parameter (NOTE: do NOT use the Order information that appears in the Edit Expression dialog; make sure you are passing the Current Record keyword from the General part of the dialog as shown).

As soon as you save your rule, it will be in effect.

You can get more information about rules here.

Try it out!

You may have already noticed that we have not yet created any view to update the status of an order to Delivered. Here’s how to demonstrate that it is working…

Launch the application by clicking on the Visit Deployed Application link in the application main page (if you have already launched it from earlier, just refresh the browser tab instead).

Submit a new order. The grid should show it with Delivery as blank.

Back in BMC Helix Innovation Studio, go to the Processes tab, and click the Manage Processes button.

Select the Simple Order Lifecycle process
There should be an active instance of this process for every Order submitted since you created the rule that triggers it.
Drill down on that instance’s Context Key in order to see the runtime diagram. It should show the User Task: Wait for Delivery activity as the current one.

In a different (or the same) browser window, go to the Records tab, select the check-box for Order (not the link), and click on Edit Data.

Using the built-in Data Editor, open your latest Order record (the one the process is waiting for) and change the Status value to Delivered (do not change the Delivery date field value, the process will do that for you).

Now back in the Manage Process diagram, refresh the diagram. It should now show the process instance has run through the Update Record: Set Delivery to Now activity and is now complete.

Refresh the application (or even just the record grid of submitted orders). You should now see the delivery time to be current as of when you updated the order.

What we learned

Voila! You have now created a complete working application, though not a particularly complex one. Along the way you have discovered a lot of fundamental capabilities of BMC Helix Innovation Studio, including:

Record, View, Process, and Rule designers
Previewing views
Managing processes
Using the built-in data editor
The documentation for developing applications

Of course, a real application will typically need much more, including being able to use foundational shared data, managing data relationships, access permissions, complex views, error handling, sophisticated process logic, leveraging custom Java and Javascript code, just to name a few. Perhaps more importantly, as you start to support more “real world” requirements, you will need to know the best practices for identifying just how to pull all of these things together. There’s a lot to learn, but the good news is that this tutorial will take us through all of these aspects. You have a great start now in understanding the basic patterns of how BMC Helix Innovation Studio works and that it is safe to explore and build your own very flexible workflow-driven applications.