Consuming the GPProcessDiscovery Web Services 

 

Guided Procedures (GP) offers a collection of services for process initiation and retrieving of process output available on an application server. The WSIL documents for the services are dynamically generated upon request. Each service element in the WSIL contains a name and description of the process, as well as a valid URL that is used to generate a WSDL document for it.

The WSIL contains process information only for processes for which the user has permissions.

...

WSIL Generation

The following process initiation Web services are available:

●      GPProcessDiscoveryWSIL– provides a listing of all active and deprecated versions of process templates available on your system. To retrieve the corresponding WSIL document, enter http://<host>:<port>/gpcore/GPProcessDiscoveryWSIL/inspection.wsil in a browser window.

●      GPProcessDiscoveryActiveWSIL – provides a listing of active template versions only. The URL for the service is http://<host>:<port>/gpcore/GPProcessDiscoveryActiveWSIL/inspection.wsil.

●      GPProcessDiscoveryRecentWSIL – provides a listing of active template versions only, with no reference to the process template versions in the WSDL URLs. The URL for the service is http://<host>:<port>/gpcore/GPProcessDiscoveryRecentWSIL/inspection.wsil.

In the URL string, replace <host> with the host name of where your application server resides, and <port> with the server’s port for HTTP communications.

http://localhost:53000/gpcore/GPProcessDiscoveryWSIL/inspection.wsil

WSDL Generation

To generate the WSDL document for a specific service (process template), choose a process and use the corresponding URL from the WSIL listing:

http://<host>:<port>/gpcore/GPExecuteProcessWSDL/pid<X>/pver<Y>?wsdl

Replace <host> with the host name of where your application server resides, and <port> with the server’s port for HTTP communications. <X> stands for the process template ID and <Y> stands for the process version. You can also get the process template ID from the Instantiation tab page in the object design time.

Alternatively, the URL

http://<host>:<port>/gpcore/GPExecuteProcessWSDL/pid<X>?wsdl

might also be used. This WSDL always belongs to the currently active version of the process template referenced by ID <X>.

The WSDL document is generated from a preliminary defined WSDL template in which the input and output parameters and process roles are replaced with the ones from the specified process template.

Web Service Operations

Once the WSDL document is generated, you can see details about a specific service residing on the application server. All operations available for the service are listed in the WSDL together with their input and output parameters.

The operations available for the GPProcessDiscovery  Web services are:

●      StartProcess – initiates an instance of a process template

·        GetProcessInfo – checks the process name and status

·        GetProcessResult – retrieves information of the process status and process finish time stamp

StartProcess

You use this operation to initiate a process from a process template.

It has the following parameters:

Technical Name	Description
Input Parameters
UDName	User-defined process name. This parameter is not mandatory and can be free text. If you do not specify a process name, you can identify the process by its process instance ID only.
UDDescription	User-defined process description. This parameter is not mandatory and can be free text.
Roles	The list of initiation-defined roles. It consists of all mandatory built-in roles (Administrator, Owner, Overseer) and user-defined roles available for the process. To each role in the list, you must assign a particular user, unless a default value is available for it. In such cases, you are not required to provide a user or you may not even be able to do so. The Web service only accepts individual user assignments. If you want to assign a group of users to a particular role, you must handle it in your client application. You can also use the GP design time for creating Web service callable objects, which is able to parse groups to single users.
InputParameters	This parameter depends on the actual input structure of the process template. The Web service provides the structure and type definitions to which you have to assign the appropriate values.
CallbackURL	This parameter is saved for future use. It is the URL that is used to notify the consumer about the process completion.
Output Parameters
Response	The StartProcess operation returns as an output parameter a global unique ID (GUID) for the process instance. You can use the GUID in the GetProcessInfo and GetProcessResult operations to check the status of the process or to get its result.

GetProcessInfo

You use this operation to check the process name, progress of completion and status.

After the process is initiated, the process execution can continue a significant amount of time. During this time the consumer can get the process information, using the process instance GUID that is returned as output parameter from the StartProcess operation.

Technical Name	Description
Input Parameters
ProcessInstanceGUID	This parameter is returned as output after the completion of the StartProcess operation.
Output Parameters
ProcessName	Process template name
Progress	Progress of completion of the process instance
Status	Process status

GetProcessResult

You use this operation to view the process result state.

After the process completion, the result of the process execution can be retrieved by the GetProcessResult operation. To start the operation, you need to enter the GUID that is returned from the StartProcess operation.

Technical Name	Description
Input Parameters
ProcessInstanceGUID	This parameter is returned as output after the completion of the StartProcess operation.
Output Parameters
EndDatetime	Process finish time stamp
OutputParams	Process template output parameters
ProcessName	Process template name
Status	Process status

GP design time provides the means for WSIL, WSDL generation and the execution of the operations listed above through its Web service callable object. Therefore, you can consume the Web service even if you do not know specific service details.

See Starting a Process Using Web Services.