Inhalt

Vorbemerkungen

Achtung: Das Plugin liegt aktuell in einer Beta-Version vor.

Für das Plugin bieten wir keinen Support!

Das System-Replacer Plugin für formcycle bietet eine Möglichkeit, Platzhalter innerhalb eines Formulars zu definieren, die durch benutzerdefinierten JavaScript-Code ersetzt werden können. Durch diese Funktionalität lassen sich dynamische Inhalte im Workflow einfügen und mit den Eingaben der Benutzer verknüpfen.

Die Nutzung des Plugins erfordert Programmierkenntnisse in JavaScript. Da die Fehlersuche (Debugging) im Workflow nur sehr begrenzt möglich ist, ist der Code schlecht wartbar und das Plugin stellt eine hohe Anforderung an eine saubere Programmierung.

Installation

Das Plugin kann als Mandant-Plugin oder System-Plugin installiert werden. Eine Anleitung zur Installation von Plugins finden Sie hier.

Funktionsweise

Das Ausführen von JavaScript wird durch die spezielle Syntax [%$=] aktiviert. Innerhalb dieser Syntax kann beliebiger JavaScript-Code eingefügt werden. Der JavaScript-Code wird in dem Moment ausgeführt, wo der Platzhalter ausgewertet wird.

Die Funktion kann überall dort verwendet werden, wo die Platzhalterauswahl zur Verfügung steht.

Ein Beispielformular mit einem Auswahlfeld selAnrede, zwei Eingabefeldern für den Namen tfVorname und tfNachname und zwei Eingabefeldern für Beträge tfBetrag1 und tfBetrag2 könnte so aussehen:

Im Workflow wird eine Textdatei erzeugt, die danach gleich ausgeliefert wird. Der Inhalt enthält JavaScript-Anweisungen:

Die Textdatei wird im Beispiel in einem Popup-Fenster ausgegeben:

Platzhalter-Syntax

Die folgenden Beispiele gelten ab Version 5.1.0 des Plugins. Für ältere Versionen beachte die Hinweise am Ende dieses Artikels.

Der Platzhalter beginnt mit [%$=, gefolgt von dem JavaScript-Code und wird mit %] abgeschlossen.

Der JavaScript-Code wird zur Laufzeit ausgeführt und das Ergebnis wird anstelle des Platzhalters im Formular eingefügt.

[%$= "Hallo " + fc.form.value("tfVorname") + " " + fc.form.value("tfNachname") %]

[%$=(parseInt(fc.form.value("selAnrede")) === 1 ? "Sehr geehrter" : "Sehr geehrte") + " " + fc.form.option("selAnrede").text %] [%tfVorname%] [%tfNachname%]

[%$=
    const field = "selAnrede";
    const male = parseInt(fc.form.value(field)) === 1;
    const address = male ? "Sehr geehrter" : "Sehr geehrte";
    address + " " + fc.form.option(field).text;
%] [%tfVorname%] [%tfNachname%]

[%$= parseFloat(fc.form.value("tfBetrag1")) + parseFloat(fc.form.value("tfBetrag2")) %]

Funktionen

Ab Version 5.1.0 stehen im globalen JavaScript-Objekt fc Funktionen zur Verfügung. Im Gegensatz zur alten get("...")-Schreibweise handelt es sich dabei um normale JavaScript-Funktionen, die alle Möglichkeiten von JavaScript erlauben und normale JavaScript-Werte und Objekte zurückliefern.

Aktuell gibt es die im folgenden erläuterten Funktionen.

Formular und Vorgang

fc.form enthält Funktionen, die den Zugriff auf Formularwerte und den Information des Vorgangs erlauben.

Zur Illustration nehmen wir an, dass es im Formular ein Auswahlfeld namens sel1 gibt, welches als Checkboxen dargestellt wird und wiederholt ist. Zur Auswahl stehen folgende 4 Optionen

• Rot (Wert "r")
• Grün (Wert "g")
• Gelb (Wert "y")
• Schwarz (Wert "b")

Der Nutzer hat 2 Wiederholungen des Felds erzeugt und folgende Checkboxen angehakt:

• 1. Wiederholung: Schwarz
• 2. Wiederholung: Rot, Gelb

Für Metadaten des Vorgangs stehen folgende Werte zur Verfügung:

• fc.form.recordId
  • Enthält die ID des Vorgangs (als String).
  • [%$=fc.form.recordId%]
    • Resultat: 5931
