LSPS documentation logo
LSPS Documentation
Webservices

Process Design Suite supports communication with other systems via SOAP web services: it allows you to generate Task types that can be used to design Processes that act either as a Web Service Server or a Web Service Client):

  • Web-service client tasks:
    • For every operation, the system generates one task type that sends a request to the web service server, and receives the response.
  • Web-service server tasks:
    • Wait task that waits for a request from a client,
    • Response task that sends a response to the client,
    • Error task that sends a fault response to the client.

Web Service Server

To be able to implement a Process that will serve as a Web service server, you will need to generate the following task types and create the Process using these:

  1. waitForInvoke: waits for a client request
  2. sendResponseToInvoke: sends the client the output data
  3. Optionally sendErrorToInvoke tasks: sends fault responses

waitForInvoke
The workflow enters the waitForInvoke task, it waits until it receives a web service client call. Once, it has received a client call, the task finishes, and the Process instance execution proceeds. The task defines the following parameters:
  • input: input of the call from the client request

  • requestId: reference to the ID of the call

    The ID is used by the response tasks to identify the call; the value is generated by the Execution Engine.

  • principal: reference to a slot that holds the principal who is performing the call
  • logXmlMessage: if true, all XML messages received by the task are logged to the database and can be viewed in the Webservices.

    Important: Enabling logging of XML messages can result in significant database growth. Make sure to handle such risks appropriately.

  • requestHeaders: reference to a slot that holds the HTTP headers of the request
sendResponseToInvoke
The sendResponseToInvoke Task type sends a response to the wait point of the request ID. The task defines the following parameters:
  • output: output sent in the client response
  • requestId: reference to the ID of the call
  • logXmlMessage: if true, all XML messages received by the task are logged to the database and can be viewed in the Webservices.

    Important: Enabling logging of XML messages can result in significant database growth. Make sure to handle such risks appropriately.

  • requestHeaders: reference to a slot that holds the HTTP headers of the request
sendErrorToInvoke

For the cases when the received request call is incorrect or fails, use this task to send a fault message to the client. For error responses, the task defines the following parameters:

  • error: error sent in the error response to the client
  • requestId: reference to the ID of the call
  • logXmlMessage: if true, all XML messages received by the task are logged to the database and can be viewed in the Webservices.

Important: Enabling logging of XML messages can result in significant database growth. Make sure to handle such risks appropriately.

  • requestHeaders: reference to a slot that holds the HTTP headers of the request

SOAP Webservice Server

Depending on whether you have the WSDL file for the service, you will need to do the following:

  • If you do not have the WSDL file, you need to model the input and output data types, and define a WSD definition (Generating Tasks for Web Service Server). Based on the WSD definition, the system generates the task types that you can use to implement a web service server in a process.
  • If you already have a WSDL file, the system generates the data types and task types for the web service server directly based on the WSDL file (refer to Generating Tasks for Web Service Server from WSDL File).

On runtime, you can check and manage Model instances that are serving a web service call in the Webservices.

Creating SOAP Web Service Server from Scratch

To generate task types and design a process acting as a Web service server without a WSDL, you need to do the following:

  1. Create the data types for the server.

    • input: input data type received from the web service client
    • output: output type of the data sent as a response to the web service client
    • error: data types for data sent to the client as a web service error (when the client sends invalid data to the server)

    All these data types must be defined as Records even if they contain only primitive values since they will be used in the WSDL and used for XML mapping in XSD.

  2. Check the XML mapping of the Records, their Fields, and Relationships on the XML Mapping tab of their Properties. The mapping will be applied in the XSD and WSDL files of the service. Generally, the default mapping should work fine.

    To exclude a Relationship direction from the XSD schema of your server, mark the relationship direction as XML Transient: in the Properties view of the Relationship, select the Target XML Mapping or Source XML Mapping tab and select XML Transient.

  3. Create a web service definition file:
    1. Right-click the Module, go to New > Webservice Definition
    2. Open the file in the web service editor and define the web service properties:
      • Service name: name used as the service name and the task name in the generated task types
      • Service namespace: namespace of the Web service
      • Input type: input data type you defined above
      • Output type: output data type you defined above
      • Soap fault types: fault data types you defined above
    3. If applicable, select Generate optional parameters for access to HTTP headers: if selected, the generated task type contain the properties for setting of responseHeaders.

    4. Click Generate:

      The system generates the following:

  4. Design the server Process workflow with the generated task types.

    Important: Make sure to define the id parameters on the waitForInvoke, sendResponseToInvoke, and sendErrorToInvoke. Failing to do so, might result in transaction rollback.

  5. Design the process workflow with the Webservice-Server Tasks.

    webserviceServerWorkflow.png
    Workflow of a Process Serving as a Web Service Server
  6. Expose the WSDL and XSD files as appropriate.

