Open

Contents

Overview

The purpose of this document is to provide standards and guidelines for creating new demo assets to share with the rest of the department. By implementing these standards to processes, engineers and other stakeholders in this company should be able to easily find and understand our library of assets. Every asset created by the sales engineering department should be clearly labeled and designed so that anyone internally and externally understands the context and use case demonstrated by any asset.

Users

Process Designers/Architects

Everyone in the department should have their own user in an environment where they are creating or editing assets. This allows all team members to refer to the correct person when asking about a process they need to edit or demo in the future. If everyone logs in as the administrator, then there is no insight into who created an asset or who made changes to an existing asset in the version log.

Participants (Dummy Users)

Participants in the process should have generic usernames (ex: “applicant” and “reviewer”) and should just be a fake name without any relation to popular media (ex. “Abby Applicant” and “Ricky Reviewer”). All email addresses for dummy users should be se+[username]@processmaker.com (ex. “se+applicant@processmaker.com” and “se+reviewer@processmaker.com”). Passwords for all dummy users should be “Password123”.

Processes

When creating a new demo asset, it is important to map the process as if you are going to show it to a customer. That means the workflow needs to be concise, easy to follow, and clearly labeled. Think about having to explain the workflow to your grandmother or grandfather; the process map should allow someone who is not technically savvy or knowledgable about BPMN to follow along (“grandpa-proof”). This also helps other team members understand what the objective of the process is should they have to demo it on the fly.

Creating a New Process

Naming conventions for processes

When naming a new process, it is important to give it a descriptive name so that anyone reading the name gets a general sense of what the process does. If the process was built to showcase a specific feature without context, name the process after the feature it is showcasing. Do not include company names in the process name.

When naming a process that is specifically used as a sub-process for a parent process, include the name of the parent process in the name of the sub-process. For example: Student Services Portal - Counseling Request.

Writing a process description

Process descriptions should briefly describe the context and actors in the process to give the reader a better understanding of the context and use case that the process covers.

Categorizing a process

The categories applied to a process should include the features that the process showcases, the stakeholders included in the process (if relevant), the industry or department that uses the process, and the name of the parent process (if the process is a sub-process).

For example, a loan application might be included in the following categories:

• Banking

• Loans (if there are more than one type of loan process in the instance)

• External users (when there are tasks that do not require user login)

• Business rules (if the process is routed based on various conditions aka business rules)

If you think a process is a good showcase of a feature or industry-specific need, include categories that would make the process easily searchable according to those properties.

Process Model Design

Every process should be designed such that if a customer were to request to see the map, no changes would be necessary to make the map more neat and presentable for the customer. All elements should be properly labeled, and all outgoing conditional sequence flows after gateways should be labeled according to the outcome.

All process maps should include:

• Pools around each process depicted on the map, labeled with the name of the process.

• Lanes within each pool that represent the stakeholders or phases in the process.

• Clearly labeled events and gateways

• An end event depicting each end state

• Tasks should be named with a verb then an object. For example: Review Application, Fill Out Loan Application.

Here is an example of a process that follows these standards. Sometimes, you won’t be able to put each task in its correct lane due to the placement of the sequence flows - just use your best judgment.

Open

Process Versioning

If changes are made to an existing asset that the logged-in user did not create, then add a name and description to the version created after all the changes have been made. The version name should describe the changes made, and the version description should include details about the changes made to the model.

Screens

Screen design is crucial when it comes to building workflows. How each screen looks should reflect the power of the platform and has huge implications for user experience. User interface design for demos should be production-worthy with demo-worthy functionality because this is the part of the workflow that has the most impact with prospects, both technical and not. The design of each screen should be pleasing to the eye and easy to follow, and should not overwhelm the viewer with information.

Creating a New Screen

Naming conventions for screens

Screen names should have clear and concise names that accurately describe the content, and should be assigned to a category named after the process they are used in. For example, if the screen is used in a process named “Loan Origination Process,” there should be a screen category named as such, and all screens used in the process should be in that same category. If the screen is a nested screen commonly used across any number of processes, it should be categorized as a “Base Form.”

Notice in the example below how including the process name in the name of the screen gives you a context for how the screen is used. Without the process name, what would “assign workspace” mean? The viewer may have an idea, but including the process name in the screen name removes room for confusion.

Writing a screen description

The description of a screen should clearly describe in detail about what the screen is used for, who is filling it out (if it’s a form-type screen) and any interesting features that it showcases.

Categorizing a screen

