Web Service in CURSOR-BPM

BPM-Prozess durch Webservice starten

Übersicht

Eine externe Anwendung kann den von CURSOR-CRM veröffentlichten Webservice nutzen, um gezielt einen BPM-Prozess zu starten und ihm Daten zu übergeben.

Die Übergabe der Daten erfolgt als Liste von Elementen der Form Name/Typ/Wert, es ist also keine verschachtelte Datenstruktur.

Der Aufrufer meldet sich mit dem Namen und Passwort eines CRM-Benutzers an. Es ist daher empfehlenswert, einen speziellen Benutzer nur für diesen Zweck und mit den notwendigsten Zugriffsrechten anzulegen.

Aufbau des BPM-Prozesses

Start-Ereignis

Typ: System-Start (Web Service, Timer)

Bedingungs-Script: Im folgenden Beispiel prüft das Script des Start-Ereignisses, ob der Aufrufer alle erwarteten Parameter angegeben hat.

GROOVY

return ProcessUtils.isVariableSet("parameter1")
  && ProcessUtils.isVariableSet("parameter2")
  && ProcessUtils.isVariableSet("parameter3")
  && ProcessUtils.isVariableSet("parameter4")
  && ProcessUtils.isVariableSet("parameter5")
  && ProcessUtils.isVariableSet("parameter6");

Ausgabeparameter: Dem Webservice-Aufrufer können Ergebnisvariablen als Ausgabeparameter zurückgegeben werden.

Die Ausgabevariablen müssen im Verarbeitungsschritt nach dem Startereignis gefüllt werden.

Skript-Task

Die übergebenen Parameter sind als Variablen verfügbar.

Hinweis: die übergebenen Parameter heißen in diesem Beispiel parameter1 usw. Die Namen sind aber frei wählbar, solange sie nicht mit internen Variablennamen (etwa eventName) in Konflikt geraten.

GROOVY

ProcessUtils.setVariable("string2", ProcessUtils.getVariable("string1"))
ProcessUtils.setVariable("longstring2", ProcessUtils.getVariable("longstring1"))
ProcessUtils.setVariable("int2", ProcessUtils.getVariable("int1"))
ProcessUtils.setVariable("double2", ProcessUtils.getVariable("double1"))
ProcessUtils.setVariable("boolean2", ProcessUtils.getVariable("boolean1"))
ProcessUtils.setVariable("date2", ProcessUtils.getVariable("date1"))
ProcessUtils.setVariable("lookup2", ProcessUtils.getVariable("lookup1"))
ProcessUtils.setVariable("lookup3", LookupUtils.getKey(ProcessUtils.getVariable("lookup1")))
ProcessUtils.setVariable("map2", ProcessUtils.getVariable("map1"))
ProcessUtils.setVariable("submap2", ProcessUtils.getVariable("map1").get("submap1"))

Aufruf aus Sicht des externen Aufrufers

Per Web Service kann die Methode startProcess angesprochen werden. Dieser Aufruf ist analog zu dem Aufruf ProcessUtils.startProcess(processID, params, version, callback). Da hier jedoch der Aufruf im Allgemeinen nicht aus dem CRM erfolgt, muss das zu nutzende Locale noch mit übergeben werden.

WSDL (Web Services Description Language)

Der Web Service ist unter der folgenden URL aufrufbar: http://[HOST]:[PORT]/soap/ProcessWebService?wsdl

Methode: startProcess

Parameter: processWebParameter (ProcessWebParameter)

ProcessId: Die ID des Prozesses
Locale: Die Sprache, mit welcher der Prozess ausgeführt wird (de, en, sl, it, fr)
AutoOpenUserTask: Mit dieser Option wird die erste Benutzeraktion im Prozess automatisch beim Anwender geöffnet
Parameter: Die Prozessvariablen

Werte der Prozessvariablen werden im konkreten Datenfeld spezifiziert.

HTML/XML

<xs:complexType name="ProcessVariable">
  <xs:sequence>
    <xs:element name="Name" type="xs:string" />
    <xs:element name="Value" type="ProcessVariableData" />
  </xs:sequence>
</xs:complexType>

<xs:complexType name="ProcessVariableData">
  <xs:choice>
    <xs:element name="StringValue" type="xs:string" />
    <xs:element name="IntValue" type="xs:integer" />
    <xs:element name="DoubleValue" type="xs:decimal" />
    <xs:element name="BooleanValue" type="xs:boolean" />
    <xs:element name="DateValue" type="xs:dateTime" />
    <xs:element name="LookupValue" type="ProcessLookupData" />
    <xs:element name="MapValue" type="ProcessVariableArray"/>
  </xs:choice>
</xs:complexType>  

<xs:complexType name="ProcessLookupData">
  <xs:sequence>
    <xs:element name="Pk" type="xs:string" />
    <xs:element name="FieldName" type="xs:string" minOccurs="0" maxOccurs="1" />
  </xs:sequence>
</xs:complexType>
 
<complexType name="ProcessVariableArray">
  <xs:sequence>
    <xs:element name="item" type="ProcessVariable" maxOccurs="unbounded" minOccurs="0"/>
  </xs:sequence>
</complexType>