Important: If the timeout period elapses and the server has not sent any response, the server timeout response is sent to the client. The default time out is set to 10 seconds.

Creating SOAP Web Service Server from WSDL

To generate task types and the underlying data types for a Process that will serve as a Web service server from a WSDL file, do the following:

  1. In the GO-BPMN Explorer, right-click the respective module and in the context menu click Generate > Webservice Server.
  2. In the Generate Webservice Server dialog box, enter the following:
    1. In the WSDL location text field, type the location of the WSDL, possibly a URL.
    2. Select the optional task parameters for HTTP headers. The system will create a copy of the WSDL in the Module and create the respective Records and task types. Consider global variables for the input, output, and error data types that will hold the data during the web service invocation.
      webServiceServerResources.png
      Web Server Service Module
  3. Design the process workflow with the generated Webservice-Server Tasks.
    webserviceServerWorkflow.png
    Workflow of a Process Serving as a Web Service Server
  4. Expose the WSDL and XSD files as appropriate.

Web Service Client

A Process that acts as a web service client must contain artifacts generated on hand of the WSDL file of the target web service. The artifacts allow the Process to send a valid request to a web service server and receive and process the server response.

The generated client artifacts include the invoke task types that perform the calls, and the underlying data types:

  • invoke task types The tasks of the invoke task type perform the web service operation calls:
  • fault data types Fault data types are used to create variables, which can store the returned web service errors.
  • data types used by the generated task types

Note: Only SOAP 1.1 document and literal style Web services are supported.

Web Service Task Types

Every generated task type represents one WSDL operation. Its messages and other properties are defined by its properties:

  • isSynchronous: if true the web service call is synchronous If synchronous, the entire process execution stops until the server response is received.

    If asynchronous, other parts of the process can continue their execution (other tokens in the process continue their execution); for example, parallel branches continue, while the branch with the web service client task waits for the server response.

  • input: input data sent to the web service server
  • requestHeaders: custom headers of the request
  • requestSoapHeaders: soap headers sent with the request
  • output: reference to a slot that stores the server response
  • responseHeaders: reference to a slot that stores the response headers

  • responseSoapHeaders: list of references to variables

    The variables will be filled with the received soap headers if they match any of the present headers.

  • endpointAddress: target webservice endpoint URL address If null, the endpoint address from metadata is used.

  • logXmlMessage: database logging of messages

    If true, all XML messages received by the task are logged to the database (false by default).

Note: Enabling logging of XML messages can result in significant database growth.

  • error: If the web service server return soap: fault in web service response, fault is stored in this variable. If null, soap fault is discarded.
  • readTimeout: read timeout in milliseconds After the defined time period elapses, a BPMError is thrown. You can handle the possible error with an Error Intermediate Event. If undefined the timeout is set to zero (0) and hence no timeout is applied (the timeout is infinite).
  • login: login name used to access the web service HTTP basic authentication is used.
  • password: password for HTTP basic authentication

Creating SOAP Web Service Clients

Important: Resources for a web service client can be generated only for SOAP 1.1 web services.

To create data types and tasks that will constitute a Process that will act as a web service client, do the following:

  1. Get the respective WSDL and any other related resources. Web service WSDL is usually available on a URL provided by the web service server.

    When generating web service client for web service server Process, include the required XSD files.

  2. In the GO-BPMN Explorer, right-click your Module and in the context menu, click Generate > Webservice Client.
    creatingWebServiceClient.png
    Generating Artifacts for Web Service Client
  3. In the Generate Web Service Client dialog box:
    1. Enter the path to the target Module.
    2. In the WSDL location text field, type the URL or file system location of the WSDL.
    3. Select the additional optional task parameters to be generated.
    4. Click OK.
    5. Select the web service operations you want to use in your process: for every operation, one task type and the respective data types are generated. Tasks of the task type call the webservice server and request the operation.
      webserviceClientOperations.png
      Selecting relevant operations
    6. If necessary, adjust the XML mapping of the data types: open the Properties view of the record and on the XML Mapping tab, change the mapping.
      webserviceClientGeneratedResources.png
      Generated Task Types and Data Types
  4. Design a Process that uses the generated task types.
webserviceClientExecution.png
Model instance of a web service client Process