Using the GSi Vertical API, process instance creation, process instance status checking and get tasks for user operations can be performed. Also task based operations: Claim and Complete can be performed.

All the above operations are exposed through the VerticalApi Service.

Getting Started

Note: GSi as of the version V1.0/1.x has deprecated the Web Services based API. Instead of this an HTTP(S) based GSi Vertical API is provided. There is a new client API VerticalHTTPClientAPI interface provided for the verticals to invoke the functions provided by the Vertical client API. The method signatures for the existing methods remain the same, only the declaration is what is changed.

This version of the document explains the usage the new Vertical HTTP based Client API and details the new API functions provided.

To use the GSi Vertical API, write a client program (Web Service requestor) in a language of your choice. This client program will send request to the VerticalApi service. The VerticalApi service will process the request and send back the response, which needs to be parsed by the client program. In the current version, by default the Java version of GSi Vertical API client is provided, discussed in later section.

The operations of the service are defined in the WSDL (Web Services Definition Language) file. To connect to the Web Service, the URL for the WSDL needs to be known. The URL will be of the following format:

http://<GSiServerLocation>:<Port>/GSiServer/verticalapi?wsdl

The detail of how the client program connects to the API. depends on the client program language and toolkit used. After connecting the client can send requests to invoke any of the provided operations.

Requirements

Since the GSi Vertical API runs as a Web Service, there is no need to install any specific stuff related to the API. The only software that needs to be installed is the ones required for the client program.

In case of the Java version which is provided with the distribution, the VerticalClientApi.jar and Apache Axis related jars are required to be present in the classpath.

API Reference

This section explains the operations provided by the GSi Vertical API service. To access any of the operations provided by the service, the client needs to validate/identify itself. The validate operation request upon success will return a user token. This token should be used for all subsequent requests. Once the client has done with all its service requests, it needs to invoke the disconnect operation to logout.

Validate User

Operation Name	validateUser
Description	This request is issued for authentication with the vertical API. Upon successful login, a valid user token is created and returned. The client for all its requests [on behalf the user] should use this token as one of the parameters.
Parameters	User Name Roles, Array of Strings Unit, Array of Strings – [Organization Unit] Vertical, the vertical into which the user wants to connect
Response	User Token – This should be used for all further requests

Create Process Instance

Operation Name

createProcessInstance

Description

This operation is used to create an instance of the specified process definition with related inputs. This request is served by the GSi server in a asynchronously manner, meaning the process instance will get created asynchronously and is not immediate

Parameters

Process Definition Name

Vertical Unique Identifier (to uniquely identify the instance)

Requestor Name

Array of Input Parameters [Key-Value pair]

User Token

Response

Result – return code indicating the success or failure of the request. The return code has the following meanings:

Code	Meaning
1	Request successful
2	Request failed
3	Invalid user token / User not authenticated

Create Process Instance Immediate

Operation Name

createProcessInstanceImmediate

Description

This operation is used to create an instance of the specified process definition with related inputs. This request is served by the GSi immediately.

Parameters

Process Definition Name

Vertical Unique Identifier (to uniquely identify the instance)

Requestor Name

Array of Input Parameters [Key-Value pair]

User Token

Response

Result – return code indicating the success or failure of the request. The return code has the following meanings:

Code	Meaning
1	Request successful
2	Failed, Insufficient Input Parameters
3	Failed, Process Definition Not Found
4	Unknown Exception
5	Invalid user token / User not authenticated
6	Unable to connect – Internal Error

Get Process Instance Status

Operation Name	getPIStatusForVerticalUnqiueID
Description	Get the status of the process instance with the specified input parameters, process name and vertical unique ID. Returns the current status of the process instance.
Parameters	Process Definition Name Vertical Unique ID User Token
Response	Status, of process instance in the following format Response = [the process status:<completed activities (act1,act2,act3)>:<activities in execution(act1,act2,act3):<activities aborted(act1,act2,act3)]

Get Tasks

Operation Name	getTasks
Description	Gets the open and pending tasks of the user for the roles and organization units specified during the validateUser operation.
Parameters	User Token
Response	Array of User Tasks [ArrayOfUserTask Message]

Claim Task

Operation Name

claimTaskItem

Description

Claim the specified task/task item on behalf of the requestor. The operation can fail due to various reasons listed in the response section.

Parameters

Task Id

Requestor

User Token

Response

