Database counter plugin

Plugin download (requires login)

The database counter plugin may be installed as either a client plugin or a system plugin. It requires no additional configuration. Once installed, it offers to new workflow actions: Variable and Counter.. The Counter action requires you to choose a fixed counter that you would like to change. In contrast, the Variable action lets you choose the counter based on the submitted form data.

The database counter plugin lets you create one or more counter in a database. It also adds a new menu entry to the backend where you can view and edit all available counters. You can then use the workflow processing to increment or decrement the counter. This plugin is subject to additional charge.

Some of the possible use cases include:

A registration form for a weekly event, when you need to keep track of the number of registered participants. You can then block new registrations for a certain date when the maximum number of participants has been reached.
Generating a unique id for a form record that is independent of internal ids used by Xima® Formcycle. Useful especially when the id needs to conform to a certain pattern or needs to be reset in fixed intervals.
Running the actions of a certain state n-times, where n is determined by the value of a submitted form field.

Once the plugin is installed, you can manage the available counter in a separate backend page. You can check which counters exist currently and add or delete counter. The current value of each counter is displayed as well, and if necessary, you can also change the counter's value.

In addition, this plugin offers two new workflow actions: Counter and Variable. The action Counter requires you to select a predefined counter. The action Variable, on the other hand, lets you select a counter based on the value of a submitted fo m field. See the sections on each action below for further details.

Lastly, you can also access the current value of a counter either via a variable during workflow processing or via an Ajax request from within an opened form.

Each counter has got both a name as well as a unique Uuid. The Uuid uniquely identifies a counter and is used, for example, when querying the counter's current value via an Ajax request.

This is plugin bundle that includes two workflow action plugins, one placeholder replacer plugin, and one servlet action plugin. The following sections describe these plugins in more detail.

Menu entry "Counter configuration"

This plugin adds a new role permission that controls whether a user is granted access to this menu entry. Contact your administrator in case you do not see the menu entry and believe you should have access.

The menu with an overview of all existing counter. You can add or delete counter, or modify existing counters.

Once installed, a new menu entry appears in the main menu bar to the left. Please note that you may have to sign out and sign in again. The menu Counter configuration contains an overview of all existing counters, including their name and their current value. You can modify or delete existing counter, or add new counters.

Press the plus icon to the top left to add a new counter. If you would like to delete an existing counter, click on that counter to select it, then press the trash icon to the top left.

Properties

Select a counter by clicking on it in the list of counters to the left. The following details are shown for the counter:

Uuid: A unique id of the counter. You need to use this Uuid, for example, when you want to retrieve the counter's current value via an Ajax request, see also the servlet action plugin below.
Current value: The current value of the counter.
Creation date: The date when the counter was created.
Last change: The date of the most recent change to the counter's value.

Additionally, you can also edit the following properties of a counter:

Counter name: The name of this counter. When you change the name of a counter, you may have to change existing Variable action, placeholders and Ajax requests that reference a counter by its name. Ajax requests that reference a counter by its Uuid do not have to be updated.
Description: An optional description of this counter. This description is shown only within this backend menu.
Initial value: The initial value of this counter. This is also the value that is used when a workflow action resets a counter to its initial value.
Reset automatically: When this option es enabled, the value of this counter is reset in period intervals.

Reset automatically

The following settings are available when the option to reset the counter automatically is enabled:

When a counter is reset, then after the counter action was processed, the counter's value will be equal to the configured initial value. For example: Assume the counter action was configured to increment the counter by 3 each time it is executed, and should be reset daily. Let the the current counter value be 37 and the intial value 11. The first counter action that is executed on a new day will now reset the counter to 11, and not be incremented at all. Starting with the second counter action of that day, the counter will be incremented by 3 each time the action is executed.

Please note that the counter is not reset by background task, but only when the workflow action Counter or Variable is executed. Or, to be more precise, the counter value is reset (instead of being incremented or decremented), when the time points at which the counter should have been reset contains at least one point that lies between the last point in time the counter value was modified and the current point in time.

Condition

Lets you choose when and how the counter should be reset. The following options are available:

Counter greater than or equal: Available only when the counting action was set to count up. The counter is reset to its initial value when, after the counter was incremented, its value is now greater than or equal to the given limit.
Counter less than or equal: Available only when the counting action was set to count down. The counter is reset to its initial value when, after the counter was decremented, its value is now less than or equal to the given limit.
daily: The counter is reset each day at the given time of day.
weekly: The counter is reset at each of the given days of the week and at the given time of the day.
monthly: The counter is reset each month at the given date and time of the day.
yearly: The counter is reset each year the given day, month and time of the day.

Workflow action "Counter"

The settings for the workflow action Counter. You can select the counter to modify and how its value should be changed, e.g. incrementing or decrementing it by a certain amount.

Once the plugin is installed, you can select the new action Counter in the workflow processing configuration. This action lets you modify the value of a predefined counter.

Compared with the action Variable, here you need to select a predefined counter. You should have created this counter in the counter configuration menu (see above). Use this action when you need a global, non-dynamic counter, such as when you want to generate an identifier for each form record.