• fc.form.recordUuid
  • Enthält die UUID des Vorgangs (als String).
  • Auch bekannt unter der Bezeichnung Prozess-ID.
  • [%$=fc.form.recordUuid%]
    • Resultat: 8cd7802d-b684-447e-82aa-45662546c78a
• fc.form.recordCreated
  • Enthält den Zeitpunkt, wann der Vorgang erstellt wurde (als Date-Objekt).
  • Zur Formatierung kann "fc.date.format" genutzt werden.
  • [%$=fc.form.recordCreated%]
    • Resultat: Fri Mar 06 2026 00:47:28 GMT+0100 (CET)
• fc.form.recordModified
  • Enthält den Zeitpunkt, wann der Vorgang zuletzt bearbeitet wurde (als Date-Objekt).
  • Zur Formatierung kann "fc.date.format" genutzt werden.
  • [%$=fc.form.recordModified%]
    • Resultat: Fri Mar 06 2026 00:49:02 GMT+0100 (CET)

Für Formularwerte stehen folgende Funktionen zur Verfügung:

• fc.form.value(fieldName, repetitionIndex?, valueIndex?)
  • Greift auf den Wert des Felds zu. Liefert immer einen String zurück.
  • Falls das Feld wiederholt ist oder mehrere Werte hat, wird der 1. Wert der 1. Wiederholung genommen.
  • Optional kann auch angegeben werden, welche Wiederholung oder welcher Wert genommen werden soll.
  • [%$=fc.form.value("sel1")%] - 1. Wert der 1. Wiederholung
    • Resultat: b
  • [%$=fc.form.value("sel1", 1)%] - 1. Wert der 2. Wiederholung
    • Resultat: r
  • [%$=fc.form.value("sel1", 1, 1)%] - 2. Wert der 2. Wiederholung
    • Result: y
• fc.form.values(fieldName, repetitionIndex?)
  • Greift auf die Werte des Felds zu. Liefert immer eine Array (Liste) zurück.
  • Falls das Feld wiederholt ist, werden die Werte der 1. Wiederholung genommen.
  • Optional kann auch angegeben werden, welche Wiederholung genommen werden soll.
  • [%$=fc.form.values("sel1").join(" - ")%] - Werte der 1. Wiederholung
    • Resultat: b
  • [%$=fc.form.values("sel1", 1).join(" - ")%] - Werte der 2. Wiederholung
    • Resultat: r - y
• fc.form.valuesAll(fieldName)
  • Greift auf alle Werte des Felds zu. Liefert immer eine Array von Arrays zurück.
  • Das äußere Array stellt die Wiederholungen dar, die inneren Arrays die Werte der jeweiligen Wiederholung.
  • [%$=JSON.stringify(fc.form.valuesAll("sel1"))%]
    • Resultat: [["b"], ["r", "y"]]

Für die Optionen, welche zu den aktuellen Werten eines Auswahlfeld gehören, stehen folgende Funktionen zur Verfügung:

• fc.form.option(fieldName, repetitionIndex?, valueIndex?)
  • Greift auf die Option zu, welche zum aktuellen Wert des Felds gehört.
  • Das Resultat ist ein Objekt mit den Daten der Option.
  • Falls das Feld wiederholt ist oder mehrere Werte hat, wird der 1. Wert der 1. Wiederholung genommen.
  • Optional kann auch angegeben werden, welche Wiederholung oder welcher Wert genommen werden soll.
  • [%$=JSON.stringify(fc.form.("sel1"))%]- Option des 1. Werts der 1. Wiederholung
    • Resultat: {"text":"Schwarz","title":""}
  • [%$=JSON.stringify(fc.form.("sel1", 1))%] - Option des 1. Werts der 2. Wiederholung
    • Resultat: {"text":"Rot","title":""}
  • [%$=JSON.stringify(fc.form.option("sel1", 1, 1))%] - Option des 2. Werts der 2. Wiederholung
    • Result: {"text":"Gelb","title":""}
• fc.form.options(fieldName, repetitionIndex?)
  • Greift auf die Optionen zu, welche zu den aktuellen Werten des Felds gehören.
  • Das Resultat ist ein Array mit Objekt, welche die Daten der Optionen darstellen.
  • Falls das Feld wiederholt ist, werden die Werte der 1. Wiederholung genommen.
  • Optional kann auch angegeben werden, welche Wiederholung genommen werden soll.
  • [%$=JSON.stringify(fc.form.options("sel1"))%] - Werte der 1. Wiederholung
    • Resultat: [ {"text":"Schwarz","title":""} ]
  • [%$=JSON.stringify(fc.form.("sel1", 1))%] - Werte der 2. Wiederholung
    • Resultat: [ {"text":"Rot","title":""}, {"text":"Gelb","title":""} ]
