Getting Started with SBM Composer

Getting Started with SBM Composer


Composer is the visual designer for Serena Business Manager you use to define the data and workflows automated by SBM. In this blog post we'll step through the creation of a simple process app, demonstrating and discussing various aspects of the Composer as we go. While there will be plenty of subjects not covered, following the steps outlined in this post should give you a good start on understanding how to design workflows using SBM Composer.

Getting Started

Almost all businesses use workflows. To those of us in software development at Serena, our primary workflow involves the software development life cycle, from managing defects to coordinating releases.  Other workflows that touch us involve finance legal and HR. 

Your first step is to identify the workflow you'd like to automate. Think about processes in your company that involve some item of work that moves between people. Your goal will be to create an SBM process that guides the people in your organization through this process and collects information along the way.

For this blog, we'll demonstrate the creation of an application for tracking vacation requests and approvals.

Note: See Employee Time Off for an example of a full fledged process app for this purpose.

Creating a Process App

To create a new Process App, launch Composer, then click on the New... item on the FILE menu:


This brings up the Create New Process App dialog box:

Select Application Process App and click Create to get started. This brings up another dialog to enter the basic information you need for a process app. Enter Employee Time Off for the process app and application names. Change the tab name to Time Off. Click OK to create the process app. Now we're ready to start designing the process.

Define the Workflow

Think about what the steps of your workflow are, who's responsible for each step, what decisions they need to make and what decisions the workflow itself can make. Once you have an idea of these things, you are ready to start designing your workflow.

For time off requests, the basic idea is that an employee enters a time off request, it gets approved or rejected, then if the time has been taken, the payroll manager updates the payroll system to reflect the time off. Of course, there are some complexities, but this gives us enough to start designing the workflow. We can add change and cancellation requests, additional approval states and other refinements later. As we identify the need, we'll add fields to store information on the item representing the time off request.

Design the Workflow

Now open the Application Workflow Editor in Composer by clicking on Employee Time Off  under the Application Workflows  entry in the Workflow Design navigation pane on the left of Composer. The editor is pre-populated with a submit transition, a new state and update and delete transitions.

Add States and Transitions

Click on the New state, open the property editor General tab at the bottom of the screen and change the name to Awaiting Approval. Now drag a state from the Workflow Palette on the right edge of the application and drop it to the right of the Awaiting Approval state. Drag a transition from the palette, drop it on the Awaiting Approval state, then move your mouse to the state you just added and click to connect the states. Select the transition and rename it to Approve. Now select the state and rename it Approved. Add one more state and transition, and name the transition Leave Taken and name the state Audit. Your workflow should now look something like this:

Each transition in the workflow allows the user to enter or modify data in the request. The states represent locations where the request waits while something happens outside the system.

Note: Process app developers typically deploy the application throughout its development to iteratively test what they've created. To deploy the application you'll need to connect to the Application Repository.  You do this by opening the SBM Composer Options dialog (FILE->Settings) and choosing the Repository tab. Enter the machine name and port, along with your login credentials and select the Work online option.

Now choose the DEPLOYMENT tab in the ribbon and click the Quick Deploy button to send your design to the server where it can be tested. Once deployment is complete, you can click on the User Workspace button to launch your browser and submit an item into the workflow for testing.


Notice that each state is labeled as having (no owner). That means we haven't identified who is responsible for the request in each of the states. In our case, we have three different roles involved; a manager (who approves the leave), the employee (who submitted the request and will tell the system that the leave has been taken) and the payroll manager (who will record the leave taken in the company's back end system.)  We'd like these folks to own the request in the Awaiting Approval, Approved and Audit steps, respectively. In SBM the owner of a state is determined by an associated User field in the request. We'll use the Owner Wizard to create a field for the states.

Select the Awaiting Approval state and click on the Owner drop down list box on the General tab of the property editor. Pick the item:

 to bring up the Add Owner wizard. After the introductory page, we see:

We'd like the users who can own the Awaiting Approval state to be in a manager role, and we don't have one yet, so fill out a name and description and click Add role to create and select the role. Then click Next > to get to the page for creating a field to hold the approving manager:

After clicking Finish, we will have created a role for managers, used that role to create a user field restricted to managers and associated that user field with the Awaiting Approval state.

For the Approved state, we need a field to hold the name of the submitting employee, so we run the wizard to create an Employee role and field. Finally, for the Audit state, we create a Payroll Manager role and field for that. Our workflow now looks like this:

Add Branches to the Workflow

As designed this workflow isn't terribly useful, for example because the manager has no choice but to approve it. At this point, we'll add some new transitions and states to flesh out the workflow. We'll also add some secondary owners to the states. This allows people other than the owner to process items in those states, for example, for the original submitter to withdraw a vacation request that has been approved. We'll create the following workflow:

This may take you a while, but it's primarily adding the new states and transitions you see on the workflow diagram above and adding owners for the states as we've done above. You'll also want to add the indicated secondary owners. To so this, you'll need to add the system Secondary Owner field to the table so the system can keep track of who else (besides the owner) has special permissions for accessing and transitioning the request. Now, for each state where you'd like a secondary owner, just select the corresponding field in the secondary owner drop down on the General tab of the state property editor.

Now we have a workflow that enables the following actions:

  1. The employee can
    • submit a vacation request
    • modify it prior to approval
    • withdraw the request prior to approval
    • request modification after approval
    • request cancellation after approval
    • notify the system that the leave has been taken
    • view processed and canceled requests
  2. The manager can
    • approve or reject the vacation request
    • approve or reject a request to change the vacation after approval of the request
    • approve or reject a request to cancel the vacation
    • view processed and canceled requests
  3. The payroll manager can
    • indicate that the vacation time has been processed with payroll

However, the astute reader will note that, with this workflow, the employee can also:

  • approve or reject the vacation request
  • approve or reject a request to change the vacation after approval of the request
  • approve or reject a request to cancel the vacation

which is likely not what you'd want. In the next section, we'll address this by restricting who can take various transitions:

Using the Restrict by Role Transition Property

We can easily ensure that only people with a manager role can use a transition using the Restrict by Role property tab on the transition. To so this, select the transition, click on the Restrict by Role tab of the property editor and check the Restrict users who can take this transition to members of specified roles check box. Now just check the roles that you'd like to see and be able to use the transition from the list of roles below. For our purposes, we'll make the following restrictions:

 Transition  Roles
Modify Employee, Manager
Withdraw Employee
Approve Manager
Reject Manager
Request Change Employee
Approve Change Manager
Reject Change Manager
Cancel Vacation Employee
Approve Cancellation Manager
Reject Cancellation Manager
Leave Taken Employee, Manager
Complete Payroll Manager

Now that we've defined the vacation workflow, we're almost there. But there's the question of what information we need to collect along the way. That's the subject of the next section.

Define the Data to Collect

One thing that we haven't addressed is how to define the information collected and acted upon by the participants in the workflow. In this exposition, we've defined the workflow first and we're leaving the data for later. Some people may choose to do the opposite, they may not know what the workflow should look like, but they have requirements that define exactly what data needs to be gathered. SBM Composer supports either approach, as you can easily go back and forth between defining the workflow and the data model (as well as other aspects of the design that we haven't yet discussed). In reality, people find themselves iterating on all aspects of the design.

So what fields do you need to collect for a vacation request?  Here are some ideas:

Field Name  Data Type  Description
 Begin Date  Date/Time Date The day that the employee will start taking time off
 End Date  Date/Time Date The last day that the employee will be taking time off
 Proposed Hours Numeric/Integer The requested number of hours of vacation
 Actual Hours Numeric/Integer The number of hours actually taken
 Final Status Single Selection Whether the request was processed or canceled

We've also defined some user fields as part of the workflow to define ownership.

To create these fields, pick either Data Design or All Items from the navigation area on the left side of Composer, then pick Employee Time Off under the Tables item. Pick fields of the specified data type from the Table Palette on the right and either double click or drag them onto the table to add them to the data model. Rename each to the corresponding name. Set the style for the Date/Time fields to Date only and the style for numeric fields to Integer. For the Final Status field, go to the options tab on the property editor and add values named Canceled and Processed.

Set Required and Read Only Fields in the Workflow

Now that we have our data, we need to make sure it it collected. For example, during the submit transition, when an employee is requesting time off for a vacation, we don't want to let them complete that transition (i.e. submit the form) without entering the start date and the end date for the vacation.

You can set a field as required or read only on the field itself then override that on a workflow or transition level or do the reverse. We'll make the Begin Date and End Date required throughout the workflow, and set them to be read only for the Complete transition.