Counter name

Name of the counter to be modified. For each counter you can see its name as well as its Uuid. The Uuid uniquely identifies a counter and is used when querying it via an Ajax request. To delete a counter, first select the counter, then click on the thrash icon to the right. To add a counter, first click on the plus icon, then enter a name for the new counter, and finally save the counter by pressing the floppy disc icon.

Counting action

Lets you chose how the value of the counter should be changed. Possible options are:

Increment count: Adds the given amount to the current value of the counter.
Decrement count: Substracts the given amount from the current value of the counter.
Reset counter to start value: Sets the current value of the counter back to the selected initial value.

Step size

Amount by which the counter is incremented or decremented.

Use global settings (deprecated)

You should leave this option checked and configure the counter settings in the counter configuration menu (see above). It exists only to ensure backwards compatibility with older versions of the plugin and may be removed in future versions.

Workflow action "Variable"

Settings for the workflow action Variable. It lets you select a counter dynamically by its name. You can also make use of placeholder variables to select a counter based on the value of some form field.

Once the plugin is installed, you can select the new action Variiable in the workflow processing configuration. This action lets you select a counter by its name and modify its value.

Compared with the action Counter, here you do not have to choose a predefined counter. You can also use placeholder variables to select a counter based on the submitted form data. In case the counter does not exists yet, a new counter is created dynamically.

Use this action when you need different counters for each submitted form record. For example, if you have got a participation form where users can sign up for a certain date, you can use a counter for each date to keep track of the number of registered people for that date. The counter name could be formatted like participants-year-month-day.

Change variable

Select the name of the variable ("counter") to modify and how its value should be changed.

Counter name

Name of the counter to modify. Enter name of the counter, not its Uuid). You can also use placeholder variables to select a counter based on a submitted form field.

Counting action

Lets you chose how the value of the counter should be changed. Possible options are:

Increment count: Adds the given amount to the current value of the counter.
Decrement count: Subtracts the given amount from the current value of the counter.
Reset counter to start value: Sets the current value of the counter back to the selected initial value.

Step size

Amount by which the counter is incremented or decremented.

Default settings if variable does not exists yet

In case the variable ("counter") with the given name does not exist yet, a new counter is created. Here you can edit the default settings for a newly created counter. In case the counter exists already, these settings do not have any effect.

Initial value: The initial value of the newly created counter.
Reset automatically: Whether the newly created counter should be reset automatically. When this option is enabled, a few more settings appear. See the section on the counter configuration menu above for further details.

General return parameters

Settings for the return parameters of the counter action. You can access the returned values via placeholder variables.

Sometimes it may be necessary to access the new value of the counter. To do so, you can use action variables for accessing the returned values of an action. The section general return parameters lets you configure the key you need to use for accessing the return values. For example, assume a counter action were named CountUp. Then you can use the variable [%$CountUp.RESULT[0].currentValue%] to access the current counter value, provided you entered the key currentValue in the input field for the Counter return value. The following return values are available:

1 - ResultCode

A numerical value that indicates whether the counter action was successful or not. The following result codes are possible:

1 (OK): The counter action was processed successfully.
10 (UNKNOWN_ACTION_ERROR): The counter action could not be processed, an unknown counting action was selected. The currently supported counting actions are count up, count down and reset counter to start value.
11 (PARSING_ERROR): A settings does not conform to the expected data type or syntax; such as when a letter was entered for the initial value (instead of a number).
40 (INTERNAL_ERROR): The counter action was not successful. The type of error cannot be specified more closely.

2 - ResultMessage

An English description of the result (success or error).

3 - Counter

The new numerical value of the counter, after the counting action was applied.

4 - IsReset

Either true, when the counter was reset during the current action; or false if it was not reset.

5 - CounterAfterReset

In case the counter was reset: The numerical value of the counter before the reset.

System variable plugin

An example for how to retrieve the current value of a counter. Here we read a counter that is used for keeping track of the number of participants of some event. We then check whether the value exceeds the maximum number of participants. Based on the result of this check, we can display an appropriate error message to the user in case the limit was reached. By performing this check during workflow processing, we can validate the data on the server and prevent manipulatios. Please note that it is best practice to give the user some feedback while the fill out the form and inform the user in case no more free slots are available.

Once the plugin is installed, you can access the current value of the plugin with a system variable. This can be used, for example, to access the counter value in the condition of a workflow action and compare it with a submitted value. The system variable has got the following pattern:

[%$DBCOUNTER.<CounterName>%]

For example, in order to access the value of a counter named test, you can use the following variable:

[%$DBCOUNTER.test%]

In case you need to access a counter that may not exist yet, you need to provide an initial value for the counter. When the counter does not exist yet, a new counter with the given initial value is created. Use the following pattern:

[%$DBCOUNTER(<CounterName>, <InitialValue>)%]

For example, if the counter is named participants-2020-03-17 and should start at 0 in case it does not exist, you can use the following variable:

[%$DBCOUNTER(participants-2020-03-17, 0)%]

Servlet action plugin

