Skip to main content
Skip table of contents

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.

CRM-849_ResultConfig2.png

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.