A new screen category for the process where the screen is used should be created, and each screen used in the process should be included in that category. The screen should also be included in screen categories that reflect the industry or features showcased in the screen. A new category should be created if it does not exist.

Screen Design

First screen of a process

The first screen of a process is crucial for any demo.This is the “world-building” screen of the process; the first screen sets the stage for what is about to happen in the rest of the process and provides crucial context for what is going to happen in the next 20 or 30 minutes. Imagine the mindset of a new prospect who has never seen a DPA platform before - what would be their reaction if they were to see a boring black and white form with no images and 30 different fields with no explanation? They are going to be confused at minimum, if not completely overwhelmed. Their mind is going to be so focused on understanding what is shown before them that they will not hear a word the presenter is saying.

Including a simple screen as a cover page for the rest of the process is a simple way to get the viewer’s feet wet and invite them into the world that has been created for them. When learning a new concept or creating a new memory, it is as important to address as many of the five senses as possible to make a lasting impression. By allowing them to see the purpose of the process through a written explanation as well as hear the presenter describing the context, the demo will make more impact by addressing both sight and hearing..

General screen design standards

• Use bootstrap classes for colors whenever possible; therefore, when the environment’s colors are changed, the colors for each screen are also changed automatically. Only use hex codes for grayscale colors.

• Use nested screens whenever possible (ex. contact information, address).

• Keep the number of fields on a single page to a 20-25 maximum.

• Use whitespace to keep forms elegant and draw attention to the text on the page.

• Use relevant icons and images to break up monotony and make the UI interesting.

• Keep the number of colors to 3-4 maximum - colors not on the grayscale should reflect the environment’s color palette.

• Keep the number of font sizes to 3-4 maximum. The font style should be the environment’s font style.

Headers

A header should be included at the top of every form screen. The header should include a logo (ProcessMaker’s logo for a canned asset, the prospect’s logo for a POC), the name of the form, a subtitle for the form, and reflect the color palette of the environment. The title and subtitle of the screen should be included in the calculated properties of the screen where the header is placed.

Here is an example HTML for a header. Notice that this HTML inserts the pageTitle and pageSubTitle properties into the design. Also note that the bg-primary Bootstrap class is used to set the background color of the header.

Note: The HTML below hides the right panel and breadcrumbs when an end user is completing a task while signed into the platform. If you do not want to hide these items, then make a copy of the header and delete the HTML that hides them in the copy.

Below is the accompanying CSS to complete the header styling.

The image below is the end result of the HTML and CSS above.

When creating a header, feel free to create a different version keeping the guidelines in this section in mind.

Page Navigation and Progress Bar

Every multipage form should have some type of navigation that allows the user to easily navigate between pages of the same form. This is an important demo element that almost always gains the interest of the prospect.

Below is an example of tabs that are used for page navigation, and a progress bar below to show the progress of the application. In this case, the progress bar is static, but it can be made dynamic as well.

Side navigation is also possible. The image below shows both side navigation and another type of progress bar that explains the flow of the form to the user.

These are just two examples of what is possible when it comes to page navigation and progress tracking. Feel free to use these ideas or create another design for page navigation.

Form fields

• A single page of a screen should only have 15 visible fields maximum.

• Use visibility rules to hide fields whenever possible.

• Use sidebars to create margins and whitespace to draw the eye to the content.

• Avoid making a single field the entire width of the page.

• Use masking for phone numbers, social security numbers, tax IDs, etc.

• All fields should be clearly labeled with consistent capitalization.

• All words should be spelled correctly and phrases should use proper grammar.

• Groups of related fields should have their own subheader (ex. Personal Information, Address, Employment Information).

• Use toggles instead of individual checkboxes.

• Use clear and generic names for variables.

The above image of a screen is a good example of how most screens should be composed. Look at how the margin on the left with the user Fontawesome icon describes the intent of the fields on the page while creating whitespace, drawing the eye to the content on the right.

In the above image, notice how toggles are used to simplify the form to avoid overwhelming the end user with unnecessary information. When a toggle is enabled, then a group of fields appears below.

Buttons

• Buttons should take up the entire width of the column they are in. Use multicolumn tables to adjust the relative to the screen, then use the width CSS property to set the button width to 100%.

• Label submit buttons according to the action taken after the button is clicked. For example, instead of labeling a button “Submit,” label it “Send Application for Review.”

Loops

Always relabel the loop buttons to be more specific to the use case.

The CSS to do this is included below.

Nested Screens

While creating a screen, if a group of fields is being used frequently across multiple screens, it is a good idea to make that screen a nested screen. Nested screens are often used to collect contact information, addresses, personal information, ID information, employment information and more. They are also excellent demo assets because they truly showcase ProcessMaker’s ability to reuse assets across screens and processes.

It is often a good idea to place nested screens inside loops so that all input is put inside of a nested property. For example, variables in a nested screen for addresses might be street address, street, city and state. Putting the nested screen inside of a loop labeled business will store all of the input inside of the business property, i.e. business.streetAddress, business.street, business.city and business.state. This prevents common input types from being overwritten.

Watchers

• Use the CSS below to replace the loading screen for watchers from the default.

• This website is a good resource for generating unique loading animations: https://loading.io/.

Bookend pages

Immediately before or after a user submits a screen, it is a good idea to add an additional page explaining what happens after the form is submitted, especially if the use case is for an external user, like a banking customer or a university student.

• Use the last page in a screen to display this information before submitting a form.

• Use a web entry completion screen for a web entry.

• Use an interstitial screen for a logged in user to redirect them using an HTML button. (Note: this is sort of a “hack” to redirect users to another place other than the Tasks page when the next task is not assigned to the same user).

As seen in the image above, this does not have to be anything complicated. Just something to inform the end user of the next steps.

Summary Screens

Ideally, each process should end on a summary screen that includes a relevant summary of the request. See the example below of a request summary for a loan origination process.

Scripts

Most of the time, you shouldn’t be using live scripts for a demo. If you need to use a script as part of a process, (to show what interstitial screens look like, for example), it should always return true to eliminate any potential for failure during the demo. In the case a script is necessary, please follow the guidelines below to ensure that your code is clear and readable for other team members.

Declaring Variables

Always declare variables that store values from request data at the top of the script. This helps team members looking at your script know what data input is necessary to test the script in the case they need to use the script. Use comments to indicate which group of variables use request data.

Follow the request data with values set in the script configuration in the process (if applicable).

Finally, declare any other variables necessary to run the script that do not require request data or configuration from the process.

Next, define the functions and conditions required by the script. Include detailed comments throughout the script along with descriptive variable names to help other team members.

Also try to use the SDK to call internal endpoints rather than creating a Guzzle or CURL client.

Request Tracking

The ability to track requests is crucial for any end user, and helps immensely when demoing a process to a prospect because it helps the prospect understand the sequence of events as the sales engineer runs through the demo. Therefore, each demo asset should have generic users (e.g. “applicant” and “reviewer”) that each have their own dashboards, top menus and saved search charts that make sense within the context of the user’s role. Including relevant ways to track requests helps immerse prospects into the experience and allows them the understanding to start applying some of the concepts demonstrated to them to their own use cases.

Top menu/saved searches

Every dummy user in a demo should have their own customized top menu with options appropriate for their role in the demo.

For example, users external to the organization that have a ProcessMaker user typically have only one menu option: My Dashboard.

On the other hand, a manager might have a link to their Dashboard, an In Queue option linking to a list of requests waiting to be claimed, a To Do option linking to a list of tasks assigned to the user, and a link to a Collection or Saved Search containing important, relevant statistics regarding the use case being demoed.

Each link in the top menu should have their own accompanying icon next to the test. The link text itself should be clear, concise with each word capitalized. The example below is a top menu for a user that reviews incoming applications.

Dashboards

Like menus, each user role represented in the demo should have their own corresponding dashboard. Users external to the organization should have extremely simple, intuitive dashboards with minimal options. See the example below for a template designed for someone external to the organization.

.

The example below illustrates a dashboard used for an internal user. Dashboards for internal users should include graphs labeled with titles relevant to the use case and Saved Search charts that allow easy access to in-flight requests.

Pizza Tracker

Enable visual tracking information from the process on the request screen using a pizza tracker visualization

Breadcrumb Tracker

Enable visual tracking information from the process on the saved search using breadcrumb tracker visualization:

Data Model

All assets built within a demo asset should fit within a uniform data structure, detailed below, to allow for saved search charts, screens and scripts to be reusable across many processes. It will also help sales engineers better understand processes that they have not built themselves, and prevent team members from re-inventing the wheel when it comes to naming variables and structuring the data for any asset.

Below is the data model that the sales engineering team should aim to conform to.

Contact

The contact property represents the contact information for the process in the case multiple people are involved in a single process. Normally, the contact property is used in the context where an external applicant is filling out some sort of application, such as a loan application or onboarding process.

The contact property should be used to create any saved search chart related to tracking requests.

People

The People property contains all personal information relating to any person listed on a form or application. All nested properties may not be necessary for each process, but this object contains most, if not all, basic information required for any application.