• fc.form.optionsAll(fieldName)
  • Greift auf die Optionen zu, welche zu allen aktuellen Werten des Felds gehören. 
  • Das Resultat ist ein Array von Arrays von Objekten.
  • Das äußere Array stellt die Wiederholungen dar, die inneren Arrays die Werte der jeweiligen Wiederholung.
  • Jedes Objekt stellt die Daten der jeweiligen Option dar.
  • [%$=JSON.stringify(fc.form.optionsAll("sel1"))%]
    • Resultat: [ [{"text":"Schwarz","title":""}], [ {"text":"Rot","title":""}, {"text":"Gelb","title":""} ] ]

Für alle möglichen Optionen eines Auswahlfelds stehen folgende Funktionen zur Verfügung:

• fc.form.availableOptions(fieldName)
  • Liefert eine Objekt mit allen möglichen Auswahloptionen zurück.
  • Der Schlüssel ist die Value der Option.
  • Der Wert ist ein Objekt mit den Daten der Option. 
  • [%$=JSON.stringify(fc.form.availableOptions("sel1"))%]
    • Resultat:
    • {"y":{"text":"Gelb","title":""},"r":{"text":"Rot","title":""},"b":{"text":"Schwarz","title":""},"g":{"text":"Grün","title":""}}
    • 
      

Der "text" der Option ist der Anzeigename, der "title" ist der Titel oder die Beschreibung, wie im Formular-Designer konfiguriert.

Falls die Auswahloptionen aus einer CSV-Quelle oder Datenbankabfrage stammen, enthält das Objekt noch weitere Einträge für die jeweiligen Spalten aus dem Ergebnis der Datenbankabfrage.

Zum Beispiel würde eine CSV-Quelle mit Städten:

{"text":"Dresden","title":"Haupstadt","col0":"Dresden","col1":"dd","col2":"328.8","col3":"Haupstadt"}

Workflow

fc.workflow enthält Funktionen, die den Zugriff auf Funktionalitäten des Workflows erlauben.

• fc.workflow.result(nodeName)
  • Greift auf das Resultat der Aktion mit dem angegebenen Namen zu.
  • Das Resultat ist ein JSON-Wert, in der Regel ein Objekt.
  • Das Resultat hängt vom Typ der Aktion ab. Die möglichen Werte können im Workflow-Designer eingesehen werden (Info-Icon einer Aktion).
  • Erfordert, dass die Aktion bereits ausgeführt wurde und erfolgreich war. Ansonsten wird undefined zurückgeliefert.
  • [%$=JSON.stringify(fc.workflow.result("Datenbank-Statement"))%]
    • Resultat: 
    • {"rows":[{"name":"Schwarz","id":"b","hex":"000000"},{"name":"Rot","id":"r","hex":"FF0000"}], "updateCount":0}
• fc.workflow.error(nodeName)
  • Greift auf die Informationen des Fehlers der Aktion mit dem angegebenen Namen zu.
  • Das Resultat ist ein JSON-Objekt mit den Feldern
    • type - Technischer Code des Fehlers.
    • message - Nachricht oder Beschreibung des Fehlers.
    • data - Daten des Fehlers
  • Der Code und die Daten hängen vom Typ der Aktion ab. Die möglichen Fehler-Codes und deren Daten können im Workflow-Designer eingesehen werden (Info-Icon einer Aktion).
  • Erfordert, dass die Aktion bereits ausgeführt wurde und fehlgeschlagen ist. Ansonsten wird undefined zurückgeliefert.
  • [%$=JSON.stringify(fc.workflow.error("HTTP-Request"))%]
    • Resultat:
    • {"type":"NETWORK_FAILURE","data":{},"message":"Could not read server response for request to URL 'http://invalid.url'"}
• fc.workflow.event()
  • Greift auf die Daten zu, welche vom Ereignis der aktuellen Verarbeitungskette bereitgestellt werden.
  • Das Resultat ist ein JSON-Wert, in der Regel ein Objekt.
  • Das Resultat hängt von der Art des Ereignisses ab. Die möglichen Werte können im Workflow-Designer eingesehen werden (Info-Icon an einem Ereignis).
  • [%$=JSON.stringify(fc.workflow.event())%] - z.B. für eine Verarbeitungskette mit einem Button-Ereignis
    • Resultat: [{"buttonName":"btnSubmit","buttonQualifier":"btn1"}]

Benutzer

fc.user enthält Funktionen zu Nutzern, etwa dem Zugriff auf die Daten des Nutzers (eines Vorgangs) ermöglichen.

