WorklistEntry Class Methods

In this section, we discuss the WorklistEntry class methods. The methods are discussed in alphabetical order.

Syntax

Create()

Description

Use the Create method to create a new WorklistEntry object.

This method is not the same as the Create constructor. The Create constructor only creates an instance of the WorklistEntry class. To add the entry to the database, you must use this method.

The following properties must be set before calling this method:

  • busactivity

  • buseventname

  • busprocname

  • worklist

If this method completes successfully, the following properties are populated:

  • instanceid

  • transactionid

Parameters

None.

Returns

This method returns a numeric value: 0 if there is an error, nonzero if entry created successfully.

Example

import PT_WF_WORKLIST:*;

Local WorklistEntry &worklist;
Local Number &Rslt;

&worklist = create WorklistEntry();

&worklist.busprocname  = "Administer Workflow";
&worklist.busactivity  = "Send Note";
&worklist.buseventname = "Worklist Note";
&worklist.worklistname = "Worklist Note";

&Rslt = &worklist.Create();

Syntax

GetResponseStatus()

Description

Use the GetResponseStatus method to return the response status of the callback method. This is useful only for entries that are created by web services.

The following properties must be set before calling this method:

  • busactivity

  • buseventname

  • busprocname

  • requestmessageid

  • worklistname

Parameters

None.

Returns

A number. Valid values are:

Value

Description

0

CreateWorklistEntry message not received yet or this entry was not created by any web service.

1

Message received but not processed yet.

2

Message processed and sent to message queue.

3

Error while sending message to the caller of create worklist entry.

4

Message was sent to the originating web server and was received successfully.

Syntax

Reassign(Operid)

Description

The Reassign method assigns the worklist in the data buffers to the user specified by Operid. This method commits the version of the worklist entry in the data buffer to the database using the Save method.

If you want to reassign an entire worklist, use the Reassign Worklist class method.

Note: You must use the SelectByKey method to populate data buffers with the worklist entry.

Parameters

Field or Control

Definition
Operid

Specify the user ID to which you want to assign the worklist entry, as a string.

Returns

A Boolean value: true if the reassignment was successful, false otherwise.

Example

import PT_WF_WORKLIST:WorklistEntry;

       Local WorklistEntry &wl = create WorklistEntry();
       &wl.busprocname = WF_WORKLIST_VW2.BUSPROCNAME;
       &wl.busactivity = WF_WORKLIST_VW2.ACTIVITYNAME;
       &wl.buseventname = WF_WORKLIST_VW2.EVENTNAME;
       &wl.worklistname = WF_WORKLIST_VW2.WORKLISTNAME;
       &wl.instanceid = WF_WORKLIST_VW2.INSTANCEID;

       If (&wl.SelectByKey()) Then
          If Not (&wl.Reassign("TOPSUSER2")) Then
             /* Reassign error */
          End-If;
       Else
          /* SelectByKey error */
       End-If;

Syntax

Save()

Description

Use the Save method to save a WorklistEntry to the database.

PeopleCode Event Considerations

You must include this method within events that allow database updates. This includes the following PeopleCode events:

  • SavePreChange (Page)

  • SavePostChange (Page)

  • Workflow

  • FieldChange

If this method results in a failure, all database updates are rolled back. All information the user entered into the component is lost, as if the user pressed ESC.

Considerations Using Web Services

This method saves the instance of the worklist to the database. If the worklist entry is marked as worked, (that is, if inststatus property is set to 2) and the worklist entry was originally created by a web service, the originating requestor is sent a response when this method is executed. If the requestor is expecting additional data, use the SaveWithCustomData method instead.

Parameters

None.

Returns

A numeric value: 0 if save didn't complete successfully, nonzero if save completed successfully.

Example

If (&worklist.Save() <> 0) Then
   /* success */
Else
   /* handle error */
End-If;

Syntax

SaveWithCustomData(&Message, &FieldNameArray, &FieldValueArray)

Description

Use the SaveWithCustomData method to save the worklist entry to the database, as well as to pass additional data back to the requestor that created this worklist entry. You should only use this method with worklist entries that are created by web service. If you want to save a worklist entry without additional data, or a worklist entry that was not created using a web service, use the Save method instead.

If the worklist entry was not created by a web service, or if the worklist entry is not marked as worked (that is, if the inststatus property is not set to 2,) the additional data is ignored.

PeopleCode Event Considerations

You must include this method within events that allow database updates. This includes the following PeopleCode events:

  • SavePreChange (Page)

  • SavePostChange (Page)

  • Workflow

  • Message Subscription (the Integration Broker INotificationHandler interface)

  • FieldChange

If this method results in a failure, all database updates are rolled back. All information the user entered into the component is lost, as if the user pressed ESC.

Parameters

Field or Control

Definition
&Message

Specify an already instantiated and populated response message containing the custom data to be sent back to the originating web service.

&FieldNameArray

Specify an already instantiated and populated array of string containing the field names to be used by the web service that created the worklist entry.
&FieldValueArray

Specify an already instantiated and populated array of string containing matching field values to be used by the web service that created the worklist entry.

Returns

A message object containing the final message that was sent to the web service if successful, a null object otherwise.

Syntax

SelectByKey()

Description

The SelectByKey method uses the key field values that have been assigned to build and execute a Select SQL statement. The field values are then fetched from the database SQL table into the worklist entry and the Select statement is closed.

If you don’t specify all the key fields, those you exclude are added to the Where clause with the condition equal to a blank value. If not all keys are set and more than one row is retrieved, you won't receive an error and SelectByKey won’t fetch any data.

For worklist entries that were created by web services, use the SelectByMessageId method instead.

Parameters

None.

Returns

A Boolean value: true if the properties are set based on the database values, false otherwise.

Syntax

SelectByMessageId()

Description

Use the SelectByMessageId method to select a worklist entry by the message id. This is useful only for entries that are created by web services.

The following properties must be set before calling this method:

  • busactivity

  • buseventname

  • busprocname

  • requestmessageid

  • worklistname

Parameters

None.

Returns

A Boolean value: true if this method completes successfully, false otherwise.

Syntax

Update()

Description

Use the Update method to update the worklist entry with any property values that have changed, and assign values to the associated record in the database. However, this method does not commit the changes to the record in the database. You must use the Save method to update the database.

Parameters

None.

Returns

A numeric value: 0 if update didn't complete successfully, nonzero if update completed successfully.

Example

If (&worklist.Update() <> 0) Then
   &worklist.inststatus = "2"  /* mark entry worked */
   /* additional processing */
End-if;