Creating Worklist Entries by an External System
A third-party system uses the PT_WORKLIST web service, which is provided by PeopleSoft, to create a new worklist entry for a task that is to be completed by a PeopleSoft Enterprise application. Like any other web service, the worklist web service is discoverable using web service inspection language (WSIL) or in the web services repository or in an optional UDDI registry. The PeopleSoft PT_WORKLIST web service provides two service operations– CREATE_WORKLIST_ITEM and GETWLINSTANCE. A service operation is a predefined transaction between two or more systems. Both of these web service operations provide a request message for the third-party system developer to enter data and a reply message from PeopleSoft Enterprise. When creating the request message, consumers of this web service (the third-party system) must know the appropriate PeopleSoft Enterprise values to enter for these request message items:
PeopleSoft business process name.
Activity name.
Event name.
Worklist name.
PeopleSoft user ID.
The CREATE_WORKLIST_ITEM web service operation is the primary service operation for creating worklist entries. GETWLINSTANCE is an optional web service operation that enables the third-party system to request status information about the worklist entry. The third-party system web developer must provide the same information for the request message for this optional service operation as was provided for the request message when the CREATE_WORKLIST_ITEM web service is created.
The following sections discuss:
Defining CREATE_WORKLIST_ITEM service operation.
Describing PT_WL_CREATE_REQUEST message.
Describing PT_WL_CREATE_RESPONSE message.
Describing GETWLINSTANCE service operation.
Describing PT_WL_GET_INSTANCE_REQ message.
Describing PT_WL_GET_INSTANCE_RESP message.
Submitting web service operation.
Defining CREATE_WORKLIST_ITEM service operation
The third-party system uses this web service operation to enter a request message to create the worklist entry for a PeopleSoft Enterprise application user and to receive notification when the task is marked as Worked. Because several days may elapse from when the request was submitted to when the task is actually completed and marked Worked, this is an asynchronous request-reply web service operation.
Describing PT_WL_CREATE_REQUEST Message
The alias for this request message is CreateWorklistEntryData. The following table provides information about the fields in this request message:
Schema Input Field Name |
PeopleSoft Record Field Name |
Description |
Type |
Required |
---|---|---|---|---|
RequestMessageID |
PT_REQUEST_MSG_ID |
A message identifier that is defined by the third-party system web service developer. If this field is defined, the third-party system can use the GETWLINSTANCE service operation to request and receive status information about the worklist entry before and after it is marked Worked. If this field is not defined by the third-party system web service developer, status information cannot be provided to the third-party system. If the third-party system developer omits this field, the Transaction ID of the request message is used instead to track the worklist entry. Regardless of whether this field is used, the third-party system is notified when the worklist entry is marked Worked. |
String |
No |
BusinessProcessName |
BUSPROCNAME |
The PeopleSoft Enterprise source business process name that includes the work item. The third-party system web service developer enters the appropriate PeopleSoft value for this field. |
String |
Yes |
ActivityName |
ACTIVITYNAME |
The PeopleSoft Enterprise source activity name of the source business process. The third-party system web service developer enters the appropriate PeopleSoft value for this field. |
String |
Yes |
EventName |
EVENTNAME |
The PeopleSoft Enterprise source event name of the source activity. This field defines a routing event for PeopleSoft Workflow. The third-party system web service developer enters the appropriate PeopleSoft value for this field. |
String |
Yes |
WorklistName |
WORKLISTNAME |
The PeopleSoft Enterprise source worklist name for the source event. The third-party system web service developer enters the appropriate PeopleSoft value for this field. |
String |
Yes |
OperatorID |
OPRID |
The ID of the PeopleSoft Enterprise user who is assigned to the worklist entry. The third-party system web service developer enters the appropriate PeopleSoft value for this field. |
String |
Yes |
OriginatorID |
ORIGINATORID |
This field can be the ID of the PeopleSoft manager who assigns the worklist entry to the user. The user who is assigned to the worklist entry can view this field. If the value is omitted, the default value for this field is the system ID that processed the PeopleCode to create the worklist entry. This is an optional field. |
String |
No |
Priority |
WL_PRIORITY |
The priority of the worklist entry. Valid values are:
The default value for this field is blank. The third-party system web service developer enters the appropriate PeopleSoft value for this field. This is an optional field. |
String |
No |
ApplicationData |
PT_WL_CR_APP |
A section in the request message that contains the case sensitive field names and values of the PeopleSoft Enterprise application worklist record. In addition to the key fields, which are required, the information from this field can be used to populate optional fields. If the application worklist record is missing or misspelled, an error is sent to the requesting system indicating that the worklist entry could not be created. The third-party system web service developer enters the appropriate PeopleSoft value for this field. |
SubRecord with two fields, Name and Value |
Yes |
AdditionalData |
PT_WL_CR_ADD |
A section in the request message that can be used to pass additional information between systems. The third-party system web service developer enters the appropriate PeopleSoft value for this field. This is an optional feature that is useful only when a custom notification handler is used to process the worklist entry creation. |
SubRecord with two fields, Name and Value |
No |
To use the AdditionalData section of the request message, PeopleSoft Enterprise application developers must design application-specific handlers that:
Implement from the PeopleTools-delivered OnNotify class.
Have access to the entire XML message.
Call the PeopleTools-delivered handler to create the PeopleTools Worklist entry, the applications Worklist entry and the reply-to record.
Do any additional required application processing.
Ensure that the PeopleTools-delivered notification handler is set to inactive, and the application handler is set to active.
Describing PT_WL_CREATE_RESPONSE Message
The alias for this reply message is CreateWorklistEntryResponse. This table provides information about the fields in this reply message:
Schema Output Field Name |
PeopleSoft Record Name |
Description |
Type |
---|---|---|---|
RequestMessageID |
PT_REQUEST_MSG_ID |
The message identifier from the request message. |
String |
BusinessProcessName |
BUSPROCNAME |
The PeopleSoft Enterprise source business process name that includes the work item. The response message uses the value defined in the request message. |
String |
ActivityName |
ACTIVITYNAME |
The PeopleSoft Enterprise source activity name of the source business process. The response message uses the value defined in the request message. |
String |
EventName |
EVENTNAME |
The PeopleSoft Enterprise source event name of the source activity. This field defines a routing event for PeopleSoft Workflow. The response message uses the value defined in the request message. |
String |
WorklistName |
WORKLISTNAME |
The PeopleSoft Enterprise source worklist name for the source event. The response message uses the value defined in the request message. |
String |
InstanceID |
INSTANCEID |
A unique number that identifies the instance of the worklist entry. Value provided by PeopleSoft Enterprise. |
Number |
TransactionID |
TRANSACTIONID |
A number that identifies the worklist entry transaction. Value provided by PeopleSoft Enterprise. |
Number |
OperatorID |
OPRID |
The ID of the PeopleSoft Enterprise user who is assigned to the worklist entry. The response message uses the value defined in the request message. |
String |
InstanceStatus |
INSTSTATUS |
For a given worklist, determines the worklist status—available, selected, worked, canceled. Value provided by PeopleSoft Enterprise. |
Number |
WorkedOn |
INSTWORKEDDTTM |
The date and time a worklist instance was worked by a user. Value provided by PeopleSoft Enterprise. |
Number |
ErrorCode |
MESSAGENBR |
A way to identify a specific type of error. Value provided by PeopleSoft Enterprise. |
Number |
ErrorDescription |
MESSAGE_DESCR |
A textual description of the error. Value provided by PeopleSoft Enterprise. |
String |
AdditionalData |
PT_WL_CR_ADD |
An optional section in the request message that is used by PeopleSoft Enterprise application developers to do additional processing, such as adding informational notes. This feature is available only when the assigned user selects the Programmatic option to mark the worklist entry as complete. |
SubRecord with two fields, Name and Value |
Describing GETWLINSTANCE Service Operation
GETWLINSTANCE is an optional web service operation that enables the third-party system to request status information about a worklist entry that it created for a PeopleSoft application user. This status information can be requested by the third-party system during the interim–between the time the worklist entry was created and before the worklist entry is marked Worked–or even after the worklist entry is marked Worked. This is a synchronous web service operation in which a response is immediately sent back to the requesting system. The request message uses the following fields as input and returns the status of the worklist entry as described in the PT_WL_GET_INSTANCE_RESP:
Request_Message_ID
Business Process Name
Business Activity
Business Event Name
Worklist Name
Instance ID
Transaction ID
The GETWLINSTANCE service operation is available only if the worklist entry was created by a web service. PeopleSoft application developers can use the WorklistEntry class IsCreatedViaWebService property to determine if a worklist entry was created by a web service.
Note: If a SOAP intermediary is able to change the value of WS-Address in the SOAP header, and you want to be able to use the GETWLINSTANCE service operation, you must populate the PT_REQUEST_MSG_ID field with a developer-defined value, and you must use the value as the key for this operation.
Describing PT_WL_GET_INSTANCE_REQ Message
The alias for this request message is GetWorklistEntryStatusData. The following table provides information about the fields in this request message:
Schema Input Field Name |
PeopleSoft Record Name |
Description |
Type |
Required |
---|---|---|---|---|
RequestMessageID |
PT_REQUEST_MSG_ID |
The message identifier that was defined by the third-party system web service developer for creating the worklist entry request message. |
String |
Yes |
BusinessProcessName |
BUSPROCNAME |
The PeopleSoft Enterprise source business process name that includes the work item. The third-party system web service developer enters the appropriate PeopleSoft value for this field. |
String |
Yes |
ActivityName |
ACTIVITYNAME |
The PeopleSoft Enterprise source activity name of the source business process. The third-party system web service developer enters the appropriate PeopleSoft value for this field. |
String |
Yes |
EventName |
EVENTNAME |
The PeopleSoft Enterprise source event name of the source activity. This field defines a routing event for PeopleSoft Workflow. The third-party system web service developer enters the appropriate PeopleSoft value for this field. |
String |
Yes |
WorklistName |
WORKLISTNAME |
The PeopleSoft Enterprise source worklist name for the source event. The third-party system web service developer enters the appropriate PeopleSoft value for this field. |
String |
Yes |
Describing PT_WL_GET_INSTANCE_RESP Message
The alias for this reply message is WorklistEntryStatusData. The following table provides information about the fields in this reply message:
Schema Input Field Name |
PeopleSoft Record Name |
Description |
Type |
---|---|---|---|
RequestMessageID |
PT_REQUEST_MSG_ID |
The message identifier that was defined by the third-party system web service developer for creating the worklist entry request message. |
String |
BusinessProcessName |
BUSPROCNAME |
The PeopleSoft Enterprise source business process name that includes the work item. The response message uses the value defined in the request message. |
String |
ActivityName |
ACTIVITYNAME |
The PeopleSoft Enterprise source activity name of the source business process. The response message uses the value defined in the request message. |
String |
EventName |
EVENTNAME |
The PeopleSoft Enterprise source event name of the source activity. This field defines a routing event for PeopleSoft Workflow. The response message uses the value defined in the request message. |
String |
WorklistName |
WORKLISTNAME |
The PeopleSoft Enterprise source worklist name for the source event. The response message uses the value defined in the request message. |
String |
InstanceID |
INSTANCEID |
A unique number that identifies the instance of the worklist entry. Value provided by PeopleSoft Enterprise. |
Number |
TransactionID |
TRANSACTIONID |
A number that identifies the worklist entry transaction. Value provided by PeopleSoft Enterprise. |
Number |
InstanceStatus |
INSTANCESTATUS |
For a given worklist, determines the worklist status—available, selected, worked, canceled. Value provided by PeopleSoft Enterprise. |
String |
ResponseStatus |
PT_WS_RESP_SENT |
Value provided by PeopleSoft Enterprise. Valid values are:
|
Number |
AdditionalData |
PT_WL_CR_ADD |
An optional section in the request message that is used by PeopleSoft Enterprise application developers to do additional processing, such as adding informational notes. This feature is available only when the assigned user selects the Programmatic option to mark the worklist entry as complete. |
SubRecord with two fields, Name and Value |
Submitting the Web Service Operation
Upon successful receipt of the create worklist entry web service request, PeopleSoft Integration Broker sends an HTTP acknowledgement to the requesting system. The request is sent to the Workflow application for creating a worklist entry for the identified user. If the worklist entry is created, the requesting system is not notified until the worklist entry is marked Worked. If the worklist entry cannot be created, PeopleSoft sends an error message to the requesting system. Upon successful receipt of the optional status request for the worklist entry, PeopleSoft Integration Broker sends an HTTP acknowledgement to the requesting system. The web service is sent to the Workflow application to obtain the status of the worklist entry, and the GetWorklistInstanceResp message is immediately returned to the requesting system.
Note: PeopleSoft application developers who want to create worklist entries locally should use the PeopleCode Notification Classes or the PeopleCode built-in function, TriggerBusiness Event.
The requesting system is responsible for ensuring the request message is sent only once. If the request message is sent a second time with a unique request message ID, the Workflow application processes the second message as a new request. This could result in the same task appearing in the end user's worklist twice. If a request message is sent twice with the same unique ID in both messages, the first attempt creates the worklist entry and the second attempt causes an error message to be sent back to the requesting system.
PeopleSoft does not provide web service operations for reassigning or canceling a worklist entry. PeopleSoft provides PeopleCode classes and a web service operation for PeopleSoft applications developers to obtain the worklist key values by using the message ID as a search parameter.