• fc.user.current
  • Greift auf die Daten des aktuellen Nutzers zurück.
  • Liefert ein Objekt mit den Daten des Nutzers zurück, analog zum Platzhalter [%$USER%].
  • Leeres Objekt, wenn nicht verfügbar.
    • [%$=JSON.stringify(fc.user.current)%]
      • Resultat:
      • {"universalReferenceId":"...","authTypeId":"form","typedId":"...","mail":"john@example.com", ...}

        
        

• fc.user.initial
  • Greift auf die Daten des Nutzers zurück, der den Vorgang erstellt hat
  • Liefert ein Objekt mit den Daten des Nutzers zurück, analog zum Platzhalter [%$INITIAL_USER%].
  • Leeres Objekt, wenn nicht verfügbar.
  • [%$=JSON.stringify(fc.user.initial)%]
    • Resultat:
    • {"universalReferenceId":"...","authTypeId":"form","typedId":"...","mail":"mary@example.com", ...}
• fc.user.last
  • Greift auf die Daten des Nutzers zurück, der den Vorgang zuletzt bearbeitet hat.
  • Liefert ein Objekt mit den Daten des Nutzers zurück, analog zum Platzhalter [%$LAST_USER%].
  • Leeres Objekt, wenn nicht verfügbar.
  • [%$=JSON.stringify(fc.user.initial)%]
    • Resultat:
    • {"universalReferenceId":"...","authTypeId":"form","typedId":"...","mail":"frodo@example.com", ...}

Platzhalter

fc.placeholders enthält Funktionen, die das Ausführen beliebiger Platzhalter erlauben.

• fc.placeholders.form(placeholderContent)
  • Führt einen Formularplatzhalter aus und liefert das Ergebnis als String zurück.
  • [%$=fc.placeholders.form("sel1_2")%] - Platzhalter [%sel1_2%]
    • Resultat: b,r
• fc.placeholders.i18n(placeholderContent)
  • Führt einen I18N-Platzhalter aus und liefert das Ergebnis als String zurück.
  • [%$=fc.placeholders.i18n("requiredCheckbox")%] - Platzhalter [%I18N.requiredCheckbox%]
    • Resultat: Dieses Feld ist ein Pflichtfeld
• fc.placeholders.template(placeholderContent)
  • Führt einen Textbaustein-Platzhalter aus und liefert das Ergebnis als String zurück.
  • [%$=fc.placeholders.template("Submission successful")%] - Platzhalter [%$$Submission successful%]
    • Resultat: <div lang="de"><div class="header">...</div></div>
• fc.placeholders.system(placeholderContent)
  • Führt einen Systemplatzhalter aus und liefert das Ergebnis als String zurück.
  • [%$=fc.placeholders.system("PROJECT_TITLE")%] - Platzhalter [%$PROJECT_TITLE%]
    • Resultat: 152
• fc.placeholders.replace(placeholder)
  • Führt einen beliebigen Platzhalter aus und liefert das Ergebnis als String zurück.
  • [%$=fc.placeholders.replace("[\u0025\u0024PROJECT_TITLE\u0025]")%] - Platzhalter [%$PROJECT_TITLE%]
    • Resultat: 152
    • % und $ müssen leider maskiert werden, da in Platzhaltern nicht erlaubt.

Datum und Uhrzeit

fc.date enthält Funktionen, die bei der Arbeit mit Datums- und Uhrzeitwerten genutzt werden können.

• fc.date.now()
  • Liefert das aktuelle Datum zurück, als Date-Objekt.
  • [%$=fc.date.now()%]
    • Resultat: Fri Mar 06 2026 00:52:10 GMT+0100 (CET)
• fc.date.format(date?, format?)
  • Formatiert ein Datum in einem bestimmten Format.
  • Wird kein Datum angegeben, wird das aktuelle Datum verwendet.
  • Wird kein Format angegeben, wird das Standardformat "dd.MM.yyyy HH:mm" verwendet.
  • Das Format muss ein gültiges SimpleDateFormat sein.
  • [%$=fc.date.format()%]- Aktuelles Datum, Standardformat
    • Resultat: 06.03.2026 00:52
  • [%$=fc.date.format("yyyy/MM/dd HH:mm")%]- Aktuelles Datum, eigenes Format
    • Resultat: 2026/03/06 00:52
  • [%$=fc.date.format(fc.form.recordCreated)%]- Erstellungsdatum des Vorgangs, Standardformat
    • 25.02.2026 17:43
  • [%$=fc.date.format(fc.form.recordCreated, "yyyy/MM/dd HH:mm")%]- Erstellungsdatum, eigenes Format

    • Resultat: 2026/02/25 17:43

