Das Datenbankzähler-Plugin ermöglicht es, einen oder mehrere globale Zähler in einer Datenbank anzulegen. Der Zählwert kann innerhalb der Statusverarbeitung erhöht, erniedrigt, ausgelesen oder zurückgesetzt werden. Mögliche Anwendungsfälle sind etwa:

• Ein Teilnahmeformular, in dem die Anzahl der Teilnehmer pro Termin gezählt wird und weitere Anmeldungen ab einer bestimmten Grenze blockiert werden.
• Das Generieren einer ID für einen Formularvorgang, die unabhängig von der FORMCYCLE-internen Prozess-ID ist. Dies ist speziell dann sinnvoll, wenn die ID einem bestimmten Muster folgen soll oder in regelmäßigen Abständen zurückgesetzt werden muss.
• Das n-fache Durchlaufen der Aktionen eines Status, wobei n in Abhängigkeit einer Formulareingabe festgelegt wird.

Zudem ist es auch möglich, den aktuellen Wert eines Zählers über einen Platzhalter in der Verarbeitung oder per AJAX im Formular abzufragen.

Jeder Zähler besitzt sowohl einen Namen als auch eine eindeutige UUID. Die UUID dient zur eindeutigen Identifikation Zählers und wird bei der Abfrage per AJAX verwendet.

Nach Installation stehen zwei neue Aktionen in der Statusverarbeitung zur Verfügung: Counter und Variable. Bei Counter muss der Zählername fest eingegeben werden, bei Variable kann der Zählername dynamisch durch den Wert eines Formularfelds bestimmt werden.

Aktionverarbeitung "Counter"

Nach Installation gibt es in der Status- und Aktionsverarbeitung eine neue Aktion namens Counter. Mit dieser Aktion kann der aktuelle Zählwert eines Zählers geändert werden.

Im Unterschied zur Aktion Variable muss und kann hier der Zähler fest ausgewählt werden. Der Zähler sollte vorher auf der Zählerübersichtsseite (siehe unten) angelegt werden. Daher eignet sich diese Aktion besonders für globale Zähler, wie etwa für die Generierung einer fortlaufenden Vorgangs-ID.

Zählername

Auswahl des Zählers, dessen Wert geändert werden soll. Der Zähler sollte vorher auf der Zählerübersichtsseite angelegt werden, kann aber auch hier neu erstellt werden. Für jeden Zähler wird sowohl sein Name als auch seine UUID angezeigt. Die UUID dient der eindeutigen Identifikation des Zählers und wird etwa bei der Abfrage per AJAX verwendet. Um einen Zähler zu löschen, wird dieser ausgewählt und das Papierkorb-Symbol rechts neben der Auswahl betätigt. Um einen neuen Zähler hinzuzufügen, wird zuerst auf das Plus-Symbol gedrückt, anschließend der gewünschte Name des Zählers eingegeben und schließlich der neue Zähler durch Drücken des Plus-Symbols angelegt.

Zählaktion

Gibt an, in welcher Art und Weise der Wert des Zählers geändert werden soll. Möglich Optionen sind:

Hochzählen

Erhöht den Wert des Zählers um die eingegebene Zahl.

Herunterzählen

Erniedrigt den Wert des Zählers um die eingegebene Zahl.

Zähler auf Startwert zurücksetzen

Setzt den Wert des Zählers auf den eingegebenen Startwert zurück.

Schrittweite

Anzahl, um die der Zähler hoch beziehungsweise herunter gesetzt werden soll.

Globale Einstellungen nutzen (deprecated)

Diese Option sollte angehakt bleiben und dient nur der Abwärtskompatibilität zu älteren Versionen des Plugins. Bei älteren Versionen gab es nicht die Möglichkeit, eine Menüseite im Backend für die Zählerkonfiguration anzulegen, daher musste dies in der Aktionsverarbeitung geschehen. Ist diese Option deaktiviert, erscheinen weitere Einstellungen, die weiter unter im Abschnitt zur Zählerübersichtsseite beschrieben sind.

Rückgabeparameter der Aktionen

Manchmal ist es notwendig, auf den neuen Zählwert zugreifen zu können. Dies kann über Aktionsplatzhalter geschehen, welche auf die Rückgabewerte einer Aktion zugreifen. In den allgemeinen Rückgabeparametern kann eingestellt werden, über welchem Schlüssel die Rückgabeparameter Aktion zugegriffen werden kann. Beispielsweise trage die Zähleraktion den Namen CountUp. Dann kann über den Platzhalter [%$CountUp.RESULT[0].count%] auf den aktuellen Zählwert zugegriffen werden, falls unter (3) bei den allgemeinen Rückgabeparameter der Wert count eingetragen wurde. Folgende Rückgabeparameter sind verfügbar:

1 - ResultCode

