Documentation Center

BackgroundTask 2.5 Find

Used to identify all background tasks that match the criteria given in the metadata filter.


Parameters

NameTypeDirectionDescription
psAuthContextStringInOutDeprecated proprietary authentication context only used by .ASMX web services based on internal username/password authentication. Claims based security standards drive all the WCF .SVC web services, making this parameter redundant.
pdModifiedSinceDateInA date limiting the background tasks that will be retrieved based on the last modification date of the background tasks
peUserFiltereUserFilterInEnumeration indicating if only background tasks of the current user or all background tasks must be retrieved
psXMLMetadataFilterStringInBackground Task Metadata Filter XML structure with additional filter on metadata to limit the background tasks on which metadata has to be returned.
psXMLRequestedMetadataStringInRequested Background Task Metadata XML structure indicating which metadata has to be retrieved for the given background tasks
psOutXMLTaskListStringOutBackground Tasks XML structure containing the metadata of the background tasks.

Note that:

  • Although all dates (CREATIONDATE, EXECUTEAFTERDATE, LEASEDON,...) are stored as UTC date time in the database,
    • the filter values in psXMLMetaDataFilter are assumed to be in the local date time of the application server
    • the requested dates are returned in the local date time of the application server
  • If the parameter peUserFilter is set to Current, only background tasks that are associated with the current user will be retrieved. Otherwise the background tasks associated to all users are retrieved.
  • You can retrieve the data reference of the inputdata (= INPUTDATAID) and outputdata (=OUTPUTDATAID), but this method will not return the content itself.
  • The history level contains information about one single execution of the background task.
    • As long as the background task did not start to execute the background task yet, there is not history information.
    • If you don"t filter on history information, the information of the background task is returned even if the requested metadata contains fields of the history level and there is no history information yet.
Which fields can be used to filter or retrieve information?
FieldLevelDescription
TASKIDtaskThe column "TASKID" contains the unique identifier of the background task. This value can only be used for filtering!
HISTORYIDhistoryThe column "HISTORYID" contains the unique identifier of one of the history record of the background task. This value can only be used for filtering!
USERIDtaskThe user that started the background task
STATUStaskThe status of the background task
HASHIDtaskString containing the "hash" representation for this background task. This will be used to skip older background task for the same action. For instance, synchronizing the same language object only once to SDL LiveContent.
EVENTTYPEtaskThe type of the event (e.g PUBLISH)
PROGRESSIDtaskThe unique identifier of the event log linked with this background task
TRACKINGIDtaskCurrently the trackingId is the same as the progressId
CREATIONDATEtaskThe date time that the background task was created
MODIFICATIONDATEtaskThe date time that the background task was last modified
EXECUTEAFTERDATEtaskThe background task should not be executed before this date time.
LEASEDONtaskThe date and time when background task was leased
LEASEDBYtaskThe id of the process/thread that leased the background task
CURRENTATTEMPTtaskNumber containing the current attempt
INPUTDATAIDtaskData reference linking to the inputdata of the background task
OUTPUTDATAIDtaskData reference linking to the outputdata of the last execution of the background task
EXITCODEhistoryThe exit code for this background task execution
ERRORNUMBERhistoryThe error number thrown by this background task execution
OUTPUThistoryData reference linking to the outputdata of this background task execution
ERRORhistoryData reference linking to the detailed error of this background task execution
STARTDATEhistoryThe date time that this execution of the background task was started
ENDDATEhistoryThe date time that this execution of the background task was finished
HOSTNAMEhistoryThe host name from which the background task was created

What are the possible statuses?

LabelElementDescription
PendingVBACKGROUNDTASKSTATUSPENDING

The background task waiting to be executed by the service.

This status can occur when:

  • The background task is created, but is not picked up by the service yet
  • The background task failed and is waiting to be retried.
ExecutingVBACKGROUNDTASKSTATUSEXECUTINGThe background task service is running the background task
SkippedVBACKGROUNDTASKSTATUSSKIPPEDThe background task service found a more recent background task with the same hashId. The current background task is skipped and the more recent one will be executed.
FailedVBACKGROUNDTASKSTATUSFAILEDIf there was no successful execution after the configured number of attempts, the background task is marked as failed.
SuccessVBACKGROUNDTASKSTATUSSUCCESSThe background task finished "successfully".

Example

When you do the BackgroundTask25.Find for the Current user with following metadata filter:
<ishfields>
  <ishfield name="EVENTTYPE" level="task" ishvaluetype="element">VEVENTTYPEPUBLISH</ishfield>