An example for how the counter value can be accessed via an Ajax request. The Url is build with the metadata available in the form context. This avoids having to enter the Url directly in the code, which is prone to error: the host or context path could change, for example, when the form is moved between a development and production.

Once the plugin is installed, a new servlet plugin action is available that lets you access the current value of a counter via an Http request. This is useful, for example, when you would like to read the counter's current value from within a form and display it in the form. The Url for the counter action plugin servlet takes the following pattern:

https://<Host>/<FormcycleContextPath>/plugin?name=Servlet%20Counter&client-id=<ClientId>&id=<CounterUuid>

Assuming Xima® Formcycle was installed locally and runs in the context path formcycle, and the counter plugins was installed within a client with the id 1, and the Uuid of the counter is bc49d3b0-f869-4e59-864e-ddcc2925ed63, the Url is:

https://localhost:8080/formcycle/plugin?name=Servlet%20Counter&client-id=1&id=bc49d3b0-f869-4e59-864e-ddcc2925ed63

Alternatively, you can also use the id of the form instead of the client-id. Both the client and the form id are used only to identify the servlet to be executed; and are not used in any way by this counter servlet.

https://<Host>/<FormcycleContextPath>/plugin?name=Servlet%20Counter&project-id=<FormID>&id=<CounterUuid>

HTTP parameter

In addtional to the parameters mentioned above, you can also specify a few more paramters as Url parameters. The following is an overview of all available parameters.

name: The name of the servlet plugin action to execute. Set this to Servlet Counter for this plugin.
client-id: id of the client where the counter plugin was installed. Not required in case the plugin was installed as a system plugin. Only one of client-id or project-id may be specified.
project-id: id of a form that belongs to a client that has access to the counter plugin., in dem das Zähler-Plugin zur Verfügung steht. Only one of client-id or project-id may be specified.
id: Uuid of counter to read. In case a counter with the given Uuid does not exist yet, a corresponding error code is returned, see below. Only one of id or counter-name may be specified.
counter-name: Name of the counter to read. In case a counter with the given name does not exist yet, a new counter is created with the given initial value.Only one of id or counter-name may be specified.
counter-initial: Optional. The initial value of the counter, in case it does not exist yet. Defaults to 0. This parameter is allowed only when counter-name is specified.
counter-array: Optional. Either true or false, defaults to false. When this is set to true, the parameter counter-name or id may be specified multiple times. This will return an array with the current value of all specified counters. This can be used, for example, to reduce the amount of Http requests when you need to query multiple counter simultaneously.

HTTP response

If the servlet action plugin is executed successfully, it returns a Json object as shown in the figure to the right. When the parameter counter-array was set to true, a Json array is returned instead, with each item being a Json object as described below.

The Json-Objekt has got the following properties:

Status

Indicates whether the servlet request was successful. The value is another Json object with the following entries:

Msg

A numerical value that indicates whether the servlet request was successful. Possible values are:

0 (OK): The request was successful.
12 (NO_REQUEST_ID_ERROR): The request did not specify a counter UUID.
13 (NO_COUNTER_TO_UUID_ERROR): No counter with the specified UUID exists.
40 (INTERNAL_ERROR): The counter action was not successful. The type of error cannot be specified more closely.

Code

An English description of the result (success or error).

Counter

Details about the requested counter. The value is another Json object with the following entries:

LastChange: The date and time of the most recent modification of the counter value. The date and time is formatted according to the current server locale.
LastChangeTimestamp: The date and time of the most recent modification of the counter value. The timestamp is a whole number indicating the number of milliseconds January 1st, 1970, 00:00:00 GMT.
Value: The current numerical value of the counter.
UUID: The UUID of the requested counter.
Name: The name of the requested counter.

Changelog

This section lists all known versions of this plugin and describes the changes that were made in each version.

2.3.3

Fixed some spelling mistakes

2.3.2

Fixed a UI bug: The checkbox Use global settings (action Counter) now toggles the options below correctly.
Fixed some spelling mistakes

2.3.1

Fixed a bug with Mysql that prevented this plugin from working with that database management system.

2.3.0

New action: Variable
Lets you select a counter by its name and allows for placeholder variables. This requires an initial value.
New placeholder variable: DBCOUNTER(name, initialValue). Creates a new counter in case a counter with the given name does not exist yet.
Added 3 new parameters to the servlet action plugin: counter-name, counter-initial and counter-array.

2.2.0

Make sure to reset the counter even when its value is only read
Portal page that adds a new menu entry to the backend: Counter configuration
Deprecate editing a counter's settings in the workflow action directly

2.1.0

Modifications for Xima® Formcycle version 6.1.6
The CounterPlugin and ServletCounterPlugin had the same name, this resulted in errors
Fixed an error that resulted in a counter not being resetted correctly
Add a new property to the Json object returned by the servlet action plugin: Counter.LastChangeTimestamp
Added a new system variable replacer plugin that lets you access the value of a counter via a variable: [%DBCOUNTER.name%]

2.0.0

Modifications to make the plugin work with Xima® Formcycle version 6.0.2

1.0.1

Fix a bug where the counter value was not set when retrieved for the first time

1.0.0

Initial version

Tags: