Instance numbers in BPS

applies to version: 8.2.x; author: Marcin Wiktor

In essence, a document number in BPS is a unique number assigned to a workflow element – a string of text which provides unambiguous identification for each element of a workflow.

This system allows users to easily and unquestionably ascertain a documents ID based on its document number – since the document number is unique within the system. Additionally, it is absolutely  certain, that any given document number will refer unchangingly to only one workflow element, since it is impossible to change a registered document number, even with administrator privileges.

A document number is created when a workflow element is saved for the first time, therefore, every workflow element existing in the system will have a unique document number.

A well thought-out structure of numbering documents can greatly increase the efficiency of finding documents (without knowing its ID or number) and browsing reports.

BPS offers a multitude of ways to configure the functionality of document numbers, in the following article I will attempt to present the possibilities and advantages of correctly configured document numbers, as well as a few custom examples.

1. Document number configuration

Document numbers for a process can be defined at two different levels – workflow or document types, yet only one configuration will be used (If both are defined, the workflow element will receive a number based on the configuration in the document type).

To demonstrate how both of these configurations work, we will make use of a sample process for organizing business trips. This workflow will have 3 document types – Domestic Business Trips (DBT), Foreign Business Trips (FBT) and Local Business Trips (LBT):

 1. At workflow level – The document number definition from the workflow configuration is only taken into account if the document number in the document type settings is not defined, or if it is set to “Use workflow document number”.

In this example, consecutive numbers will be given to elements within the workflow, without differentiating between document types. If we register one element for each document type, their numbers will look like this:

– DBT/2015/000001

– LBT/2015/000002

– FBT/2015/000003

 2. At document type level – If any option other than “Use workflow document number” is selected, the elements will be assigned a document number from here.

In this case, consecutive numbers will be assigned to elements within each document type.

So the same three documents from the previous example would be numbered:

– DBT/2015/000001

– LBT/2015/000001

– FBT/2015/000001


For both of the above examples, the numbering will reset with every new calendar year. Regardless of whether the document number is assigned from the workflow or document type, it is obvious that in most cases such numbering is far superior to a plain string of numbers which provides no information whatsoever.

There exists a third, vastly more advanced, way of assigning document numbers – by using an SDK plugin.  This solution allows custom solutions when generating document numbers.

This method will not be covered in this article. It is worth noting however, that such an option exists.


2. Document number structure

In the document number definition field, we have access to all system and form fields, as well as context variables (‘tags’) available in the tag editor. They will be placed in the document number, however their values cannot be used narrow down the numbering. In other words, the document number can contain the name of the department an employee belongs to, but elements cannot be numbered separately for each of those departments.

If we decide to include form field values in the document number, it must be noted that a document number is assigned after the element is saved for the first time. This means it is necessary to put some means of validation in place, which would block all paths or disable the save button, if all required fields haven’t been filled out. If a user fails to enter a value into a field which will become part of the document number, the number will be left incomplete.

2.1. Document numbering

A list of elements that can be included in the document number can be found under the “Document number” branch.


In addition to the numbering within the current year, BPS also offers numbering within a given month, day, “Date and time” form field as well as consecutive numbering (without taking the date into account). Numbering based around a “Date and time” form field is especially useful in processes where the date of the document’s registration in the workflow does not necessarily correspond to the date of the document’s creation.

A good example of such  a process would be some sort of agreement archive, where we want to store all the paperwork that has been gathered over many years, before the implementation of WEBCON BPS – and we want the document numbers of the agreements in this archive to contain the date on which they were signed.

It is worth pointing out, that when using such a form field to narrow down the numbering, we can choose a specific element from that date field (day, month, year) or combine elements (date + company).

Apart from dates, it is possible to have separate numbering within companies and logins.

If BPS is set to support multiple companies, we can number documents separately for each of them. It allows each company to maintain unbroken continuity in its document numbers. This avoids situations where a user who has access to all elements of company A will be left wondering why there are gaps in document numbers, when those numbers have been assigned to elements registered for company B.

The numbering within a document number can be set to be autocompleted up to a given number of signs. This means that numbers will be preceded by an appropriate number of zeros, so that the number’s total length will correspond to the desired number of digits. For example, if we set autocompleting to 6 digits, and register the 15th consecutive element, its number will be 000015.

While the editor only displays the option to autocomplete up to 10 signs, switching to Advanced mode allows us to manually modify this number to a maximum of 20 signs.




3. Element search

To make it easier for users to find specific workflow elements based on their document number we can employ 2 functionalities:

1. Add the “BPS Search Box” web part to the SharePoint site. It allows us to go directly to the element, whose document number is entered.



2. Configure an SWE web part to display the document number search box by default. The advantage of this method is the ability to search for elements by entering a partial document number, like so:



To get the same effect as in the above screenshot, go to the SWE web part configuration settings, then in the “Search” section set “Show search results immediately” and toggle the Search panel to “Visible”. In the “Data presentation and searching” find the “[System] Document number” field and mark the “Basic search” checkbox.


4. Tips and good practices

  • The structure of the document number should be well thought out before deploying the proces in a production environment. While it is possible to alter the format at any moment, it is not recommended. It can cause unneeded confusion for users and will break continuity in element numbering. Document numbers may not be altered in any way, so the elements in a given process will cease to have a uniform numbering scheme.

  • Before deciding if numbering should be carried out within the span of a year, month or day, one should estimate how many of the given type of element is expected to be registered in one day. For example, a correspondence workflow may register a dozen or two elements a daily, so numbering within the span of the current day (with element numbering resetting each new calendar day) may be reasonable. An agreement workflow may see a few tens of elements registered within a year, spread evenly over 12 months. For such workflows it is better to number elements within the current year or even opt for continuous numbering, disregarding date.

  • To shorten the document number to a minimum, it is a good idea to assign acronyms to workflows and document types, no longer than 3-4 characters, and use them in document numbers instead of full names.

  • Continuous numbering, without any additional information (like at least the process or workflow acronym) is, in almost all cases, a pretty bad idea. First of all, with a bare number like 00000765 we know nothing about the element (for example if the element is an invoice or a vacation request) and secondly we will be able to have only one process with such numbering – since a document number has to be unique within the entire system. BPS will not allow an element with a document number of 0000000001 to be registered if such an element already exists on the process. In processes where continuous numbering is a viable solution, it is always worth adding some unique distinguishing element like the process or workflow acronym.

  • Even though the document number is unique within the system, and from a technical standpoint it can be used to search for elements in the database, for performance reasons it is better to use the element’s ID (WFD_ID) and not the document number. (ex. When wanting to display elements in an SQL Grid form field).

Leave a Reply

Your email address will not be published. Required fields are marked *