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:

  • blank–no priority

  • 1–high priority

  • 2–medium priority

  • 3–low priority

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.

See IsCreatedViaWebService.

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:

  • 0–No such entry created. This may happen because the worklist entry creation request has not been processed.

  • 1: Entry is created successfully but it is not marked Worked.

  • 2: Entry was marked Worked and a response is sent to PeopleSoft Integration Broker for sending the response message to the originating third-party system.

  • 3: Entry was marked Worked but the response could not be sent to the originating third-party system.

  • 4: Entry was marked Worked and the response was successfully sent to the originating third-party system.

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.