×

Please give details of the problem

Docs

Find

Best Practices on Naming Resources

Choosing the right names, prefixes and suffixes for your resources and variables will ease troubleshooting and maintenance of your RunMyProcess applications.

RunMyProcess resources

Every RunMyProcess application requires you to configure different resources:

  • An organization
  • Several entities & roles
  • Several projects
  • For every project
    • Processes
    • Webinterfaces
    • Custom lists
    • Collections
    • Providers
    • Connectors
    • Composite APIs (CAPIs)
    • Reports
    • Versions

Organizations

For every new application you create, there will be a dedicated set of roles (managers, approvers, super managers...). A good practice is to create a dedicated organization per application, and use the application's name as the title of your application.

Here's an example for a "Vacation Request" app:

Organization per application

You will also need a dedicated organization for all the "cross-application" roles (ex: CEO, Marketing department, France Sales department). You may also want to sync this organization with your Google Directory or AD. Use your company name as title for this organization.

Organization cross applications

Entities and roles

Entities and roles are the same RunMyProcess object : they are groups of users.

Entities are more like departments or locations, whereas roles are more like positions in a company.

An entity or role can also be called a lane. A lane can be of 5 types, for each type of lane we'll use a dedicated suffix.

  • Everybody

The "Allow everybody" check-box is ticked, so it contains all the users on the RunMyProcess account. It is recommended that you use (everybody) as suffix.

  • Dynamic

the "Dynamic role" check-box is ticked, so you can use this lane to design a manual task in a process and pick a different lane when assigning a task. It is recommended that you use (dynamic) as suffix.

Note: this lane doesn't contain any users.

  • Scripted

Scripted lanes are defined when you enter a formula in "Role script" that rely on user metadata or other lane IDs. It is recommended that you use a title related to the formula you've entered and add a (script) as suffix.

2 examples:

Scripted formula metadata

Scripted formula lanes

  • Static

It's a standard lane, you can drag and drop users in it. there is no specific suffix recommended, just enter an explicit title.

  • Empty

You may want to create different levels of lanes in your organization. To do so you'll create parents that may be empty, and different child lanes underneath. If the lane is empty, it is recommended that you add (empty) as suffix

Projects

For every RunMyProcess application, you'll need to create one or several projects since you'll need to have different set of rights for your resources and you won't version them the same way.

As prefix for all these projects, it is recommended that you use the application name, and, as suffix, the specific set of rights or type of version.

Ex: We have built a Vacation Request app that's divided into 5 projects:

Scripted formula lanes

  • Mail provider KU

This is a project that is created by default on your RunMyProcess account. You will need to embed it in every project where you configure a process to send email notification. It is recommended that you use KU as suffix since we ticked the "keep update" check-box while creating a version on this project (More info on this option).

  • Vacation Request - MAIN

This is the core project of the application. For this reason we added - MAIN as suffix.

  • Vacation Request - Manager

This project includes the "MAIN" project, and is dedicated to resources only accessible by the Manager role of the Vacation Request app. For this reason we added - Manager as suffix.

  • Vacation Request - Admin

This project includes the MAIN project, and is dedicated to resources only accessible by the Admin role of the Vacation Request app. For this reason we added - Admin as suffix.

  • Vacation Request - Connectors KU

This project is included in the MAIN project, and contains all the providers and connectors used to integrate the Vacation Request app with 3rd party systems. We added KU as suffix since we ticked the "keep updated" check-box while creating a version on this project (More info on this option).

Processes

In the MAIN project, you will configure the workflow processes. You will usually have a main process and several subprocesses:

Scripted formula lanes

  • Main process

When you open a project you may want to create a main process in which to create subprocesses. It is recommended that you use the suffix - MAIN for this process.

  • Subprocesses

To identify processes that will only be triggered by a father process, use SUB - as prefix.

  • Batch processes

If you've configured a batch process (timer as starting point of the process), it is recommended that you use BATCH frequency - as prefix to identify it:

Scripted formula lanes

  • Processes triggered by email

If you've configured a process triggerable by email, it is recommended that you use EMAIL - as prefix to identify it:

Scripted formula lanes

Webinterfaces

You can configure different types of webinterfaces:

Scripted formula lanes

  • Main webinterface

In your main project, where you've configured the main process, you'll configure the main webinterface that triggers this process.

You can use the name of your application as title for your webinterface. If you intend to display a different title in your reports, you can configure a dynamic name (Webinterface>Implementation>Dynamic name).

  • Reports

When you submit a webinterface to trigger a process, you can then create reports and embed them in another webinterface so the end users can see their tasks, drafts, requests, etc... Use Report - as prefix and the perimeter of users that can access it as suffix.

  • Custom widgets

A custom widget is a set of widgets you can reuse and embed in webinterfaces. Technically a custom widget is a webinterface of type "Custom widget". You will use custom widgets to configure a menu bar or a progress bar, for example. Use CW - as prefix

  • Backoffice

To maintain the content of a collection, or to manage users, you will configure dedicated webinterfaces. Use Backoffice - as prefix and as suffix the type of items you manage.

Custom lists

No specific best practice, just enter an explicit title.

Collections

When you create a new collection you're asked to enter its name. Keep in mind that naming a collection is like naming a table in a DB : you should NEVER change its name, and choose a name with only lowercase characters and no special characters except underscore "_".

Collections

Providers

You can configure providers to send emails, and to perform integration with 3rd party systems.

  • Email providers

