Skripte in 3C-Modulen

Grundlegende Fragestellungen

Bei der Erstellung von 3C-Modulen müssen im Maskenskript und BPM die folgenden Fragestellungen besonders beachtet werden:

• Muss ein Skript vom Kunden erweitert werden können?

• Muss eine Logik beim Kunden übersteuert werden können?

• Sollen Logiken beim Kunden konfiguriert werden können?

Wann nutze ich eine Skript-Bibliothek?

• Der Code wird wiederverwendet

• Der Code soll übersteuert oder erweitert werden können

• Eine Logik soll automatisch getestet werden

Best Practice

Namenskonventionen für Skript-Bibliotheken im Modulbau

Wie alle Customizings sollte bei Skript-Bibliotheken direkt auf den ersten Blick erkennbar sein, zu welchem Modul diese gehören und welchen Zweck sie dient.

Beispiele für Module C11SURVEYS. 

• Für C11SURVEYS wurde sich auf das Kürzel C11SV geeinigt.

• C11SVUtils - Wenn nur eine Bibliothek im Modul benötigt wird.

• C11SVCloudUtils - Skript-Bibliothek für den CURSOR Service Cloud Zugriff

• C11SVConfigUtils - Skript-Bibliothek für die Konfiguration des Umfragen Moduls

Strukturierung von Code

Für die Lesbarkeit von Code sollte dieser in private Methoden unterteilt werden, die wiederum dokumentiert sind und einen sprechenden Namen tragen. Dies lehnt sich an die bestehenden Coding-Konventionen an.

void entryLoaded()
{
  disableTicketFields();
}

/** Change enable state of ticket fields according to ticket type. */
void disableTicketFields()
{
  if (isSupportTicket())
  ...
}

/** Returns true if ticket type is "SUPPORT_TICKET" */
boolean isSupportTicket()
{
  ...
}

Nur wenn der Code übersteuert werden soll, ist dieser in einer Skript-Bibliothek auszulagern. Zur reinen Code Strukturierung ist das Auslagern nicht notwendig, und die Übersicht in der Bibliothek geht verloren.

Im Beispiel ist der Schlüssel für ein Supportticket kundenspezifisch und muss in der Skript-Bibliothek übersteuert werden. 

void entryLoaded()
{
  disableTicketFields();
}

/** Change enable state of ticket fields according to ticket type. */
void disableTicketFields()
{
  if (SC11ModulIdUtils.isSupportTicket())
  ...
}

Eine Auslagerung von Code in Teilprozesse, die nur einen Skript-Task beinhalten, wirkt sich negativ auf die Performance aus. Hier sollte immer eine Skript-Bibliothek genutzt werden.

Konfiguration von Logiken

Einstellungen in Modulen können zum einen über Globale Variablen und Konfigurationsparameter in einer Skript-Bibliothek erfolgen. 

Globale Variablen sollten dann zum Einsatz kommen, wenn sich die Einstellungen im Test- und Produktivsystem unterscheiden können. Auch in Bereichen, die keine Skripte nutzen, müssen Globale Variablen genutzt werden.

String searchKey = (String) VariableUtils.getGlobalVariable("C11<ModuleId>_SearchKey");
IScriptWorkSpace ws = WorkSpaceScriptUtils.search(searchKey);
...

Sind die Einstellungen über alle Systeme identisch, so sollte die Konfiguration für Skript-Logiken in einer Skript-Bibliothek zum Modul hinterlegt werden.

Konfiguration in Skript-Bibliothek

public class SC11<ModuleId>Utils
{
  private Object config(String key)
  {
	Map<String, Object> configMap = new HashMap<>();
    // Documentation of the parameter in english
    configMap.put("searchKey", "Value");
    ...

    return configMap.get(key);
  }

  public String configSearchKey()
  {
    return (String) config("searchKey");
  }
}

Im Skripte kann dann direkt auf die Konfiguration zugreifen.

String searchKey = SC11<ModulId>Utils.configSearchKey();
IScriptWorkSpace ws = WorkSpaceScriptUtils.search(searchKey);
...