Result – return code indicating the success or failure of the request. The return code has the following meanings:

Code	Meaning
1	Successfully claimed
2	Invalid Task State for Claim
3	Specified Task Not found
4	Unknown Exception
5	Invalid user token / User not authenticated
6	Unable to connect – Internal Error

Complete Task

Operation Name

completedTaskItem

Description

Complete the specified task/task item with the passed output parameters. The operation can fail due to various reasons listed in the response section.

Parameters

Task Id

Output Parameters

User Token

Response

Result – return code indicating the success or failure of the request. The return code has the following meanings:

Code	Meaning
1	Successfully claimed
2	Invalid Task State for Complete
3	Specified Task Not found
4	Unknown Exception
5	Invalid user token / User not authenticated
6	Unable to connect – Internal Error

Get Task Output Parameters

Operation Name	getTaskOutParams
Description	Gets the task output parameters for the specified task/task item. This is useful for the task interfaces (Open and Pending Task list display) to know and display the outputs that the specified task generates.
Parameters	Task Id User Token
Response	String Array of Output parameter names

Reject Task

Operation Name

rejectTaskItem

Description

Reject the specified task/task item on behalf of the requestor. The task after rejection becomes Open and is available for Claim for the users of the role. The operation can fail due to various reasons listed in the response section.

Parameters

Task Id

Requestor

User Token

Response

Result – return code indicating the success or failure of the request. The return code has the following meanings:

Code	Meaning
1	Successfully rejected task
2	Invalid Task State for reject task
3	Specified Task Not found
4	Unknown Exception
5	Invalid user token / User not authenticated
6	Unable to connect – Internal Error

Force Assign Task

Operation Name

forceAssignTaskItem

Description

Force assign the task/task item on behalf of the requestor to the specified “assign to” user. The operation can fail due to various reasons listed in the response section.

Parameters

Task Id

Requestor

AssignTo

User Token

Response

Result – return code indicating the success or failure of the request. The return code has the following meanings:

Code	Meaning
1	Successfully force assigned task
2	Invalid Task State for reject task
3	Specified Task Not found
4	Unknown Exception
5	Invalid user token / User not authenticated
6	Unable to connect – Internal Error

Get Task Output Parameters With Type

Operation Name	getTaskOutParamsWithType
Description	Gets the task output parameters for the specified task/task item with their respective datatype This is useful for the task interfaces (Open and Pending Task list display) to know and display the outputs and their data types that the specified task generates.
Parameters	Task Id User Token
Response	2 Dimensional String Array of Output parameter names and their types

Get Completed Tasks

Operation Name	getCompletedTasks
Description	Gets the tasks completed by the user for the roles and organization units specified during the validateUser operation.
Parameters	User Token
Response	Array of User Tasks [ArrayOfUserTask Message]

Get Process Based Data for Report

Operation Name	getProcessData
Description	This method gets the process data (specific to the vertical) based on the specified search criteria. The search is based on process/activity definition, state and process attributes values.
Parameters	Process Names (array) Process State Activity Id Activity State Requestor Condition Vertical Unique ID Condition Attribute Filter Started From Date Started To Date Ended From Date Ended To Date User Token
Response	Array of Task info (CSV- String)[Message] Format : Vertical mapping id, Process name (can be empty), Status, Requestor(can be empty), Started Date, Completed Date, Time taken for completion (ms)

Disconnect User

Operation Name	disconnectUser
Description	Disconnects/Logouts the user and after this invocation, any requests to other operations will fail with Invalid token/User not authenticated error.
Parameters	User Token
Response	None

Java Client API Reference

By default with the distribution, the Java client for the Vertical API is provided. This can be used by including the VerticalAPI.jar and related jar files in the vertical application classpath.

There are classes provided to access the Vertical API. All access to API is encapsulated in one class VerticalClientApi (Package: com.comat.gsi.common.verticalapi) and this class is used to invoke the operations provided by the Vertical API.

For detailed information, refer to the Javadoc API documents provided with the distribution.

The new vertical API client is provided in the new class VerticalHTTPClientApi (Package: com.comat.gsi.common.verticalapi). This class is used to invoke the operations provided by the HTTP(S) based nwVertical API.

Core Class – VerticalClientApi [Deprecated] – Use VerticalHTTPClientApi

This class handles the invocation of the web services based Vertical API. After instantiating the class, first validateUser method has to be invoked. Upon successful execution other methods can be invoked. If the user is not validated remaining methods cannot be invoked.

