Process Interface - External Invocation Mechanism

A Web Service endpoint is provided for all processes in deployed models defining a Process Interface and being marked for exposure via Web Service endpoint. The WSDL is the same as displayed in Process Interface Definition.

The external invocation mechanism is provided to:

These services can be invoked via:

SOAP Web Service for Process Interface

You can start a process instance and retrieve process instance results using the SOAP Web service operation.

The SOAP Web service can be used for both starting a process instance and retrieving the process instance' results after it has been completed. This Web Service is available for each process interface that has been marked to be exposed via a SOAP Web Service.

Starting a Process Instance

Process Name: startProcess<Process Definition ID>

Parameters:

Return Value: . depends on the primary implementation set for the process interface. The return value also depends on the OUT and INOUT formal parameters defined for process interface and synchronous invocation. The result is returned if the

Retrieving Process Instance Results

Process Name: getProcessResults<Process Definition ID>

Parameter: the OID of the process instance for which the result should be retrieved

Return Value: if the process instance is completed the OUT and INOUT formal parameters as defined in the corresponding WSDL

WSDL Granularity

A one-to-one relationship is maintained between an XPDL model file and the corresponding WSDL file. The WSDL file is generated based on the XPDL model. It reflects all the process interfaces the model exposes. Since the WSDL contains two Web service operations per Process Definition the Web service operation's name should be post-fixed to ensure uniqueness within a WSDL file. It should be post-fixed because a model and WSDL file has one-to-one relationship. It may contain more than one process definition that exposes a process interface. A unique WS operation's name sets it apart from the WS operation names of the other process definitions. For more information, please refer to the section Providing Process Interface of the chapter Working with Process Interface of the Modeling Guide.

Web Services SOAP Invocation for Process Interface Listing

Web services SOAP invocation for Process Interface listing is performed via:

http://<host>:<port>/<context root>/services/soap/services

For example:

http://localhost:8080/ipp/services/soap/services

The process interface listing for the default partition is exposed.

Partition aware listing

The Web services SOAP invocation also supports a partition aware listing. If the invocation should be partition aware, add the specific partition in the following way:

http://<host>:<port>/<context root>/services/soap/services?partition=<partition>

For example:

http://localhost:8080/ipp/services/soap/services?partition=partition1

Listing static services

By adding the query parameter static, the static services can be listed also. To list static endpoints, e.g. Web Service API, which is always available for all partitions, use:

http://<host>:<port>/<context root>/services/soap/services?static

For example:

http://localhost:8080/ipp/services/soap/services?static

SOAP Web Service Endpoints

The following endpoints are provided for the aforementioned Web service operations for the process interface to be exposed.

Preferences

Please note that all the following preferences are loaded only once during the bootstrap of the WS facility. That means after the bootstrap operation, changes to these preferences do not take effect until the WS facility has been restarted.

Following is the example for preferences:

<preferences id="process-interface" module="web-service">
<preference name="DynamicEndpoint.DefaultModelId">ProviderModel_WS</preference>
<preference name="DynamicEndpoint.HttpBasicAuth.Enable" type="boolean">true</preference>
</preferences>

For more information on preferences, please refer to the Retrieving and Changing Preferences chapter.

Selecting a Specific Web Service Endpoint WSDL

Selecting a Specific Web Service Endpoint Process

Supported Data Types

The primitive and structured data types are supported as parameters and return types.

SOAP Binding

Document/Literal is used.

Specifying Technical User

Specify the technical user in the carnot.properties file because to generate WSDL, the user should have access to APIs. The technical user should have the permission readModelData to retrieve the formal parameters and type declarations from the model.

Setting Synchronization Interval

The interval specifies the minimum interval in seconds that has to pass before synchronizing the Web service endpoints and WSDLs with the engine's deployed models. Synchronization takes place only if a WSDL (HTTP GET) or Web service (HTTP POST) request takes place and the synchronization interval has passed. A value can be defined in the property WebService.ProcessService.EndpointSyncPeriod of carnot.properties file. The default value is 10 (seconds).

SOAP Endpoint Examples

Following are the typical examples of SOAP request and response.

SOAP Request to Start Process

URL - http://localhost:9890/ipp-portal/services/soap/ProcessServiceHttpBasicAuth?wsdl

<soapenv:Envelope xmlns:prov="http://infinity.com/bpm/models/generated/ProviderModel_WS" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header/>
   <soapenv:Body>
      <prov:startProcessPrimitiveProcess>
         <prov:Args>
            <prov:FormalParameter_1>abc</prov:FormalParameter_1>
            <prov:FormalParameter_2>123</prov:FormalParameter_2>
         </prov:Args>
      </prov:startProcessPrimitiveProcess>
   </soapenv:Body>
</soapenv:Envelope>

SOAP Response of Start Process

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <startProcessResponsePrimitiveProcess xmlns="http://infinity.com/bpm/models/generated/ProviderModel_WS">
         <ProcessInstanceOid>205</ProcessInstanceOid>
         <Return>
            <FormalParameter_3>Function of provider get Called :abc 123</FormalParameter_3>
         </Return>
      </startProcessResponsePrimitiveProcess>
   </S:Body>
</S:Envelope>

SOAP Request to Get Process Result

URL - http://localhost:9890/ipp-portal/services/soap/ProcessServiceHttpBasicAuth?wsdl

