Web service in CURSOR-BPM
BPM process start via web service
Overview
An external application can utilize the web service published by CURSOR-CRM to start a targeted BPM process and to transfer data to it.
The data is transferred as a list of elements in the format Name/Type/Value, which means it is not a nested data structure.
The process caller logs in with the name and password of a CRM user. We therefore recommend creating a special user for this particular purpose and with the required access rights.
Structure of the BPM process
Start event
Type: System start (web service, timer)
Condition script: In the following example, the script checks the start event to ensure that the process caller has provided all expected parameters.
return ProcessUtils.isVariableSet("parameter1")
&& ProcessUtils.isVariableSet("parameter2")
&& ProcessUtils.isVariableSet("parameter3")
&& ProcessUtils.isVariableSet("parameter4")
&& ProcessUtils.isVariableSet("parameter5")
&& ProcessUtils.isVariableSet("parameter6");
Output parameter: The web service caller can have result variables returned as output parameters.
The output variables must be populated in the work step following the start result.
Script task
The forwarded parameters are available as variables.
Note: The forwarded parameters in this example are named parameter1, etc. The names are freely configurable, as long as they don't conflict with internal variable names (e.g. eventName
).
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"))
Call-up from the viewpoint of the external caller
The method startProcess can be triggered via web service. This call is the same as ProcessUtils.startProcess(processID, params, version, callback). Since, however, a call-up is generally not initiated from within CRM, the locale to be used must also be transmitted.
WSDL (Web Services Description Language)
The Web service can be called at the following URL: http://[HOST]:[PORT]/soap/ProcessWebService?wsdl
Method: startProcess
Parameter: processWebParameter (ProcessWebParameter)
ProcessId: The ID of the process
Locale: The language used for process execution (de, en, sl, it, fr)
AutoOpenUserTask: This option automatically opens the first user task in the process for the user
Parameter: The process variables
The values of the process variables are specified in a specific data field.
<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 data type | Description |
---|---|---|
StringValue | String | Any character string. XML text and line breaks embedded in CDATA are also possible. |
IntValue | Integer | Integer |
DoubleValue | Double | Decimal number ("." is the decimal separator) |
BooleanValue | Boolean |
|
DateValue | Timestamp | Date – CCYY-MM-DDThh:mm:ss (http://www.edition-w3.de/TR/2001/REC-xmlschema-2-20010502/#isoformats) |
LookupValue | ProcessLookupData | The |
XML array | List | List of variables of the same type |
|
| Variable nesting |
SOA (Simple Object Access Protocol)
Here is a sample call-up in SOAP-UI:
<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>
The result contains the process instance ID and the result variables.
<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>
Web service interface and sessions
It is also possible to start and continue your own processes in the system via the web service call interface. But this requires significantly more resources than calling ProcessUtils.startProcess
and also causes problems when logging on to your own system. In these web service calls the function enableLoginViaCurrentUser(true)
can only be used to a very limited extent.
If a BPM process is started by the timer action or processes are continued asynchronously, it is an anonymous session that does not contain a valid session token in order to be able to log on to the CRM again using a web service.
To do this, the logon information must be stored in the web service definition.