Every method throws VerticalApiException in 2 possible case ie., first if user is not validated/authenticated and second, if server is not reachable.

Construct VerticalClientApi [Deprecated] / Use VerticalHTTPClientApi

VerticalClientApi Creation

The instance of the VerticalClientApi needs to be created to invoke the vertical API.

VerticalClientApi(String serverUrl,

                         String namespace,

                         String serviceName)

Parameters:

serverUrl : is the URL of the WSDL location

namespace : namespace URI

serviceName : Service name to access. This will be “VerticalApi”.

Sample Usage:

VerticalClientApi verticalClientApi = new VerticalClientApi

        ("http://<gsiserverlocation>:<port>/gsiserver/verticalapi?wsdl",

        "http://com.comat.gsi.common.verticalapi","VerticalApi");

VerticalHttpClientApi Creation

The instance of the VerticalHTTPClientApi needs to be created to invoke the vertical API.

VerticalHTTPClientApi(String host, int port)

Parameters:

host : is the host name/ipaddress of GSi Server

port : is the HTTP port where GSi Server is running

Sample Usage:

VerticalHTTPClientApi verticalClientApi = new VerticalHTTPClientApi

        ("localhost",8080);

validateUser

Validates the user information details provided. After the instance creation of the VerticalClientApi object, this method should be called before invoking any other methods.

Signature:

void validateUser(String username,

                         String[] role,

                         String[] ou,

                         String verticalName)

Parameters:

username - User Id/Name.

role - Array of roles the user plays

ou - Array of groups to which user belongs.

Throws:

VerticalApiException – if the user is not valid or if the server cannot be contacted.

Sample Usage:

String username = “tom”;

String[] roles = {“HR Manager”};

String[] ou     = {“HR”};

