Kolumne: SharePoint ganz praktisch

Workflows mit Zuweisungs- und Startformular
Kommentare

Im fünften Teil der Serie „SharePoint ganz praktisch: Workflow“ zeigt Marc Andrè Zhou, wie man Workflows mit Hilfe der Workflowformulartypen ganz einfach parametrisiert.

Der Ablauf eines SharePoint Workflows ist in der Regel von den Werten aus der Liste abhängig, auf denen er operiert. Viele Workflows benötigen aber oft noch weitere Informationen, bevor sie ausgeführt werden können. Ein typisches Beispiel hierfür ist der klassische Freigabeprozessworkflow. Bei diesem muss dem Workflow zu Beginn zusätzlich mitgeteilt werden, welche Person oder welche Personen für die Prüfung und Freigabe herangezogen werden sollen. Theoretisch könnten diese Informationen auch in Spalten der Liste abgelegt werden, auf der der Workflow ausgeführt wird, dann müsste jedoch jede Liste zunächst um diese Spalten erweitert werden. Dieses Vorgehen wäre nicht sehr flexibel, vor allem dann, wenn nur einige Listeneinträge einen Freigabeprozess durchlaufen müssen. Um dies zu vermeiden, unterstützen SharePoint Workflows zwei Arten von Workflowformularen:

  • Zuordnungsformulare (Workflow Association Form)
  • Initiierungsformulare (Workflow Initiation Form)

Das erste Formular namens Zuordnungsformular kommt immer dann zum Einsatz, wenn ein Workflow einer Liste, Bibliothek oder Site zugewiesen wird. Die Einstellungen und Angaben, die hier gemacht werden, gelten somit für alle späteren Workflowinstanzen. So kann hierüber zum Beispiel eine E-Mail-Adresse definiert werden, an die bei jedem Workflowstart eine Benachrichtigung versendet werden soll. Das Initiierungsformular kommt dagegen immer dann zum Einsatz, wenn ein zugewiesener Workflow gestartet wird. SharePoint lädt, wenn ein solches Formular definiert wurde, dieses beim Starten des Workflows automatisch und zeigt es an. Dieser Formulartyp ist immer dann geeignet, wenn sich die Werte von Workflow zu Workflow unterscheiden. Dies trifft zum Beispiel auf den Freigabeprozessworkflow zu. Hier können bei jedem Workflowstart andere Personen für die Freigabeprüfung angegeben werden.

Erstellung eines Zuordnungsformulars

Im ersten Beispiel soll nun ein Zuordnungsformular für einen Workflow umgesetzt werden. Damit dies möglich ist, muss natürlich im Vorfeld eine SharePoint-Lösung mit einem Workflow angelegt werden. Die einzelnen Schritte dazu wurden schon in früheren Ausgaben dieser Kolumne ausführlich erläutert. Zunächst reicht hier nur die Anlage eines leeren Workflows. Anschließend kann dann mit der Anlage des ersten Formulars begonnen werden, dazu den Workfloweintrag in der Projektmappe selektieren und über die rechte Maustaste das Kontextmenü öffnen. Hier nun der Lösung ein neues Zuordnungsformular hinzufügen.

Abb. 1: Hinzufügen eines Zuordnungformulars

Abb. 1: Hinzufügen eines Zuordnungformulars

Abb. 2: Auszug aus Standard-JavaScript-Block

Abb. 2: Auszug aus Standard-JavaScript-Block

Wie Abbildung 1 zeigt, stellt Visual Studio eine Vorlage für Zuordnungsformulare direkt zur Verfügung. Unterhalb dieser ist auch schon die Vorlage für das Initiierungsformular zu sehen, dieses kommt dann im späteren Verlauf zum Einsatz. Nachdem dem Formular ein Dateiname gegeben wurde, kann es über die Add-Schaltfläche (oder Hinzufügen) der Lösung hinzugefügt werden. Visual Studio fügt neben dem Formular auch noch einen Eintrag in die elements.xml-Datei des Workflows ein. Hierbei handelt es sich um einen neuen PropertyBag-Knoten, der die Verknüpfungsinformationen zwischen Formular und Workflow beschreibt. Im Gegensatz zu vielen anderen Vorlagen enthält das gerade hinzugefügte Formular schon einigen JavaScript-Code.

