Understanding the ‘Special’ Items in the BatchPatch Job Queue

The BatchPatch Job Queue has a number of “special” items that you can use to control the behavior of the queue. You can see these options in the screenshots below. Today I’m going to explain each of these special actions.


    Wait X minutes

  • Wait X minutes – This action is pretty self-explanatory. You can add a wait period to your job queue if you need the queue to pause for a period of time before continuing execution. The most common reason an administrator uses a wait period is when rebooting a target computer to give it ample time to shutdown and restart before the next queue action is executed. You can string together multiple wait periods, if desired. Here is one possible way you might use a wait period in your job queue:
    Step 1: Download and install updates + reboot always
    Step 2: Wait 10 minutes
    Step 3: Download and install updates + reboot if required

  • Wait for host to be detected online

  • Wait for host to be detected online – If you insert a ‘Wait for host to be detected online’ into your job queue, when the queue reaches this step it will check to see if it can ping the target computer and perform a successful WMI query. If it can do both of these, then the queue will advance to the next step. If it cannot do both, then it will wait a minute before trying again. The loop will continue until it is successful or until the global timeout is reached. When the global timeout is reached the queue will either terminate or continue, depending on how you have set your global timeout configuration. You can see the timeout configuration options in the screenshot below.

    IMPORTANT: ‘Wait for host to be detected online’ should generally not be placed immediately after a reboot action. The reason for this is because in that case the ‘Wait for host to be detected online’ will occur just a split second after the reboot is initiated, which means that the target computer will probably still be online, and so the check will complete successfully, and the next step in the queue will be triggered. The problem is that the machine will then probably go offline while that next step is executing, which will create undesirable results. Here is one possible way you might use ‘Wait for host to be detected online’ in your job queue.

    Step 1: Download and install updates + reboot always
    Step 2: Wait 10 minutes
    Step 3: Wait for host to be detected online
    Step 4: Download and install updates + reboot if required

  • Wait for host to go offline and come back online

  • Wait for host to go offline and come back online – This special action provides you with an alternative way to wait for a computer to reboot before executing more actions. If this action is used immediately after a reboot step, BatchPatch will monitor the target computer until it goes offline and comes back online. The target computer is not considered online again until it is both pingable and responding to WMI queries. If the global timeout is reached before the computer goes offline and comes back online, the queue will either continue or be terminated, depending on how you have set your global timeout configuration. You can see the timeout configuration options in the screenshot below.

    IMPORTANT: ‘Wait for host to go offline and come back online’ should be used carefully. In particular, we do not recommend using this special action with virtual machine target computers. The reason for this is because virtual machines can often reboot within just a couple of seconds, which unfortunately can be too fast for BatchPatch to successfully detect. If the machine reboots so rapidly that BatchPatch does not know that it ever went offline, then ‘Wait for host to go offline and come back online’ will hang until the global timeout is reached, which will leave you with undesirable results. Here is one possible way you might use ‘Wait for host to go offline and come back online’ in your job queue when the target computer is not a virtual machine.

    Step 1: Download and install updates + reboot always
    Step 2: Wait for host to go offline and come back online
    Step 3: Download and install updates + reboot if required

  • Wait for host to have zero logged-on users

  • Wait for host to have zero logged-on users – Just as it sounds, this special item will cause the BatchPatch job queue to wait until the target computer does not have any logged-on users before proceeding with the next step in the job queue. Here is one possible way you might use ‘Wait for host to go offline and come back online’ in your job queue when the target computer is not a virtual machine.
    Step 1: Wait for host to have zero logged-on users
    Step 2: Download and install updates + reboot if required

  • Terminate queue if previous ‘Check for available updates’ finds 0 updates

  • Terminate queue if previous ‘Check for available updates’ finds 0 updates – This special item works in conjunction with ‘Check for available updates’ to determine whether or not to continue the queue or terminate it. Here is one possible way you might use “Terminate queue if previous ‘Check for available updates’ finds 0 updates” in your job queue. As soon as a ‘Check for available updates’ finds 0 available updates, the queue will terminate.
    Step 1: Check for available updates
    Step 2: Terminate queue if previous 'Check for available updates' finds 0 updates
    Step 3: Download and install updates + reboot always
    Step 4: Check for available updates
    Step 5: Terminate queue if previous 'Check for available updates' finds 0 updates
    Step 6: Download and install updates + reboot always
    Step 7: Check for available updates
    Step 8: Terminate queue if previous 'Check for available updates' finds 0 updates
    Step 9: Download and install updates + reboot always

  • Terminate queue if previous action fails/errors

  • Terminate queue if previous action fails/errors – This option is typically used when incorporating custom scripts into your job queue. Failure of a script or action is determined by the return value of that script/action. Any non-zero return value will be considered a failure/error by the BatchPatch job queue. So if you want to run a custom script before downloading and installing updates, and you only want the download/install to occur if the script performs desired actions, then have your script return 0 when successful and some non-zero value when it’s not successful. Then you can setup a job queue similar to this:
    Step 1: Execute your custom remote command here
    Step 2: Terminate queue if previous action fails/errors
    Step 3: Download and install updates + reboot if required

  • Abort basic multi-row sequence if previous action fails/errors

  • Abort basic multi-row sequence if previous action fails/errors – Unlike the aforementioned item to ‘Terminate queue if previous action fails/errors’ this action will not terminate the current job queue but will instead terminate the entire basic multi-row queue sequence that this job queue is running in. The current job queue will complete, but the basic multi-row queue sequence will stop there. No more rows will be triggered.

    IMPORTANT: If you want/need both the current queue *and* the basic multi-row queue sequence to be terminated if the previous action fails/errors, then you would need your job queue to look something like this. If you were to swap the order of steps 2 and 3, you would not get the desired behavior:

    Step 1: Execute your custom remote command here
    Step 2: Terminate basic multi-row sequence if previous action fails/errors
    Step 3: Terminate queue if previous action fails/errors
    Step 4: Download and install updates + reboot if required

  • Abort advanced multi-row sequence if previous action fails/errors

  • Abort advanced multi-row sequence if previous action fails/errors – Unlike the aforementioned item to ‘Terminate queue if previous action fails/errors’ this action will not terminate the current job queue but will instead terminate the entire advanced multi-row queue sequence that this job queue is running in. The current job queue will complete, but the advanced multi-row queue sequence will stop there. No more rows will be triggered.

    IMPORTANT: If you want/need both the current queue *and* the advanced multi-row queue sequence to be terminated if the previous action fails/errors, then you would need your job queue to look something like this. If you were to swap the order of steps 2 and 3, you would not get the desired behavior:

    Step 1: Execute your custom remote command here
    Step 2: Terminate advanced multi-row sequence if previous action fails/errors
    Step 3: Terminate queue if previous action fails/errors
    Step 4: Download and install updates + reboot if required
This entry was posted in Blog, General, Tutorials and tagged , . Bookmark the permalink. Both comments and trackbacks are currently closed.