Vermeidung von (unnötigen) Abhängigkeiten

Der Zugriff auf Prozess-Variablen ist innerhalb der Skript-Bibliothek unbedingt aus folgenden Gründen zu vermeiden.

1. Soll die Methode, die den Zugriff macht, wiederverwendet werden, muss sie zwingend auch diese Prozess-Variable vorfinden - diese erschwert die Wiederverwendbarkeit.

2. Für einen Test der Methode stellt der Zugriff auf eine solche Variable auch ein Problem dar, da sie im Testumfeld nicht zur Verfügung steht.

3. Es werden Seiteneffekt und Laufzeitfehler vermieden, nur weil im aufrufenden Prozess die Verwendung der Variablen geändert wurde.

Generell ist eine zustandslose Programmierung in der Skript-Bibliothek zu empfehlen. Dies bedeutet zwar, dass mehr Parameter übergeben werden müssen, stellt aber sicher, dass die Funktionalität wirklich wiederverwendbar ist. Ein weiterer Vorteil ist die bessere Verständlichkeit, da ja nicht auf eine "nebulöse" Variable zugegriffen wird, sondern ein wohldefinierter und dokumentierter Übergabeparameter zur Verfügung steht.

Zugriff mit unnötiger Abhängigkeit

/**
 * Creates a HTML message from specified activity type.
 *
 * @return The formatted HTML message.
 */
String getHtmlActTypeMessage()
{
  String actType = ProcessUtils.getVariable("actType");
  return "<html><body>" + I18nUtils.i18nCustom("SC11EXActTypeMsg", SessionConstants.LOCALE, actType) + "</html></body>";
}

Zugriff ohne Abhängigkeit

/**
 * Creates a HTML message from specified activity type.
 *
 * @param actType The activity type lookup key.
 *
 * @return The formatted HTML message.
 */
String getHtmlActTypeMessage(ILookup actType)
{
  String actTypeKey = LookupUtils.getKey(actType);
  return "<html><body>" + I18nUtils.i18nCustom("SC11EXActTypeMsg", SessionConstants.LOCALE, actTypeKey) + "</html></body>";
}

Verwendung einer Basis-Implementierung und Ausprägung spezieller Module

Für die Anforderung, dass eine einheitliche Basis-Implementierung vorliegen soll, die aber über weitere Module individuell ausgeprägt werden sollen, kann es sinnvoll sein, mehrere Skript-Bibliotheken zum gleichen Basis-Modul aufzubauen.

Im Basis-Modul werden in einem solchen Fall die gemeinsamen Methoden implementiert sowie Aufruf-Methoden, die die eigentliche Aufgabe in spezifische Skript-Bibliotheken delegieren. Hierbei ist es sinnvoll alle öffentlichen Basis-Modul-Methoden in den spezifischen Skript-Bibliotheken ebenfalls vor zu sehen.

Beispiel:

Für ein Modul C11EXAMPLE (abgekürzt mit EX) werden die gemeinsamen Methoden in der Skript-Bibliothek SC11EXBase bereit gestellt. Die spezifischen Ausprägungen liegen in weiteren Skript-Klassen, die entsprechend der spezifischen Ausprägung benannt werden können z. B. SC11EXModul1, SC11EXModul2. Zudem ist es möglich weitere Kundenseitige Modul-Erweiterungen auf diese Weise aufzurufen.

/**
 * Proxy method to call specialized method implementations.
 * The logic to fill specified customer container is implemented in specialized script library.
 *
 * @param pk The primary key of customer to search for.
 *
 * @return The filled customer container.
 */
IContainer getCustomerData(Map<String, Object> context, String pk)
{
  return ScriptUtils.callScriptClass(SC11EXBase.getScriptClassName(context), "getCustomerData", pk);
}

/**
 * Reads and returns the name of the script class to be called from the given context.
 *
 * @return The contextual name of the script class
 */
String getScriptClassName(Map<String, Object> context)
{
  return context.get("specificModule");
}