</ishfields>
and following requested metadata:
<ishfields>
    <ishfield name="USERID" level="task"/>
    <ishfield name="USERID" level="task" ishvaluetype="element"/>
    <ishfield name="HASHID" level="task"/>
    <ishfield name="STATUS" level="task"/>
    <ishfield name="STATUS" level="task" ishvaluetype="element"/>
    <ishfield name="EVENTTYPE" level="task"/>
    <ishfield name="EVENTTYPE" level="task" ishvaluetype="element"/>
    <ishfield name="PROGRESSID" level="task"/>
    <ishfield name="TRACKINGID" level="task"/>
    <ishfield name="CREATIONDATE" level="task"/>
    <ishfield name="MODIFICATIONDATE" level="task"/>
    <ishfield name="EXECUTEAFTERDATE" level="task"/>
    <ishfield name="LEASEDON" level="task"/>
    <ishfield name="LEASEDBY" level="task"/>
    <ishfield name="CURRENTATTEMPT" level="task"/>
    <ishfield name="INPUTDATAID" level="task"/>
    <ishfield name="OUTPUTDATAID" level="task"/>
    <ishfield name="EXITCODE" level="history"/>
    <ishfield name="ERRORNUMBER" level="history"/>
    <ishfield name="OUTPUT" level="history"/>
    <ishfield name="ERROR" level="history"/>
    <ishfield name="STARTDATE" level="history"/>
    <ishfield name="ENDDATE" level="history"/>
    <ishfield name="HOSTNAME" level="history"/>