Abbildung 2 zeigt einen kleinen Ausschnitt daraus. Dieser Scriptblock darf nicht großartig verändert werden. Er ist unter anderem für die korrekte Übermittlung der Parameterwerte an den Workflow verantwortlich. Weiterhin werden hier bei Bedarf benötigte Listen – wie zum Beispiel die Workflowaufgabenliste oder auch die Workflowverlaufsliste – angelegt. Ebenfalls übernimmt der Codeblock die korrekte Initialisierung des Workflows. Daher darf hier lediglich die Methode associateWF angepasst werden. In dieser Methode müssen die konkreten Formularwerte dem Workflow mitgeteilt werden. Die notwendigen Anpassungen werden durchgeführt, nachdem das Formular angepasst wurde. Oberhalb des Script-Blocks sind schon beispielhaft drei Formularwerte unterschiedlichster Typen (Zeichenkette, Zahl und Datum) eingefügt. Dieser Bereich kann natürlich frei angepasst werden. Nur die beiden Schaltflächen sollten nicht geändert werden.

Für das aktuelle Beispiel sollen Texte für eine E-Mail-Nachricht und ein Datumswert über das Formular erfasst werden. Der so angepasste Formularbereich ist in Listing 1 zu sehen. Als Nächstes muss nun die angesprochene Methode associateWF erweitert werden. Das Listing 2 zeigt die durchgeführten Anpassungen. Das Formular ist somit vorbereitet und einsatzbereit. Im nächsten Schritt wird nun das Initiierungsformular erstellt.

zhou_sp_flow_2

Abb. 2: Auszug aus Standard-JavaScript-Block

<h1>Workflow Einstellungen</h1>
<table>
  <tr>
    <td>
      <label id="lblEMailSubject" for="txtEMailSubject">E-Mail Betreff</label>
    </td>
    <td><input type="text" id="txtEMailSubject" style="width: 450px;" /></td>
  </tr>
  <tr>
    <td><label id="lblEMailText" for="txtEMailText">E-Mail Text</label></td>
    <td><textarea rows="10" cols="80" id="txtEMailText"></textarea></td>
  </tr>
  <tr>
    <td colspan="2">WF-Datum: <SharePoint:DateTimeControl ID="wfDateTime" DatePickerFrameUrl="../_layouts/15/iframe.aspx" LocaleId="1033" DateOnly="false" runat="server"  /><br /><br />
    </td>
  </tr>
  <tr>
    <td><button id="Save" onclick="return runAssocWFTask()">Save</button></td>
    <td><button id="Cancel" onclick="location.href = cancelRedirectUrl; return false;">Cancel</button></td>
  </tr>
</table>
var strInputValue = document.getElementById("txtEMailSubject").value;
if (strInputValue) {
  metadata['EMailSubject'] = strInputValue;
}
strInputValue = document.getElementById("txtEMailText").value;
if (strInputValue) {
  metadata['EMailText'] = strInputValue;
}
var dateTimeInputValue = document.getElementById("...").value;
if (dateTimeInputValue) {
  var dateTimeValue = new Date(document.getElementById("...").value);
  if (dateTimeValue)
    metadata['WFDateTime'] = dateTimeValue;
}

Erstellung eines Initiierungsformulars

Die Schritte für die Erstellung eines Initiierungsformulars gleichen der zuvor beschriebenen Vorgehensweise. Auch hier muss zunächst dem Workflow ein neues Element hinzugefügt werden. Wie in Abbildung 1 zu sehen ist, existiert auch für ein Initiierungsformular bereits eine entsprechende Visual-Studio-Vorlage. Diese ist nun hier zu wählen. Nachdem ein gültiger Dateiname für das neue Formular angegeben wurde, kann es dem Workflow über die Schaltfläche Add („Hinzufügen“) hinzugefügt werden. Visual Studio fügt daraufhin auch wieder die neue Verknüpfungsinformation der elements.xml-Datei des Workflows hinzu.