Parameter	java Datentyp	Beschreibung
^StringValue	^String	Eine beliebige Zeichenfolge. Auch XML-Text und Zeilenumbrüche eingebettet als CDATA sind möglich.
^IntValue	^Integer	Ganzzahl
^DoubleValue	^Double	Dezimalzahl ('.' ist das Dezimalsymbol)
^BooleanValue	^Boolean	`true` oder `false`
^DateValue	^Timestamp	Datum - CCYY-MM-DDThh:mm:ss (http://www.edition-w3.de/TR/2001/REC-xmlschema-2-20010502/#isoformats)
^LookupValue	^{ProcessLookupData}	Der `Pk` des Nachschlagewertes ist immer zu füllen. Wünscht man im Prozess den vollständigen Nachschlagewert mit Schlüsselfeld und Beschreibung, muss der passende interne Feldname (z.B. ActTypeKey.Activity) angegeben werden.
XML Array	List	Liste von Variablen gleichen Typs
`MapValue`	`Map`	Verschachtelung von Variablen

SOA (Simple Object Access Protocol)

Ein Beispiel-Aufruf in SOAP-UI sieht folgendermaßen aus:

HTML/XML

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://web.process.cursor.de/" xmlns:var="http://variable.process.common.jevi.cursor.de/">
<soapenv:Header/><soapenv:Body>
        <web:startProcess>
            <var:processWebParameter>
                <ProcessId>webservice</ProcessId>
                <Locale>de</Locale>
                <AutoOpenUserTask>true</AutoOpenUserTask>  <!-- optional -->
                <Parameter>
                    <item><Name>string1</Name><Value><StringValue>abcde</StringValue></Value></item>
                    <item><Name>longstring1</Name><Value><StringValue><![CDATA[Langer Text
mit Umbruch
und <b>XML</b>-Zeichen]]></StringValue></Value></item>
                    <item><Name>int1</Name><Value><IntValue>123</IntValue></Value></item>
                    <item><Name>double1</Name><Value><DoubleValue>45.67</DoubleValue></Value></item>
                    <item><Name>boolean1</Name><Value><BooleanValue>true</BooleanValue></Value></item>
                    <item><Name>date1</Name><Value><DateValue>2014-10-14T15:27:00</DateValue></Value></item>
                    <item><Name>lookup1</Name><Value><LookupValue><Pk>S_ACTSTATUS-O</Pk><FieldName>ActStatusKey.Activity</FieldName></LookupValue></Value></item>
                    <item><Name>map1</Name><Value><MapValue>
                        <item><Name>string11</Name><Value><StringValue>abcde</StringValue></Value></item>
                        <item><Name>submap1</Name><Value><MapValue>
                            <item><Name>string111</Name><Value><StringValue>abcde</StringValue></Value></item>
                        </MapValue></Value></item>                                   
                    </MapValue></Value></item>               
                  </Parameter>
            </var:processWebParameter>
        </web:startProcess>
    </soapenv:Body>
</soapenv:Envelope>

Das Ergebnis enthält die Prozessinstanz-ID und die Ergebnisvariablen.

XML

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body><ns3:startProcessResponse xmlns:ns2="http://variable.process.common.jevi.cursor.de/" xmlns:ns3="http://web.process.cursor.de/">
            <ns2:processWebResult>
                <InstanceId>5f4b293e-5516-11e4-9724-c86000771447</InstanceId>
                <ExecutionId>5f4a174e-5516-11e4-9724-c86000771447</ExecutionId>
                <ProcessStatus>ENDED</ProcessStatus>
                <ResultParameter>
                    <item><Name>string2</Name><Value><StringValue><![CDATA[abcde]]></StringValue></Value></item>
                    <item><Name>longstring2</Name><Value><StringValue><![CDATA[Langer Text
mit Umbruch
und <b>XML</b>-Zeichen]]></StringValue></Value></item>
                    <item><Name>int2</Name><Value><IntValue>123</IntValue></Value></item>
                    <item><Name>double2</Name><Value><DoubleValue>45.67</DoubleValue></Value></item>
                    <item><Name>boolean2</Name><Value><BooleanValue>true</BooleanValue></Value></item>
                    <item><Name>date2</Name><Value><DateValue>2014-10-14T15:27:00.000+02:00</DateValue></Value></item>
                    <item><Name>lookup2</Name><Value><LookupValue><Pk>S_ACTSTATUS-O</Pk></LookupValue></Value></item>
                    <item><Name>lookup3</Name><Value><StringValue><![CDATA[O]]></StringValue></Value></item>
                    <item><Name>map2</Name><Value><MapValue>
                        <item><Name>submap1</Name><Value><MapValue>
                            <item><Name>string111</Name><Value><StringValue>abcde</StringValue></Value></item>
                        </MapValue></Value></item>
                        <item><Name>string11</Name><Value><StringValue>abcde</StringValue></Value></item>
                    </MapValue></Value></item>
                    <item><Name>submap2</Name><Value><MapValue>
                        <item><Name>string111</Name><Value><StringValue>abcde</StringValue></Value></item>
                    </MapValue></Value></item>
                    <item><Name>empty</Name></item>
                </ResultParameter>
            </ns2:processWebResult>
        </ns3:startProcessResponse>
    </soap:Body>
</soap:Envelope>

Webservice-Schnittstelle und Sessions

Es ist auch möglich eigene Prozesse im System über die Webservice-Aufruf-Schnittstelle zu starten und weiterzuführen. Doch dies benötigt deutlich mehr Ressourcen als der Aufruf von ProcessUtils.startProcess und bringt auch Probleme bei der Anmeldung am eigenen System mit sich. In diesen Webservice Aufrufen kann die Funktion enableLoginViaCurrentUser(true) nur sehr eingeschränkt genutzt werden.

Wird eine BPM-Prozess durch die Timer-Aktion gestartet oder Prozesse asynchron weitergerführt, so handelt es sich um eine anonyme Session, die keine gültiges Session-Token enthält, um sich per Webservice am CRM erneut anmelden zu können.

Hierfür müssen die Anmelde-Informationen in der Webservice-Definition hinterlegt werden.