To set these fields as required, select each in the table editor, then check the Required check box on the Attributes tab of the field's Property Editor. Now open the workflow editor and select the Complete transition. On the Field Overrides tab, select the Begin Date field then check the Override field properties for 'Begin Date' check box, then check the Read only check box. Do the same for the End Date field.

As you test the Process App, you'll also want to set the read only and required properties for the Employee, Manager, Proposed Hours and Actual Hours at various states in the workflow. 

Quick Forms

So far, we haven't defined any forms for the various states and transitions, so they all use automatically generated forms called quick forms. While they are automatically generated, as a designer you do have some control over their appearance and layout.


You can easily see what the quick form will look like using the form preview feature. Right click on a state or transition, then select Preview State Form or Preview Transition Form from the menu. This let's you quickly see how overriding the privilege section of a field changes its location on the quick form.

Field and Table Properties

If you'd like a field to take up a whole row on a quick form, pick the Span entire row on form check box on the Options tab in the field property editor. Choose a Privilege section on the General tab to determine which section the field will appear in on the quick form. If you don't like the default names of the sections, you can change that by selecting the Labels tab of the table property editor. As mentioned above, you can set whether the a field is required or read only by default on transition forms on the Attributes tab of the field property editor.

Workflow, Transition and State Overrides

The section where a field appears in a quick form can be overridden for workflows, transitions and states. So, for example, if you want to hide a field for a certain transition, you can select that transition in the application workflow editor, find the field in the Field Privileges tab of the transition property editor and move it to the hidden section. You can also move the field to a different visible section on a state or transition, for example, to move a field that will typically be set on a transition to the Standard section so it will appear near the top of the form.  You can also reorder the fields within each section by changing the order in the workflow, state or transition field privileges override tab.

Note: You can drag the field, use the Move Up or Move Down context menu, use control-up and control-down keys, or the Move To->[Section Name] context menu to change the section associated with a field. You can also use control-click to multi-pick fields and operate on them in bulk.

To change the required or read-only property of a field on a workflow or transition, pick that field in the Field Overrides tab of the corresponding property editor.

Custom Forms

Once you have your application working as you'd like, you can start adding custom forms to replace the quick forms with highly customized interfaces. If you're using SBM 11.0 or later, you can create a form with auto-sections, which permits you to modify the layout of the sections, add controls, JavaScript and form actions while maintaining the automatic placement and layout of the fields themselves. (See What's new in SBM Composer 11.0: Forms for more details on auto-sections.) Depending on your requirements, you may design custom forms from scratch, base them on the default quick form layout, or use the new auto-sections approach.

In addition to allowing you to design the form layout as you'd like, custom forms provide a variety of benefits:

  • Add controls like the REST Grid widget for integrating with external systems
  • Use form actions for dynamically controlling the behavior of the form using a simple point and click interface
  • Use JavaScript for implementing sophisticated form behaviors

Other Changes to the Design

There are plenty of other things you'll want to do to make this application rich and full. You'll need to flesh out the roles you've created to give the access you'd like. You can add decisions and corresponding rules to enable automatic routing of items in the workflow. You can add swim lanes to the workflow editor to help it better communicate the design. You can explore integrations with other systems using transition actions for calling web services and orchestrations, or using widgets on custom forms for getting just-in-time access to external data. As form extensions become available, you can leverage them for integrating with external systems or controlling form behavior. The Serena Central blogs may provide you with ideas to enable your process app to meet a wide range of requirements.

Administrative Changes After the Application is Deployed

In Composer, you create only a design and it doesn't represent the entire solution. A design has to be portable between environments, so it can't contain environment specific information. A simple example of this is the user. You'll never see user names in Composer, because each environment contains different users and that population can change over time. Similarly, projects, which are created over time are not part of the design process.

Application Administrator is the tool you use for specifying the dynamic administrative information that you can't provide in the design. For example, you use administrator to add users to the system, assign various roles to them and to create and manage projects. In our example, above, by identifying which users are Employees, Managers and Payroll Managers, you control who can take certain transitions and so, who can perform the different functions of the workflow.

If you enjoyed reading this blog entry, please subscribe to my blog by clicking the 'subscribe to updates from author' link below.

Example: Invoking SOAP Services using the SDA Web ...
CM14.2: Pulse Experts: Sonar Qube Analysis

Related Posts


No comments yet

Recent Tweets