try{

        verticalClientApi.validateUser(username, roles, ou);

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

createProcessInstance

This method creates the process instance with the specified inputs in an asynchronous manner. This request is server by the GSi Server in an asynchronous manner and errors like process not deployed, insufficient inputs are not immediately known by the caller. The success return code indicates that the request is successfully posted.

Signature:

int createProcessInstance(String processDefinition,

                                 String verticalUniqueID,

                                 String requestor,

                                 java.util.Map inputParamValues)

Parameters:

processDefinition – Process Definition Name

verticalUniqueID - Vertical Unique/Mapping ID for future reference

requestor – User Id/Name of the requestor

inputParamValues – Map of process input parameter name-value pairs

Returns:

int - Return values 1 - Successfully request sent 2- Request failed 3 - Invalid usertoken

Throws:

VerticalApiException – if the server cannot be contacted.

Sample Usage:

Map inputParams = new HashMap();

inputParams.put(“OfferLetterNo”, “OL-09-2005-10”);

try{

        int rCode = verticalClientApi.createProcessInstance(“Employee Join Process”, “OL-09-2005-10”, “tom”, inputsParams);

        switch(rCode) {

               case 1 : ..;// Success

..

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

createProcessInstanceImmediate

This method creates the process instance with the specified inputs in a synchronous manner. This request is server by the GSi Server in a synchronous manner and errors like process not deployed, insufficient inputs are returned immediately.

Signature:

int createProcessInstanceImmediate(String processDefinition,

                                 String verticalUniqueID,

                                 String requestor,

                                 java.util.Map inputParamValues)

Parameters:

processDefinition – Process Definition Name

verticalUniqueID - Vertical Unique/Mapping ID for future reference

requestor – User Id/Name of the requestor

inputParamValues – Map of process input parameter name-value pairs

Returns:

Return values 1 - Successfully request sent 2- Insufficient input parameters 3 - Process definition not found 4 - Unknown exception 5 - Invalid user token 6 - Unable to contact WFE

Throws:

VerticalApiException – if the server cannot be contacted.

Sample Usage:

Map inputParams = new HashMap();

inputParams.put(“OfferLetterNo”, “OL-09-2005-10”);

try{

        int rCode = verticalClientApi.createProcessInstanceImmediate(“Employee Join Process”, “OL-09-2005-10”, “tom”, inputsParams);

        switch(rCode) {

               case 1 : ..;// Success

..

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

getPIStatusForVerticalUnqiueID

Get the status of the process instance with the specified input parameters, process name and vertical unique ID. The status will be of the format [the process status:<completed activities (act1,act2,act3)>:<activities in execution(act1,act2,act3):<activities aborted(act1,act2,act3)]

Signature:

String getPIStatusForVerticalUnqiueID(String processDefinition,

                                      String verticalUniqueID)

Parameters:

processDefinition – Process Definition Name

verticalUniqueID – Vertical Unique/Mapping ID

Throws:

VerticalApiException – if the server cannot be contacted.

Sample Usage:

try{

String status = verticalClientApi.getPIStatusForVerticalUnqiueID(

               “Employee Join Process”, “OL-09-2005-10”);

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

getTasks

Gets the open and pending tasks of the user for the roles and organization units specified in validateUser method.

Signature:

UserTask[] getTasks()

Parameters:

None

Returns:

Array of UserTask objects, which are open or pending

Throws:

VerticalApiException – if the server cannot be contacted.

Sample Usage:

try{

UserTask[] tasks = verticalClientApi.getTasks();

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

claimTaskItem

Claim the specified task/task item on behalf of the requestor.

Signature:

int claimTaskItem(long taskID,String requestor)

Parameters:

taskID – task id of Task Item to be claimed

requestor – user requesting the claim

Returns:

int - return codes 1 - Successfully Claimed 2 - Invalid State 3- Task not found 4 - Failed for unknown reason 5 - Invalid token/ User not authenticated 6 - Unable to contact WFE

Throws:

VerticalApiException – if the server cannot be contacted.

Sample Usage:

try{

        int rCode = verticalClientApi.claimTaskItem(101, “tom”);

        switch(rCode) {

               case 1 : ..;// Claim Successful

..

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

completedTaskItem

Complete the specified task/task item with the passed output parameters..

Signature:

int completedTaskItem(long taskID,String taskOutputParams)

Parameters:

taskID – task id of Task Item to be claimed

taskOutputParams – task output in XML format

Returns:

int - return codes 1 - Successfully Completed 2 - Invalid State 3- Task not found 4 - Failed for unknown reason 5 - Invalid token/ User not authenticated 6 - Unable to contact WFE

Throws:

VerticalApiException – if the server cannot be contacted.

Sample Usage:

try{

        int rCode = verticalClientApi.completeTaskItem(101,taskOutputParams);

        switch(rCode) {

               case 1 : ..;// Complete Successful

..

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

getTaskOutputParams

Get the task output parameters for the specified task/task item.

Signature:

String[] getTaskOutputParams(long taskID)

Parameters:

taskID – task id of Task Item to be claimed

Returns:

String array of output parameter names

Throws:

VerticalApiException – if the server cannot be contacted.

Sample Usage:

try{

        String[] outputParamNames = verticalClientApi.getTaskOutputParams(101);

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

rejectTaskItem

Reject the specified task/task item on behalf of the requestor. The task item upon successful rejection is available as an open task for claiming by the potential users.

Signature:

int rejectTaskItem(long taskID,String requestor)

Parameters:

taskID – task id of Task Item to be rejected

requestor – user requesting the task rejection

Returns:

int - return codes 1 - Successfully Rejected task 2 - Invalid State 3- Task not found 4 - Failed for unknown reason 5 - Invalid token/ User not authenticated 6 - Unable to contact WFE

Throws:

VerticalApiException – if the server cannot be contacted.

Sample Usage:

try{

        int rCode = verticalClientApi.claimTaskItem(101, “tom”);

        switch(rCode) {

               case 1 : ..;// Reject task item Successful

..

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

forceAssignTaskItem

Force assign the specified task/task item on behalf of the requestor to the specified assignto user.

Signature:

int forceAssignTaskItem(long taskID, String requestor, String assignTo)

Parameters:

taskID – task id of Task Item to be force assigned

requestor – user requesting the task force assigned

assignTo – user to whom the task needs to be force assigned

Returns:

int - return codes 1 - Successfully force assigned task 2 - Invalid State 3- Task not found 4 - Failed for unknown reason 5 - Invalid token/ User not authenticated 6 - Unable to contact WFE

Throws:

VerticalApiException – if the server cannot be contacted.

Sample Usage:

try{

        int rCode = verticalClientApi.forceAssignTaskItem(101, “tom”,”ram”);

        switch(rCode) {

               case 1 : ..;// Force assign task item Successful

..

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

getTaskOutputParamsWithType

Get the task output parameters for the specified task/task item with the parameter data types.

Signature:

String[][] getTaskOutputParamsWithType(long taskID)

Parameters:

taskID – task id of Task Item to be claimed

Returns:

String 2 dimensional array of task output parameters and their types

Throws:

VerticalApiException – if the server cannot be contacted.

Sample Usage:

try{

        String[] outputParamNames = verticalClientApi.getTaskOutputParamsWithType(101);

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

getCompletedTasks

Gets the completed tasks of the user for the roles and organization units specified in validateUser method.

Signature:

UserTask[]getCompletedTasks ()

Parameters:

None

Returns:

Array of UserTask objects, which are completed by the logged in user.

Throws:

VerticalApiException – if the server cannot be contacted.

Sample Usage:

Try{

UserTask[] tasks = verticalClientApi.getCompletedTasks();

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

Get Process Based Data for Report

This method gets the process data (specific to the vertical) based on the specified search criteria. The search is based on process/activity definition, state and process attributes values.

Signature:

String[] getProcessData(String[] processNames, int processState,

int actId, int actState, Condition reqCond, Condition verticalIDCond, ProcessAttributeCriteria attrFilter, Date startedFromDate, Date startedToDate, Date endedFromDate, Date endedToDate ) throws VerticalApiException

Parameters:

processNames

processState

actId

actState

reqCond - Process Requestor name based Condition

verticalIDCond - vertical mapping id based Condition

attrFilter - process attribute based conditions criteria ProcessAttributeCriteria

startedFromDate

startedToDate

endedFromDate

endedToDate

Returns:

String[] - each record csv based

Format : Vertical mapping id, Process name (can be empty), Status, Requestor(can be empty), Started Date, Completed Date, Time taken for completion (msec)

Throws:

VerticalApiException – if the server cannot be contacted.

Sample Usage:

try{

ProcessAttributeCriteria criteria = new ProcessAttributeCriteria();

 Calendar calendar = Calendar.getInstance();

 calendar.set(2008,4,26);

 Date startedDate = calendar.getTime();

 calendar.set(2008,4,28);

 Date startedToDate = calendar.getTime();

 calendar.set(2008,4,27,16,0);

 Date endFromDate = calendar.getTime();

 String[] pData = new String[0];

// Usage Scenario : 1

// Search by process names with requestor condition and by started from // date + ended from date

 pData = clientAPi.getProcessData(new String[] {"ManualTaskPrority",

         "ManualActivities"}, -1,-1,-1,

         Conditions.createRequestorLike("j"), null, criteria,

         startedDate, null, endFromDate,null);

// Use the pData

// Usage Scenario : 2

// Search by process names with requestor condition and no dates

 pData = clientAPi.getProcessData(new String[] {"ManualTaskPrority",

         "ManualActivities"}, -1,-1,-1,

         Conditions.createRequestorLike("j"), null, criteria,

         null,null,null,null);

// Usage Scenario : 3

// Search by process names with vertical mapping id condition and

// process attributes criteria that of “Name”

criteria.startAndGroup().add(Conditions.like("Name","T")).endGroup();

pData = clientAPi.getProcessData(new String[] {"ManualTaskPrority"}, -

        1,-1,-1,null, Conditions.createMappingIDLike("S") , criteria,

        null,null,null,null);

// Usage Scenario : 4

// Search by process name and activity id with both process (102 –

// Running)and activity state (200 – Not Started) – for states use

// given process and activity states

criteria = new ProcessAttributeCriteria();

pData = clientAPi.getProcessData(new String[] {"ManualTaskPrority"},

        102,1,200,null, null, criteria, null,null,null,null);

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

disconnectUser

Disconnects/Logouts the user and after this invocation, any requests to other operations will fail with Invalid token/User not authenticated error.

Signature:

void disconnectUser()

Parameters:

None

Throws:

VerticalApiException – if the server cannot be contacted.

Sample Usage:

try{

    verticalClientApi.disconnectUser();

}catch(VerticalApiException vae) {

        // User authentication failed or server not reachable

Appendix

WSDL Document

<?xml version="1.0" encoding="UTF-8"?>

<types>

</sequence>

</complexType>

</schema>

</types>

</message>

</message>

</message>

</message>

</message>

</message>

</message>

</message>

</message>

</message>

</message>

</message>

</message>

</message>

</message>

</message>

</message>

<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"/>

<soap:operation soapAction=""/>

<input>