Ein nummerischer Zahlenwert, der angibt, ob die Zählaktion erfolgreich war oder nicht. Folgende Ergebnisnummern sind möglich:

1 (OK)

Die Zählaktion wurde erfolgreich abgearbeitet.

10 (UNKNOWN_ACTION_ERROR)

Die Zählaktion kann nicht ausgeführt werden, da eine unbekannte Zählaktion ausgewählt wurde. Aktuell werden die Zählaktionen Hochzählen, Herunterzählen und Auf den Startwert zurücksetzen unterstützt.

11 (PARSING_ERROR)

Ein konfigurierter Wert hat nicht den erwarteten Datentyp, etwa wenn für die Schrittweite des Zählers keine syntaktisch korrekte Zahl eingegeben wurde.

40 (INTERNAL_ERROR)

Es ist ein anderer Fehler aufgetreten, der nicht näher klassifiziert werden kann.

2 - ResultMessage

Eine englische Beschreibung des Resultats (Erfolg oder Fehler).

3 - Counter

Der neue nummerische Wert des Zählers, nachdem die Zählaktion ausgeführt wurde.

4 - IsReset

Entweder true, falls der Zähler durch die aktuelle Aktion zurückgesetzt wurde; oder false, wenn er nicht zurückgesetzt wurde.

5 - CounterAfterReset

Falls der Zähler zurückgesetzt wurde: Der nummerische Wert des Zählers vor dem Zurücksetzen.

Systemplatzhalter-Plugin

Nach Installation des Plugins ist ein neuer Systemplatzhalter verfügbar, über den auf den aktuellen Wert eines Zählers zugegriffen werden kann. Dies ist etwa nützlich, um in einer Aktionsbedingung den Zählwert nutzen und prüfen zu können. Der Platzhalter baut sich nach dem folgenden Schema auf:

Um also etwa auf den Zähler mit dem Name test zuzugreifen, muss der folgende Platzhalter genutzt werden:

Servlet-Aktions-Plugin

Nach Installation des Plugins ist eine neue Servlet-Aktion verfügbar, mit der auf den aktuellen Wert eines Zähler zugegriffen werden kann. Dies ist etwa nützlich, wenn aus dem Formular heraus ein Zählwert per AJAX-Anfrage abgerufen werden soll. Die URL für das Servlet baut sich nach dem folgenden Schema auf:

Falls also etwa FORMCYCLE lokal unter dem Pfad xima-formcycle installiert wurde, der Zähler in einem Formular des Mandanten mit der ID 1 verwendet wird und die UUID bc49d3b0-f869-4e59-864e-ddcc2925ed63 besitzt, dann lautet die URL:

Alternativ ist es auch möglich, statt der client-id die ID des Formulars zu verwenden. Diese IDs lediglich verwendet, um das Servlet-Aktions-Plugin zu bestimmen, welches ausgeführt werden soll, und werden von diesem konkreten Plugin nicht ausgewertet:

Nach Ausführung des Servlet-Aktions-Plugin wird das Ergebnis als JSON-Objekt zurückgeliefert, siehe hierzu auch die Abbildung. Dieses JSON-Objekt hat die folgenden Einträge:

Status

Gibt an, ob der Servlet-Aufruf erfolgreich war. Der Wert ist ein weiteres JSON-Objekt mit folgenden Einträgen:

Msg

Ein nummerischer Wert, der angibt, ob der Servlet-Aufruf erfolgreich war. Mögliche Werte sind:

0 (OK)

Die Servlet-Anfrage war erfolgreich.

12 (NO_REQUEST_ID_ERROR)

Die Server-Anfrage enthielt keine Zähler-UUID.

13 (NO_COUNTER_TO_UUID_ERROR)

Es existiert kein Zähler mit der angefragten UUID.

40 (INTERNAL_ERROR)

Es ist ein anderer Fehler aufgetreten, der nicht näher klassifiziert werden kann.

Code

Eine englische Beschreibung des Resultats (Erfolg oder Fehler).

Counter

Informationen zum angefragten Zähler. Der Wert ist ein weiteres JSON-Objekt mit folgenden Einträgen:

Der aktuelle nummerische Wert des Zählers.

LastChange

Das Datum mit Uhrzeit, an dem der Zähler zuletzt geändert wurde. Das Datum wird mit dem Datums- und Zeitformat der aktuellen Server-Locale formattiert.

LastChangeTimestamp

Das Datum mit Uhrzeit, an dem der Zähler zuletzt geändert wurde. Der Zeitstempel ist eine ganze Zahl, welche die Anzahl an Millisekunden seit dem 1. Januar, 1970, 00:00:00 GMT angibt.

Value

Der aktuelle nummerische Wert des Zählers.

UUID

Die UUID des angefragten Zählers, dessen Wert ausgelesen wurde.

Name

Der Name des angefragten Zählers, dessen Wert ausgelesen wurde.