Use as title smtp {provider_name} - {login_stored_in_provider}

Smtp providers

  • Cloud providers

If you configure a cloud provider, use an explicit title with the name of the service/software vendor (as you can find in our library).

Cloud providers

  • Local providers with SEC

If you configure a provider to integrate with a LOCAL system and use SEC, it is recomended that you use, as title:

{server_adress}:{port}/ via SEC {sec_domain}

Provider using SEC

  • Option Usage Rules

Provider usage rules

If you ticked the "Enable usage rules" check-box, add a suffix to provider title : (max frequency {value} {units})

Provider usage rules

Connectors

  • Connectors from library

Leave their title as it is.

  • Custom connectors.

The best practice is to enter an explicit name containing: the action, the webservice version (if the url of the provider doesn't change after version upgrades), and the method called (it all the more makes sense for SOAP connectors).

Salesforce connectors

Custom connectors

Important : when a new version is available for a webservice, DO NOT modify the existing connector on RunMyProcess. Create a new connector to avoid regressions.

CAPIs

A composite api (CAPI) is a set of connectors, themselves portrayed as APIs.

Just use the prefix CAPI -

Custom connectors

Don't forget to enter a proper description with INPUT and OUTPUT parameters:

Custom connectors

Reports

You can save 2 kinds of reports on RunMyProcess : webinterface instances reports, and process instances reports.

Enter an explicit title related to the filters you've configured, and add as suffix that represents the mode you're filtering on:

Custom connectors

Versions

Every time you want to propagate your changes to acceptance and then your production environment, you'll have to create a version of your projects (See create a new live version).

It is recommended that you follow the 1.0, 1.1, 2.0 nomenclature. Every minor change should impact the figure after comma, and every major change should impact the figure before comma.

Versions

If you ticked the "Always keep all resources updated" check-box, then it is recommended that you add a KU suffix:

Versions KU

RunMyProcess widget variables

Every widget may have none, one or several variables.

The common best practice, with regard to collections is: you should NOT change the variable names during the design of an application (it will cause regressions). You must also choose a name with lowercase characters only, no special characters except for underscore "_".

Text and Number input widget

These widgets only have one variable:

Text input Number input

Date input widget

When you pick a date in this widget, you'll store the number of seconds elapsed since 1/1/1970 in the "Numeric date variable", and the user-friendly date format in the "String date variable".

It is recommended that you use the same prefix for both variables, and add _sec as a suffix for the numeric variable, and _string as suffix for the string variable:

Date input

Note: NEVER use the string date variable in your formulas, you should only use the numeric variable.

List widget

There are several types of list widget:

  • Users

This will display the members of an entity/role in your organization.

As selected value you'll get the user's login, as selected label you'll get the the user's name. Use the same prefix for both variables, add _login suffix for the value one, and _name suffix for the label one:

List users

  • Entities or roles

This will display the sub entities/roles of an entity/role in your organization. Entities and roles are both lanes.

As selected value you'll get the lane id, as selected label value you'll get the lane name. Use the same prefix for both variables, add _lane_id suffix for the value one, add _lane_name suffix for the label one:

List lanes

  • Custom list

This will display the content of a label-value list. Use the same prefix for both variables, and add _id as suffix for the "Value variable" and _name as suffix for the "Label variable":

List custom

  • Variable based

You can configure a dynamic list by generating a list variable the list is relying on. You can choose any source of data from the moment you set this list variable (See tutorial).

The Custom list rules apply, and for the list variable. It is recommended that you use, as name, vb_{item_name}s :

List variable based

  • Option Multi-Selection

If this option is enabled, you'll be able to select multiple items. The selected value and label variables will turn into Array variables, so it is recommended that you add a s to your variable names:

List multi selection

Switch widget

You can keep the predefined variable name, it should look like a question without the "?".

As value checked/unchecked, It is recommended that you use yes/no, instead of true/false, since variables passed to the process and webservices are converted to string, and using a string instead of a boolean will avoid misunderstandings.

Switch

File upload widget

Since the variable contains a list of files, remember to use the plural:

File upload

Array widget

An Array widget doesn't have any label, so you must enter a variable name.

Important: the value of this array will be in the column view format (= a JSON of arrays). You will have to use the ${transpose} function to convert it into a row view format (=an array of JSONs) if you intend to loop on rows. It is highly recommended that you then add a suffix _t to distinguish the formats:

Array widget

Then, in your process, you can create a variable articles with value:

1
 ${tranpose(articles_t)}

Radio buttons and Checkboxes widgets

The Custom list and Multi-Selection rules apply.

RunMyProcess widget identifiers (ids)

By default when you enter a label, the identifier will be generated automatically. Some widgets don't have any label so you have to choose an id:

Spinner widget

It is highly recommended that you show a spinner every time you'd like to call a CAPI, so the end user knows something is running in the background.

As prefix use id_spinner_ and what action you are performing as suffix:

Spinner widget

Html widget

You can use a HTML widget to display custom HTML code, like a blue info message or even a pure HTML table.

As prefix, it is recommended that you use id_html_ and what it displays as suffix:

Html widget

Tab widget

As prefix, use id_tabs_ and what it displays as suffix:

Tab widget

Section widget

As prefix, use id_section_ and what it displays as suffix:

Section widget

Collection

You can plug a collection to a webinterface to enable the JavaScript methods over the collection. By default the identifier is generated with col_ as prefix plus the collection name. It is highly recommended that you leave it as it is.

Collection id