<soapenv:Envelope xmlns:prov="http://infinity.com/bpm/models/generated/ProviderModel_WS" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header/>
   <soapenv:Body>
      <prov:getProcessResultsPrimitiveProcess>
         <prov:ProcessInstanceOid>204</prov:ProcessInstanceOid>
      </prov:getProcessResultsPrimitiveProcess>
   </soapenv:Body>
</soapenv:Envelope>

Soap Response of Get Process Result

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
    <S:Body>
       <getProcessResultsResponsePrimitiveProcess xmlns="http://infinity.com/bpm/models/generated/ProviderModel_WS">
          <Return>
             <FormalParameter_3>Function of provider get Called :abc 123 </FormalParameter_3>
          </Return>
       </getProcessResultsResponsePrimitiveProcess>
    </S:Body>
 </S:Envelope>
<soapenv:Header>
 <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <wsse:UsernameToken wsu:Id="UsernameToken-3" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
     <wsse:Username>motu</wsse:Username>
     <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">motu</wsse:Password>
     <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">mc3h952DGu2z+JckfCXUdQ==</wsse:Nonce>
     <wsu:Created>2012-01-05T12:33:41.984Z</wsu:Created>
  </wsse:UsernameToken>
 </wsse:Security>
</soapenv:Header>

WS-Addressing Reference Parameters Example Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:new="http://infinity.com/bpm/models/generated/NewWorkflowModel" xmlns:com="http://www.infinity.com/bpm/model/NewWorkflowModel/Composite_1">
   <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <To>http://localhost:8080/ipp2/services/soap/ProcessServiceHttpBasicAuth</To>
      <Action>startProcessProcessDefinition_1</Action>
      <ReplyTo>
         <Address>http://www.w3.org/2005/08/addressing/anonymous</Address>
      </ReplyTo>
      <MessageID>uuid:35ea1109-344d-4d15-92b8-8de227f757fe</MessageID>
      <stardust-bpm-domain wsa:IsReferenceParameter="1" xmlns="http://eclipse.org/stardust/ws/v2009a/api">part2</stardust-bpm-domain>
      <stardust-bpm-partition wsa:IsReferenceParameter="1" xmlns="http://eclipse.org/stardust/ws/v2009a/api">default</stardust-bpm-partition>
      <stardust-bpm-realm wsa:IsReferenceParameter="1" xmlns="http://eclipse.org/stardust/ws/v2009a/api">carnot</stardust-bpm-realm>
      <stardust-bpm-model wsa:IsReferenceParameter="1" xmlns="http://eclipse.org/stardust/ws/v2009a/api">NewWorkflowModel</stardust-bpm-model>
   </soapenv:Header>
   <soapenv:Body>
      <new:startProcessProcessDefinition_1>
         <new:Args>
            <new:FormalParameter_1>str</new:FormalParameter_1>
            <new:FormalParameter_2>
               <com:Composite_1>
                  <myString>str</myString>
               </com:Composite_1>
            </new:FormalParameter_2>
         </new:Args>
      </new:startProcessProcessDefinition_1>
   </soapenv:Body>
</soapenv:Envelope>

RESTful Web Services for Process Interface

This RESTlet can be used for both starting a process instance and retrieving the process instance' results after it has been completed. This Web Service is available for each process interface that has been marked to be exposed via a RESTful Web Service.

Starting a Process Instance

Retrieving the Results of the Completed Process Instance

Type Declaration Web Service

This RESTlet can be used to retrieve the XML Schema Definition (XSD) of a particular Structured Type declared in an active XPDL Model.

Session Properties as Query Parameters

All of the Web Services mentioned above accept the following session properties submitted as Query Parameters:

Supported Data Types

The primitive and structured data types are supported as parameters and return types.

Retrieving WADL Definition

A WADL file describing the RESTful processes Web Service can be retrieved either via:

Note that this WADL URL also needs the query parameters to find the right model. For example, ?stardust-bpm-model=NewWorkflowModel

REST Examples

REST Request to Start Process

URL - http://localhost:9890/ipp-portal/services/rest/engine/processes/PrimitiveProcess?stardust-bpm-model=ProviderModel_WS

Method : Post

Arguments 
<?xml version="1.0" encoding="UTF-8"?>
<Args xmlns="http://eclipse.org/stardust/rest/v2012a/types">
<FormalParameter_1 xmlns="http://www.w3.org/2001/XMLSchema">Hello</FormalParameter_1>
<FormalParameter_2 xmlns="http://www.w3.org/2001/XMLSchema">5</FormalParameter_2>
</Args>


Figure: REST Request - Start Process

REST Response

http://localhost:9890/ipp-portal/services/rest/engine/processes/PrimitiveProcess?piOID=208&stardust-bpm-model=ProviderModel_WS

REST Request to Get Process Results

URL- http://localhost:9890/ipp-portal/services/rest/engine/processes/PrimitiveProcess?stardust-bpm-model=ProviderModel_WS&piOID=208

Method - GET

No arguments. Please note the given query parameters in the above URL

REST Response - No Primary Implementation is Set

<?xml version="1.0" encoding="UTF-8"?>
<Results xmlns="http://eclipse.org/stardust/rest/v2012a/types">
    <FormalParameter_3 xmlns="http://www.w3.org/2001/XMLSchema">Function of provider get Called :Hello 5</FormalParameter_3>
</Results>

REST Response - Primary Implementation is Set

<?xml version="1.0" encoding="UTF-8"?>
<Results xmlns="http://eclipse.org/stardust/rest/v2012a/types">
<FormalParameter_3 xmlns="http://www.w3.org/2001/XMLSchema">Function of Implementer1 get Called :Hello 5</FormalParameter_3>
</Results>