SOAP API - getWorkListItems

The table summarizes the SOAP API - getWorkListItems.

Request Uses the getWorkListItems element (from the WorkListService schema)
Parameter notes
  • startPosition: the position in the work list from which to start the page of results. The list is zero-based. To start at the first item, specify 0.
  • numberOfItems: the number of items from the work list to include. You need to add a number. If you do not the default is 0.
  • getTotalCount (optional): whether to include a count of the total number of work items in the list. This defaults to true. The count is returned in the totalItems value in the response. Note that:

    You should set getTotalCount to false unless you specifically need the total figure, because setting it to true is expensive in terms of database access time.

    If you pass false in this attribute, and there is at least one item in the list, the totalItems value returned in the response is -1. However, if you pass false and there are no work items in the list, the totalItems value in the response is 0 (zero).

    If you pass true in this attribute but numberOfItems is set to zero, the totalItems value in the response is 0 regardless of how many items are actually in the work list. The total count of work items is only available when you are fetching one or more work items.

  • getEnhancedAttributes (optional, default=false): If true, all 40 work item attributes are returned with the work item; if false, only work item attributes 1-14 are returned with the work item.
Enter one of resourcesRequired or entityID, plus optionally qualifierSet and orderFilterCriteria:
  • resourcesRequired (optional): the only valid value is ALL. Returns a work list for all resources, subject to the orderFilterCriteria specified.

    Note that if ALL is specified, the query does not return the total count.

  • entityID:
    • model-version: can be obtained using listOrgModelVersions.
    • entity-type: The type of organization model entity for which the work list is being returned.
    • guid: The GUID of the organizational entity whose work list you want to retrieve.
    • qualifier: Only applicable in certain circumstances, and only to organization model entities whose entity-type is PRIVILEGE or CAPABILITY. These entities can have an association with other entities, for example, a resource may hold many capabilities, or a position may have many privileges. These associations can have a qualifying value, according to their nature, to differentiate them. For example, the PRIVILEGE to sign off a purchase order may be qualified with the maximum amount that can be signed off.
  • qualifierSet (optional): An optional collection of qualifying values. This overrides any qualifier attribute set on the parent element, allowing more than one value to be set. Multiple values will only be used for qualifiers of type "enumset".
  • orderFilterCriteria (optional): sort or filter criteria, or both, to determine how the work items are to be filtered and presented. See Sorting and Filtering Work Lists for details of the syntax and content of these criteria.
Response Returns a getWorkListItemsResponse element (from the WorkListService schema)
Example 1 Request: 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com">
   <soapenv:Header/>
   <soapenv:Body>
      <api:getWorkListItems 
  startPosition="0" numberOfItems="5" getTotalCount="true" getEnhancedAttributes="true">
         <entityID model-version="-1" entity-type="POSITION" guid="_5i1V0CfLEeChutsy_vK9tg" >
         </entityID>
         <orderFilterCriteria>
            <order>id ASC</order>
            <filter>state=OFFERED</filter>
         </orderFilterCriteria>
      </api:getWorkListItems>
   </soapenv:Body>
</soapenv:Envelope>
  Response: 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <getWorkListItemsResponse xmlns="http://api.brm.n2.tibco.com">
         <startPosition xmlns="">0</startPosition>
         <endPosition xmlns="">2</endPosition>
         <totalItems xmlns="">3</totalItems>
         <workItems xmlns="">
            <id id="2" version="0"/>
            <header distributionStrategy="OFFER" priority="50">
               <name>DisplayMessage</name>
               <description>Display Message</description>
               <flags>
                  <scheduleStatus>DURING</scheduleStatus>
               </flags>
               <itemContext>
                  <activityID>pvm:001if</activityID>
                  <activityName>DisplayMessage</activityName>
                  <appInstance>pvm:0a122</appInstance>
                  <appName>WelcomeUsers</appName>
                  <appID>_-fPYwCIVEeCnP8eZZTCDGg</appID>
               </itemContext>
            </header>
            <state>OFFERED</state>
            <visible>true</visible>
         </workItems>
         <workItems xmlns="">
            <id id="3" version="0"/>
            <header distributionStrategy="OFFER" priority="50">
               <name>DisplayMessage</name>
               <description>Display Message</description>
               <flags>
                  <scheduleStatus>DURING</scheduleStatus>
               </flags>
               <itemContext>
                  <activityID>pvm:001io</activityID>
                  <activityName>DisplayMessage</activityName>
                  <appInstance>pvm:0a123</appInstance>
                  <appName>WelcomeUsers</appName>
                  <appID>_-fPYwCIVEeCnP8eZZTCDGg</appID>
               </itemContext>
            </header>
            <state>OFFERED</state>
            <visible>true</visible>
         </workItems>
      </getWorkListItemsResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example 2 Request: 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.brm.n2.tibco.com">
   <soapenv:Header/>
   <soapenv:Body>
      <api:getWorkListItems 
 <getEnhancedAttributes="true" startPosition="0" numberOfItems="100">
         <resourcesRequired>ALL</resourcesRequired>
      </api:getWorkListItems>
   </soapenv:Body>
</soapenv:Envelope>
  Response: 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <getWorkListItemsResponse xmlns="http://api.brm.n2.tibco.com">
         <startPosition xmlns="">0</startPosition>
         <endPosition xmlns="">2</endPosition>
         <totalItems xmlns="">-1</totalItems>
         <workItems xmlns="">
            <id id="5" version="0"/>
            <header distributionStrategy="OFFER" endDate="2013-06-28T09:47:33.713Z" priority="30" startDate="2013-06-26T09:47:33.713Z">
               <name>Test Entity Work Lists Group</name>
               <description>Test Entity Work Lists Group</description>
               <itemContext>
                  <activityID>SoapUI Scheduled Item</activityID>
                  <activityName>SoapUI Scheduled Item</activityName>
                  <appInstance>SoapUI</appInstance>
                  <appName>SoapUI</appName>
                  <appID>Model ID</appID>
               </itemContext>
            </header>
            <state>OFFERED</state>
            <visible>true</visible>
         </workItems>
         <workItems xmlns="">
            <id id="6" version="0"/>
            <header distributionStrategy="OFFER" endDate="2013-06-28T09:47:33.987Z" priority="30" startDate="2013-06-26T09:47:33.987Z">
               <name>Test Entity Work Lists Resource</name>
               <description>Test Work Lists Resource</description>
               <itemContext>
                  <activityID>SoapUI Scheduled Item</activityID>
                  <activityName>SoapUI Scheduled Item</activityName>
                  <appInstance>SoapUI</appInstance>
                  <appName>SoapUI</appName>
                  <appID>Model ID</appID>
               </itemContext>
            </header>
            <state>OFFERED</state>
            <visible>true</visible>
         </workItems>
         <workItems xmlns="">
      </getWorkListItemsResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>