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.

GROOVY

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).

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"))

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.

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 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	`true` or `false`
^DateValue	^Timestamp	Date – CCYY-MM-DDThh:mm:ss (http://www.edition-w3.de/TR/2001/REC-xmlschema-2-20010502/#isoformats)
^LookupValue	^{ProcessLookupData}	The `Pk` of the reference value must always be filled. The relevant internal field name (e.g. ActTypeKey.Activity) must be provided if the complete reference value, including the key field should be included in the process.
XML array	List	List of variables of the same type
`MapValue`	`Map`	Variable nesting

SOA (Simple Object Access Protocol)

Here is a sample call-up in SOAP-UI:

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>

The result contains the process instance ID and the result variables.

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>

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.