Im unteren Bereich enthält das neue Formular wiederum einen JavaScript-Codeblock, der nicht großartig verändert werden darf. Die Ausnahme bildet in diesem Fall die Methode StartWorkflow. Sie übermittelt die definierten Einstellungswerte beim Starten des Workflows an die neue Workflowinstanz. Diese Methode wird nach der Erstellung des Formulars noch an die neuen Formularfelder angepasst.

Der obere Bereich mit den HTML-Formularsteuerelementen kann natürlich wieder frei an eigene Anforderungen angepasst werden. Nur die beiden Schaltflächen sollten auch hier nicht geändert werden. Wie bereits erläutert wurde, soll der Workflow beim Starten eine E-Mail an eine beliebige Person versenden. Daher muss beim Starten des Workflows die E-Mail-Adresse abgefragt und an den Workflow übergeben werden. Dazu wird das Initiierungsformular gemäß Listing 3 vorbereitet. Benötigt wird an dieser Stelle lediglich ein einfaches Eingabefeld. Anschließend muss die Methode StartWorkflow – wie in Listing 4 zu sehen ist – erweitert werden. Der bestehende Code zum Auslesen der Formularwerte muss hier an die eigenen Formularfelder angepasst werden. Das Vorgehen ist mit dem weiter oben beschriebenen Formular vergleichbar.

<h1>Workflow Einstellungen für den Start</h1>
<table>
  <tr>
    <td>
      <label id="lblReceiver" for="txtEMailAddress">E-Mail Adresse</label>
    </td>
    <td><input type="text" id="txtEMailAddress" style="width: 450px;" /></td>
  </tr>
  <tr>
    <td>
      <input type="button" name="startWorkflowButton" value="Start" onClick="StartWorkflow()" />
      <input type="button" name="cancelButton" value="Cancel" onClick="RedirFromInitForm()" />
    </td>
  </tr>
</table>
var wfParams = new Object();
var strInputValue = document.getElementById("txtEMailAddress").value;
if (strInputValue) {
  wfParams['EMailAddress'] = strInputValue;
}

Zugriff auf die Formulardaten

Nachdem nun die beiden Formulare dem Workflow hinzugefügt wurden, muss der Workflow in die Lage versetzt werden, auf die eingegebenen Informationen zugreifen zu können. Dies ist nicht sonderlich kompliziert, da hierfür eine spezielle Workflowaktivität namens GetConfigurationValue bereitsteht. Zunächst müssen für alle definierten Formularfelder entsprechende Workflowvariablen erstellt werden. Benötigt werden die folgenden Variablen jeweils vom Datentyp Zeichenkette (String):

  • EMailSubject
  • EMailText
  • WFDateTime
  • EMailAddress

Anschließend kann die oben genannte Aktivität zum Einsatz kommen, um alle Werte auszulesen. Die Aktivität erwartet dazu folgende Parameter (Abb. 3):

  • (Optionaler) Standardwert (DefaultValue)
  • Anzeigename (DisplayName)
  • Name
  • Ergebnis (Result)

Über den Parameter „Standardwert“ kann – wie der Name schon vermuten lässt – ein Wert definiert werden, der zum Einsatz kommt, wenn keine Angabe über das Formular erfolgte. Der Anzeigename kann frei gewählt werden, sollte aber einen Bezug zum Formularwert haben. Die Eigenschaft „Name“ bestimmt nun, welcher Formularwert ausgelesen werden soll. Dieser ergibt sich aus der metadata-Auflistung, die in Listing 2 erstellt wurde. Um zum Beispiel den E-Mail-Betreff auszulesen, ist der Name EMailSubject anzugeben, da er wie folgt aus dem HTML-Formular übernommen wurde:

metadata['EMailSubject'] = strInputValue;

Nach diesem Muster werden alle vier Formularwerte ausgelesen. Abbildung 4 zeigt den so entstandenen Workflow, der lediglich die Formularwerte einliest und über einen Logeintrag ausgibt.