Kodierung

fc.encode enthält Funktionen, die zum Maskieren (Escaping) von Werten verwendet werden können.

• fc.encode.forCss(value)
  • Kodiert einen Wert zur Nutzung innerhalb eines CSS-Strings. Der CSS-String muss mit Anführungszeichen umschlossen werden.
  • background-image: url("[%$=fc.encode.forCss("http://example.com/img.png")%]")
    • Resultat:
    • background-image: url("http:\2f\2f example.com/img.png")
• fc.encode.forCsv(value, quotationMark?)
  • Kodiert einen Wert zur Nutzung innerhalb eines zitierten CSV-Werts. Der CSV-Wert muss mit den Zitatzeichen umschlossen werden.
  • Standardmäßig wird ein doppelter Anführungsstrich (") als Zitatzeichen verwendet.
  • Bei Bedarf kann das Zitatzeichen auch angegeben werden.
  • a,"[%$=fc.encode.forCsv("b1 \"b2\" b3")%]",c
    • Resultat:
    • a,"b1 ""b2"" b3",c
• fc.encode.forHtml(value)
  • Kodiert einen Wert zur Nutzung innerhalb eines Textbereichs oder innerhalb eines Attributwerts.
  • <strong>[%$=fc.encode.forHtml("10 < 20")%]</strong>
    • Resultat>
    • <strong>10 &lt; 20</strong>
• fc.encode.forJavaScript(value)
  • Kodiert einen Wert zur Nutzung innerhalb eines JavaScript-Strings. Der String muss mit einfachen oder doppelten Anführungszeichen umschlossen werden.
  • console.log("[%$=fc.encode.forJavaScript("a \" b")%]");
    • Resultat:
    • console.log("a \x22 b");
• fc.encode.forJson
  • Kodiert einen Wert zur Nutzung innerhalb eines JSON-Strings. Der String muss mit doppelten Anführungszeichen umschlossen werden.
  • [1, "[%$=fc.encode.forJson("2\"2")%]", 3]
    • Resultat:
    • [1, "2\"2", 3]
• fc.encode.forUri
  • Kodiert einen Wert zur Nutzung innerhalb eines URI-Segments (Prozentkodierung).
  • http://example.com/[%$=fc.encode.forUri("a?b")%]?foo=bar
    • Resultat:
    • http://example.com/a%3Fb?foo=bar
• fc.encode.forXml
  • Kodiert einen Wert zur Nutzung innerhalb eines Textbereichs oder innerhalb eines Attributwerts.
  • <tag>[%$=fc.encode.forXml("->tagged")%]</tag>
    • Resultat:
    • <tag>-&gt;tagged</tag>

Kurzschreibweise für Formulardaten

Ab Version 5.1.0 des Plugins ist die obige Schreibweise über richtige JavaScript-Funktionen möglich. In älteren Version des Plugins war der Zugriff auf Formularwerte nur über eine spezielle Schreibweise möglich.

ältere Versionen (erfordert zwingend einfache Hochkommas)

[%$= 'Hallo ' + get('tfVorname') + ' ' + get('tfNachname') %]
[%$= get('selAnrede').lsttxt() %]

ab Version 5.1.0

[%$= 'Hallo ' + fc.form.value("tfVorname") + ' ' + fc.form.value("tfNachname") %]
[%$= fc.form.option("selAnrede").text %]

Zur Wahrung der Kompatibiltät steht diese ältere Schreibweise auch in neueren Versionen noch zur Verfügung.

Bei der Schreibweise get('feldName") handelt es sich nicht um eine JavaScript-Funktion! Es handelt sich dabei um eine Art Präprozessor. Vor Ausführung des JavaScript wird diese Schreibweise durch einen String mit dem Wert des Felds ersetzt.

Das birgt gewisse Probleme, u.A.: (a) keine beliebigen Parameter möglich, z.B. get("tf" + "1") oder get(variable). (b) die Schreibweise wird kontextfrei ohne Beachtung der Syntax von JavaScript ersetzt, z.B. innerhalb eines Strings wie [%$="Verwenden Sie get('tf1')"%] (c) erschwertes Debugging durch Verschleierung des eigentlich ausgeführten Codes.

In den Plugin-Eigenschaften (auf der Plugin-Seite im Backend) kann der Präprozessor deaktiviert werden, Schreibweisen wie get('...') werden dann nicht mehr vor im JavaScript-Code vor der Ausführung ersetzt.