</ishfields>
this can result in something like:
<?xml version="1.0" encoding="utf-16"?>
<ishbackgroundtasks>
    <ishbackgroundtask ishtaskref="169075" ishhistoryref="122259">
        <ishfields>
            <ishfield name="USERID" level="task">admin</ishfield>
            <ishfield name="USERID" level="task" ishvaluetype="element">VUSERADMIN</ishfield>
            <ishfield name="HASHID" level="task">464975</ishfield>
            <ishfield name="STATUS" level="task">Failed</ishfield>
            <ishfield name="STATUS" level="task" ishvaluetype="element">VBACKGROUNDTASKSTATUSFAILED</ishfield>
            <ishfield name="EVENTTYPE" level="task">PUBLISH</ishfield>
            <ishfield name="EVENTTYPE" level="task" ishvaluetype="element">VEVENTTYPEPUBLISH</ishfield>
            <ishfield name="PROGRESSID" level="task">477496</ishfield>
            <ishfield name="TRACKINGID" level="task">477496</ishfield>
            <ishfield name="CREATIONDATE" level="task">21/09/2018 16:18:43</ishfield>
            <ishfield name="MODIFICATIONDATE" level="task">21/09/2018 16:18:58</ishfield>
            <ishfield name="EXECUTEAFTERDATE" level="task">21/09/2018 16:18:43</ishfield>
            <ishfield name="LEASEDON" level="task">21/09/2018 16:18:58</ishfield>
            <ishfield name="LEASEDBY" level="task"/>
            <ishfield name="CURRENTATTEMPT" level="task">1</ishfield>
            <ishfield name="INPUTDATAID" level="task">177428</ishfield>
            <ishfield name="OUTPUTDATAID" level="task"/>
            <ishfield name="EXITCODE" level="history"/>
            <ishfield name="ERRORNUMBER" level="history">-142</ishfield>
            <ishfield name="OUTPUT" level="history"/>
            <ishfield name="ERROR" level="history">177431</ishfield>
            <ishfield name="STARTDATE" level="history">21/09/2018 16:18:52</ishfield>
            <ishfield name="ENDDATE" level="history">21/09/2018 16:18:58</ishfield>
            <ishfield name="HOSTNAME" level="history">devserver01</ishfield>
        </ishfields>
    </ishbackgroundtask>    
    <ishbackgroundtask ishtaskref="169080" ishhistoryref="122264">
        <ishfields>
            <ishfield name="USERID" level="task">admin</ishfield>
            <ishfield name="USERID" level="task" ishvaluetype="element">VUSERADMIN</ishfield>
            <ishfield name="HASHID" level="task">1041540</ishfield>
            <ishfield name="STATUS" level="task">Success</ishfield>
            <ishfield name="STATUS" level="task" ishvaluetype="element">VBACKGROUNDTASKSTATUSSUCCESS</ishfield>
            <ishfield name="EVENTTYPE" level="task">PUBLISH</ishfield>
            <ishfield name="EVENTTYPE" level="task" ishvaluetype="element">VEVENTTYPEPUBLISH</ishfield>
            <ishfield name="PROGRESSID" level="task">477501</ishfield>
            <ishfield name="TRACKINGID" level="task">477501</ishfield>
            <ishfield name="CREATIONDATE" level="task">21/09/2018 16:20:45</ishfield>
            <ishfield name="MODIFICATIONDATE" level="task">21/09/2018 16:21:29</ishfield>
            <ishfield name="EXECUTEAFTERDATE" level="task">21/09/2018 16:20:45</ishfield>
            <ishfield name="LEASEDON" level="task">21/09/2018 16:21:29</ishfield>
            <ishfield name="LEASEDBY" level="task"/>
            <ishfield name="CURRENTATTEMPT" level="task">1</ishfield>
            <ishfield name="INPUTDATAID" level="task">177434</ishfield>
            <ishfield name="OUTPUTDATAID" level="task"/>
            <ishfield name="EXITCODE" level="history"/>
            <ishfield name="ERRORNUMBER" level="history">0</ishfield>
            <ishfield name="OUTPUT" level="history"/>
            <ishfield name="ERROR" level="history"/>
            <ishfield name="STARTDATE" level="history">21/09/2018 16:21:00</ishfield>
            <ishfield name="ENDDATE" level="history">21/09/2018 16:21:29</ishfield>
            <ishfield name="HOSTNAME" level="history">devserver01</ishfield>
        </ishfields>
    </ishbackgroundtask>
    <ishbackgroundtask ishtaskref="169082" ishhistoryref="122266">
        <ishfields>
            <ishfield name="USERID" level="task">admin</ishfield>
            <ishfield name="USERID" level="task" ishvaluetype="element">VUSERADMIN</ishfield>
            <ishfield name="HASHID" level="task">464975</ishfield>
            <ishfield name="STATUS" level="task">Executing</ishfield>
            <ishfield name="STATUS" level="task" ishvaluetype="element">VBACKGROUNDTASKSTATUSEXECUTING</ishfield>
            <ishfield name="EVENTTYPE" level="task">PUBLISH</ishfield>
            <ishfield name="EVENTTYPE" level="task" ishvaluetype="element">VEVENTTYPEPUBLISH</ishfield>
            <ishfield name="PROGRESSID" level="task">477503</ishfield>
            <ishfield name="TRACKINGID" level="task">477503</ishfield>
            <ishfield name="CREATIONDATE" level="task">21/09/2018 16:23:55</ishfield>
            <ishfield name="MODIFICATIONDATE" level="task">21/09/2018 16:24:02</ishfield>
            <ishfield name="EXECUTEAFTERDATE" level="task">21/09/2018 16:23:55</ishfield>
            <ishfield name="LEASEDON" level="task">21/09/2018 16:24:02</ishfield>
            <ishfield name="LEASEDBY" level="task">devserver01#6032#414b55d6e0c34c40a8da89d3864e5624</ishfield>
            <ishfield name="CURRENTATTEMPT" level="task">1</ishfield>
            <ishfield name="INPUTDATAID" level="task">177436</ishfield>
            <ishfield name="OUTPUTDATAID" level="task"/>
            <ishfield name="EXITCODE" level="history"/>
            <ishfield name="ERRORNUMBER" level="history"/>
            <ishfield name="OUTPUT" level="history"/>
            <ishfield name="ERROR" level="history"/>
            <ishfield name="STARTDATE" level="history">21/09/2018 16:24:04</ishfield>
            <ishfield name="ENDDATE" level="history"/>
            <ishfield name="HOSTNAME" level="history">devserver01</ishfield>
        </ishfields>
    </ishbackgroundtask>
    <ishbackgroundtask ishtaskref="169084">
        <ishfields>
            <ishfield name="USERID" level="task">admin</ishfield>
            <ishfield name="USERID" level="task" ishvaluetype="element">VUSERADMIN</ishfield>
            <ishfield name="HASHID" level="task">464977</ishfield>
            <ishfield name="STATUS" level="task">Pending</ishfield>
            <ishfield name="STATUS" level="task" ishvaluetype="element">VBACKGROUNDTASKSTATUSPENDING</ishfield>
            <ishfield name="EVENTTYPE" level="task">PUBLISH</ishfield>
            <ishfield name="EVENTTYPE" level="task" ishvaluetype="element">VEVENTTYPEPUBLISH</ishfield>
            <ishfield name="PROGRESSID" level="task">477505</ishfield>
            <ishfield name="TRACKINGID" level="task">477505</ishfield>
            <ishfield name="CREATIONDATE" level="task">21/09/2018 16:24:06</ishfield>
            <ishfield name="MODIFICATIONDATE" level="task">21/09/2018 16:24:06</ishfield>
            <ishfield name="EXECUTEAFTERDATE" level="task">21/09/2018 16:24:06</ishfield>
            <ishfield name="LEASEDON" level="task"/>
            <ishfield name="LEASEDBY" level="task"/>
            <ishfield name="CURRENTATTEMPT" level="task">1</ishfield>
            <ishfield name="INPUTDATAID" level="task">177438</ishfield>
            <ishfield name="OUTPUTDATAID" level="task"/>
        </ishfields>
    </ishbackgroundtask>
</ishbackgroundtasks>