As part of your models, you can design processes that act as web-service servers or clients: The procedures differ slightly depending on whether you are creating a SOAP client or server,or a REST client or server.

REST Webservice Processes

You can create a process that will act as a RESTful Web Service server or client using dedicated task types:

The RESTful Web Services are implemented as required by JAX-RS: Java TM API for RESTful Web Services version 2.0 Final Release.

Creating a REST Server Process

To create a Process that will handle REST requests, you need to create a definition and generate task types based on the definition. The task types will then serve to design the Process.

To create a REST web service server process, do the following:

Create the records for the server:
- input record for data received from the web service client
- output record for data sent as a response to the web service client
- error record for data sent to the client as an error
  
  If you plan to use JSON as content type, make sure the properties of the records are only of the following types:
  - String, Integer, Decimal, Boolean, Date, or Enumeration.
  - Set, List, Map with String, Integer, Decimal, Boolean, Date, Enumeration members, or Set, List, Map members with members of these types.
  - References to records with properties of the types as defined above.
Create a web service definition file:
1. Right-click the Module, go to New > RESTful Webservice Definition
2. Open the file in the web service editor and define the web service properties:
  - Path Template: template of the URL path of the service
    
    Define the Path Template with any path variables you want to use: the variables will be added to the Path Variables table below automatically. The template supports path variables, such as, {itemID}, and regular expressions. The REST server URL is then resolved as <LSPS_Server_URL>/lsps-ws/rest/<Path_Template> and path variables are accessible as parameters of the waitRestRequest task.
  - Method: method type
  - Input type: input record
  - Output type: output record
  - Error type: error record
  - In the Path Variables table, adjust the data type of individual variables: the generated task types will have the variables as parameters.
3. If applicable, select Generate optional parameters for access to HTTP headers: if selected, the generated task type will contain the responseHeaders parameter so you can modify the response headers; otherwise, you will be able to use only the default headers.
4. If applicable, select Generate optional parameters for access to HTTP request parameters: if selected, the generated task type will contain the requestHeaders parameter so you can modify the request headers; otherwise, you will be able to use only the default headers.
5. Click Generate to generate task types required for the process and design the process with these task types:

The system generates the following task types:

waitRestRequest

waits until it receives a web service request from client: it accepts a request if the path of the request matches its path template. If there are several tasks waiting for a request then the task with a more precise path template handles the request. Once a task accepts the request, it finishes, and the process instance execution proceeds.

The waitRestRequest task defines the following parameters:

input: input received from the client
requestId: ID of the call

The ID is used by the response tasks to identify the call; the value is generated by the LSPS Server.
parameters with path variables as defined in the web-service definition
htttpHeaders (optional): parameter with received HTTP header
requestParams (optional): parameter with received request parameters

sendRestResponse

sends a response to the request with the request ID defined by its parameter.

The task defines the following parameters:

output: response sent to the client
requestId: ID of the call

sendRestErrorResponse

sends a fault message to the client when the received request call is evaluated as incorrect or fails.

The task defines the following parameters:

error: error sent in the error response to the client
requestId: reference to the ID of the call

REST Server Process

Deploy the Model with the Process and run its instances as necessary.

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

Creating REST Client Process

To create a Process that will serve as a REST client, use in the workflow the HttpCall task type or use your own task type.

Make sure to define all required parameters of the task.

Example GET HTTPCall task parameters

httpMethod /* String */ -> "GET",
url /* String */ -> "http://localhost.com:9500/3_2/section/_search",
request /* Object */ -> "{""query"":{""term"":{""title"":""model""}}}",
requestContentType /* String */ -> "application/json",
isSynchronous /* Boolean */ -> true
//equivalent to:
//curl -H "Content-Type: application/json" -X GET
//http://localhost.com:9500/3_2/section/_search 
//-d '{"query":{"term":{"title":"model"}}}

Example POST HTTPCall task parameters

httpMethod /* String */ -> "POST",
url /* String */ -> "http://localhost:8080/lsps-ws/rest/client/123",
request /* Object */ -> convertToJson(new Input(int -> 333)),
requestContentType /* String */ -> "application/json" //"application/xml",
response /* Reference<String> */ -> &response,
responseCode /* Reference<Integer> */ -> &responseCode,
login /* String */ -> "admin",
password /* String */ -> "admin",
readTimeout /* Integer: timeout in ms */ -> 9999,
requestHeaders /* Map<String,String> */ -> [ "Accept" -> "application/json"],
responseHeaders /* Reference<Map<String,String>> */ -> ,
isSynchronous /* Boolean */ -> false

