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
  • Web Interfaces
  • 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, etc.). A good practice is to create a dedicated organization per application, and use the application's name as the title of your organization.

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

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.

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.

• 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.

• 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.

  Example:

  

  Provide the ids of the lanes you want the users populate from.

• 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.

• Runtime: Roles to which users are added at runtime. After their creation, runtime roles cannot be changed to another role type, and other role types cannot be changed to runtime roles.

• 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.

  Note: this lane doesn't contain any users.

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:

• 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:

• 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:

• 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:

Web Interfaces

You can configure different types of Web Interfaces:

• Main web interface: In your main project, where you've configured the main process, you'll configure the main web interface that triggers this process.

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

• Reports: When you submit a web interface to trigger a process, you can then create reports and embed them in another web interface 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 Web Interfaces. Technically a custom widget is a web interface 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 Web Interfaces. 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 "_".

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}

• 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).

• Local providers with DigitalSuite EnterpriseConnect (DSEC): If you configure a provider to integrate with a LOCAL system and use DSEC, it is recomended that you use, as title:

{server_adress}:{port}/ via DSEC {dsec_domain}

• Option Usage Rules

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

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).

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 -

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

Reports

You can save 2 kinds of reports on RunMyProcess: web interface 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:

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.

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

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:

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:

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:

• 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:

• 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":

• 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.

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

))

• 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:

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.

File upload widget

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

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.

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

${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:

Progress bar/circle widget

It is highly recommended that you show a progress indicator every time you'd like to call a CAPI, so the end user knows something is running in the background. You can choose between a bar or a circle element.

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

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:

Tab widget

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

Section widget

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

Collection

You can plug a collection to a web interface 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.