Abb. 3: Auslesen von Formularwerten innerhalb des Workflows

Abb. 3: Auslesen von Formularwerten innerhalb des Workflows

Abb. 4: Der gesamte Workflow

Abb. 4: Der gesamte Workflow

Workflow testen

Die beiden Formulare sind nun einsatzbereit und können getestet werden. Dazu kann das Projekt direkt aus Visual Studio heraus ausgeführt werden. Damit das Zuordnungsformular getestet werden kann, sollte auf die automatische Aktivierung verzichtet werden. Nachdem die Lösung installiert (deployt) wurde, kann zum Beispiel der neue Workflow einer Dokumentenbibliothek hinzugefügt werden. Dazu sind die Einstellungen der Dokumentenbibliothek aufzurufen und über den Link Workfloweinstellungen ein neuer Workflow hinzuzufügen.

Auf der nachfolgenden Seite ist dem Link Workflow Hinzufügen zu folgen. Anschließend kann der neue Workflow der Bibliothek hinzugefügt werden. Hier ist schon an der unteren Schaltfläche Weiter erkennbar, dass ein spezielles Zuordnungsformular existiert. Wurden auf der Standardseite alle Angaben gemacht, wird mit dem Aufruf dieser Schaltfläche das eigene Zuordnungsformular geladen. Wurden auch hier alle Angaben gemacht, kann der Vorgang über die Save-Schaltfläche abgeschlossen werden. Nun kann auf einen Eintrag der Bibliothek hin der Workflow gestartet werden. Dazu einen beliebigen Eintrag auswählen und über das Kontextmenü zu den Workflows wechseln.

Auf der Übersichtsseite der Workflows den gerade hinzugefügten Workflow starten. Bevor nun der Workflow startet, wird, wie auch die Abbildung 5 zeigt, das eigene Initiierungsformular geladen und angezeigt. Nachdem die benötigte Information eingetragen wurde, kann über die Start-Schaltfläche der Workflow gestartet werden. Der Workflow wird relativ rasch beendet, da lediglich die erfassten Parameterwerte ausgegeben werden. Diese landen zur Kontrolle in der Verlaufsliste des Workflows, wie aus Abbildung 6 hervorgeht. Damit ist der Test des Workflows erfolgreich beendet.

Abb. 5: Darstellung des Initiierungsformulars

Abb. 5: Darstellung des Initiierungsformulars

Abb. 6: Ausgabe der Formularwerte

Abb. 6: Ausgabe der Formularwerte

Zusammenfassung

Wie gezeigt wurde, bieten die beiden Workflowformulartypen die einfache Möglichkeit, einen Workflow zu parametrisieren. Einstellungen, die bei jedem Workflowstart zum Einsatz kommen sollen, werden hierbei über das Zuordnungsformular definiert. Alle weiteren Einstellungen, die nicht anderweitig bezogen werden können, werden dem Workflow über das Initiierungsformular mitgegeben. Die Anlage und das Auslesen der Einstellungen aus den beiden Formulartypen sind sehr einfach über die verfügbaren Workflowaktivitäten möglich. Workflowformulare ermöglichen somit die einfache Konfiguration von Workflows. Zu beachten ist lediglich, dass Initiierungsformulare nicht verwendet werden können, wenn ein Workflow automatisch gestartet werden soll.

Windows Developer

Windows DeveloperDieser Artikel ist im Windows Developer erschienen. Windows Developer informiert umfassend und herstellerneutral über neue Trends und Möglichkeiten der Software- und Systementwicklung rund um Microsoft-Technologien.

Natürlich können Sie den Windows Developer über den entwickler.kiosk auch digital im Browser oder auf Ihren Android- und iOS-Devices lesen. In unserem Shop ist der Windows Developer ferner im Abonnement oder als Einzelheft erhältlich.

Unsere Redaktion empfiehlt:

Relevante Beiträge

Meinungen zu diesem Beitrag

X
- Gib Deinen Standort ein -
- or -