SOAP Webservice Processes

To implement a process that will serve as a SOAP server or client, you need to create the resources that represent the web service operations and design the web-service process.

You will generate Task types that implement the web service communication and will act either as a Web Service Server or a Web Service Client):

Web-service client tasks:
- For every operation, 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.

SOAP Server Process

To design a process that will serve as a SOAP web-service server, you need to:

generate task types that can handle the client web-service call:
- waitForInvoke waits for a client call
- sendResponseToInvoke sends a response to the client call
- sendErrorToInvoke sends an error response to the client call
design a process with the tasks of these types that will serve such client request.

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

You can check and manage Model instances that are serving a web service call in the Web Services view or Management Console.

Creating a SOAP Server Process from Scratch

To generate task types and design a process acting as a SOAP web-service server without a WSDL, do the following:

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 the data structures must be defined as Records even if they contain only one field of a primitive type.
Check the XML mapping of the records, their fields, and relationships on the XML Mapping tab of Properties to define how to generate the XSD and WSDL files:
- To allow empty tags, such as, <ns1:someValue xmlns:ns1="urn:lsps:myws"/>, select the "Use xsi:nil flag" on the XML Mapping of the field or record: this translates to the nillable="true" attribute in the generated xsd file. The empty tag is sent when the value of the field or record is null.
- To allow a field or record to be missing, select the Optional flag: this translates to the minOccurs="0" attribute of the XSD tag so if the field or record is absent, no tag is inserted.
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.
Create a web service definition file:
1. Right-click the Module, go to New > Webservice Definition
2. In the web service editor, define the web service properties:
  - Service name: name used as the service name and the task name in the generated task types
    
    The target service URL is resolved as <LSPS_Server_URL>/lsps-ws/service/<MODULE_NAME>/<Service_Name>.
  - Service namespace: namespace of the Web service used in the generated WSDL
  - Input type: input data type you defined
  - Output type: output data type you defined
  - Soap fault types: fault data types you defined
3. Select the options for applicable settings of headers.
4. Click Generate to generate the following:
  - XSD schema file, which will make use of the data types
  - WSDL file that imports the XSD schema.
  - Webservice server task types
Design the server Process workflow with the generated task types:
- waitForInvoke waits until it receives a web service client call: Once the task has received a client call, the task stores the client input and finishes. The task has 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 accessible from 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 sends a response to the wait point of the request ID. The task has 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 accessible from the management tools.
    
    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 sends a fault message to the client in cases the received request call is considered incorrect or failed. The task has 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 accessible from the management tools.
    
    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
    
    Important: Make sure to define the id parameters on the waitForInvoke, sendResponseToInvoke, and sendErrorToInvoke. Failing to do so might result in transaction rollback.
Workflow of a process serving as a web service server
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 a SOAP Server Process from WSDL

To generate task types and the underlying data types for web-service server from a WSDL file, do the following:

In the GO-BPMN Explorer, right-click the respective module and in the context menu click Generate > Webservice Server.
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 storing input, output, and error data types that will hold the data during the web service invocation, in global variables.
  
  Web Server Service Module
Design the process workflow with the generated Webservice-Server Tasks.

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

SOAP Client Process

To design a Process that acts as a web service client, you will generate artifacts based on the WSDL file of the target web service. These will include the following:

invoke task types for each operation: The tasks of the invoke task type perform the web service operation calls.
fault data types: Fault data types to store returned web service errors
data types used by the generated task types

Creating a SOAP Client Process

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

To create data types and task types that will constitute you web-service client process, do the following:

Get the WSDL and any other related resources.

Web service WSDL is usually available on a URL provided by the web service server.
When creating a web service client for a web service server process, include the XSD files.
In the GO-BPMN Explorer, right-click your Module and in the context menu, click Generate > Webservice Client.

Generating artifacts for web service client
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 options for the additional parameters: these will be generated as properties of the task types.
4. Click OK.
5. Select the required web-service operations: for every operation, one task type and the respective data types will be generated. Tasks of the task type call the web-service and request the operation.
  
  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.
  
  Generated Task Types and Data Types
Design a process with the generated task types. Each task type represents one WSDL operation with the operation's messages and data defined by its properties:
- isSynchronous: if true the web service call is synchronous
  
  Synchronous task block the execution in the entire process until the server response is received, while asynchronous tasks allow other parts of the process instance to continue their execution (other tokens in the process continue to move); 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 returns 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, an Error 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

Model instance of a web service client Process