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:
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.
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
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
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 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.
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
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
The following endpoints are provided for the aforementioned Web service operations for the process interface to be exposed.
http://<host>:<port>/<context root>/services/soap/<DynamicEndpoint.HttpBasicAuth.Name> for the
HTTP Basic Authentication over HTTP secured variant if DynamicEndpoint.HttpBasicAuth.Enable is truehttps://<host>:<port>/<context root>/services/soap/<DynamicEndpoint.HttpBasicAuthSsl.Name>
for the HTTP Basic Authentication over HTTPS secured variant if DynamicEndpoint.HttpBasicAuthSsl.Enable is true
https://<host>:<port>/<context root>/services/soap/<DynamicEndpoint.WssUsernameToken.Name>
for the WS-Security UsernameToken over HTTPS secured variant if DynamicEndpoint.WssUsernameToken.Enable is true
PARTITIONweb-serviceprocess-interfacePlease 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.
DynamicEndpoint.HttpBasicAuth.Name - the name of the endpoint that is secured by HTTP Basic Authentication over HTTP;
defaults to ProcessServiceHttpBasicAuth, expected data type is String.
DynamicEndpoint.HttpBasicAuth.Enable - whether the HTTP Basic Authentication over HTTP secured endpoint for dynamically exposed process interfaces should be enabled;
defaults to false, DynamicEndpoint.HttpBasicAuthSsl.Name - the name of the endpoint that is secured by HTTP Basic Authentication over HTTPS;
defaults to ProcessServiceHttpBasicAuthSsl
DynamicEndpoint.HttpBasicAuthSsl.Enable - whether the HTTP Basic Authentication over HTTPS secured endpoint for dynamically
exposed process interfaces should be enabled; defaults to false, expected data type is String
DynamicEndpoint.WssUsernameToken.Name - the name of the endpoint that is secured by WS-Security UsernameToken over HTTPS;
defaults to ProcessServiceWssUsernameTokenDynamicEndpoint.WssUsernameToken.Enable - whether the WS-Security UsernameToken over HTTPS secured endpoint for dynamically exposed process
interfaces should be enabled; defaults to true
DynamicEndpoint.DefaultModelId - the default value for the target model ID in the context of dynamic Web Service endpoints,
expected data type is String
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.
GETwsdl, mandatory
modelId=<Model ID>, defaults to DynamicEndpoint.DefaultModelId
partition=<Partition>, defaults to the default partition
POSTSOAPAction - the unqualified target process IDThe primitive and structured data types are supported as parameters and return types.
Document/Literal is used.
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.
WebService.ProcessService.Username the username of the technical user; defaults to 'motu'.WebService.ProcessService.Password the password of the technical user; defaults to 'motu'.WebService.ProcessService.Realm the realm of the technical user; defaults to the default realm.
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).
Following are the typical examples of SOAP request and response.
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>
<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>
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>
<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>
<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>
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.
(http or https)://<host>:<port>/<context root>/services/rest/engine/processes/<Process ID>
HTTP or HTTPSPOST/services/rest/engine/processes/<Process ID>?piOID=<Process Instance OID>
(http|https)://<host>:<port>/<context root>/services/rest/engine/processes/<Process ID>?piOID=<Process Instance OID>.
For example, http://localhost:8080/myApp/services/rest/engine/processes/MyProcess?piOID=42
HTTP or HTTPS
GETThis RESTlet can be used to retrieve the XML Schema Definition (XSD) of a particular Structured Type declared in an active XPDL Model.
(http|https)://<host>:<port>/<context root>/services/rest/engine/typeDeclarations/<Type Declaration ID>.
For example, http://localhost:8080/myApp/services/rest/engine/typeDeclarations/MyString
All of the Web Services mentioned above accept the following session properties submitted as Query Parameters:
stardust-bpm-model the target model, defaults to DynamicEndpoint.DefaultModelId (see section SOAP Web Services)
stardust-bpm-partition the target partition, defaults to the default partition
stardust-bpm-realm the target realm, defaults to the default realm
stardust-bpm-domain the target domain, defaults to the default domain
The primitive and structured data types are supported as parameters and return types.
A WADL file describing the RESTful processes Web Service can be retrieved either via:
<host>/services/rest/engine/processes/<Process ID>/application.wadl?stardust-bpm-model=<Model ID>
OR
<host>/services/rest/engine/processes/<Process ID>Note that this WADL URL also needs the query parameters to find the right model.
For example, ?stardust-bpm-model=NewWorkflowModel
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
http://localhost:9890/ipp-portal/services/rest/engine/processes/PrimitiveProcess?piOID=208&stardust-bpm-model=ProviderModel_WS
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
<?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>
<?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>