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.

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 ishttp://<host>:<port>/gpcore/GPProcessDiscoveryRecentWSIL/inspection.wsil .

In the URL string, replace

<host><port>

with the host name of where your application server resides, and with the server's port for HTTP communications.

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><port><X><Y>

with the host name of where your application server resides, and with the server's port for HTTP communications. stands for the process template ID and 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 <

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