This article shows the troubleshooting methodology we use in Altiris Support to diagnose and remedy problems reported with Software Delivery Task Executions. As there are several components involved with a Task, this document covers all the mechanisms and potential problem points with the execution. This document does not cover download issues, though the symptoms associated with it are provided for reference.

Introduction

Often failed Software Delivery Tasks are due to a lack of testing of the task. It is highly recommended to rollout a Task to a test bed, even if only a couple or more systems, before rolling out into the greater environment. In this way if there is a problem with the Task, the issue can be resolved before the general rollout to the Production environment. No matter where the issue arises, this article can be used to resolve the issue, however it's cleaner to have the problem show up in testing before it hits all targeted systems.

This article covers standard Software Delivery Tasks, though the same principles can be applied to Sequential Software Delivery Tasks when a single execution in the sequence fails.

The most common issue areas for Task Execution failures are:

1. Invalid Command line - Though the command line being used here may work in other execution environments, this is often the source of the problem.
2. Insufficient User Stack - Some installers require specific user-driven environments to be available at execution.
3. Configuration - Often the way the Program is defined causes issues depending on what the installer needs to successfully execute.

General Troubleshooting

Use these steps to work through where the problem is occurring. It is essential to understand exactly where the problem lies before trying to fix it or coming to the conclusion that something is inherently wrong with the execution engine.

Note that each subsequent step assumes the previous step is resolved.

1. Is the Altiris Agent receiving the Task? This can be checked by looking at the Altiris Agent UI on a target system to see if the package is listed. If not, the most common reason is either an expired license or the license count has been exceeded.
2. Is the Altiris Agent downloading the Package successfully? In the Agent UI, double-click on the applicable package, and look at the Download History. If not, this issue must be resolved before the Task can be properly tested or executed.
   

   Click to view.

3. What is the status of the execution? To check, again double-click on the Package and look at the run history. This will provide a status and exit code. Check the exit code against the installer's documentation to see if it provides a reason for the failure.
4. If the execution is failing, take the command-line you are using for the Task and try it manually:
   1. Click on Start > Run > type 'cmd' > and click OK.
   2. Browse to a directory that contains the files for execution.
   3. Type in the command-line exactly as it is being executed by the Task.
   4. Does this fail? If it fails with the same error then there is most likely a problem with the command-line. Check the product documentation on how the command-line should be configured.
5. Caveat: The Software Delivery Execution engine does not load all the same environment variables available to a logged on user. The following items are examples illustrate this point, and must be configured as indicated in order to avoid any problems associated with a missing environment variable:
   • MSI - MSIs must be called by msiexec. For MSI command lines, the execution should look this way:

   msiexec.exe /I install.msi
   
   

   • Scripts - Scripts that require a windows or command script engine for execution require the applicable engine be called:

   cscript myscript.cs
   wscript myscript.vbs
   
   

   Note: wscript will attempt to pop up a window if the script produces any output. In these cases it is recommended to use cscript
6. If the execution is successful, but you are prompted to interact with the installation, this is a problem. See the section 'User Interaction' under Common Methods for more information.
7. If the execution works silently, there are several potential issues, as follows.
8. This may be an execution environmental problem as defined by the Program. Browse to the Program being used by the Task. This is found as the 'Program' tab which is part of the Package being used for the Task execution. The recommended configuration when seeing this problem is to:
   1. Check the option 'User Input Required'. Despite what the label implies, this instructs the Altiris Agent to load a fuller user stack. The addition of piping the execution to the user's desktop garnered it the name 'User Input Required', however as long as the command-line executes with a silent or quiet switch, or the Starting Window is set to 'Hidden', the execution won't be seen even if this option is checked.
   Note: I recommend always checking this option to avoid this potential issue
   2. Use the System Account if no network access is required. This account typically has the rights to do what is necessary.
   3. Set the Starting Window to 'Hidden'.
      

      Click to view.

9. Another potential cause concerns the inclusion of a network location in the command-line. By default we run under the System Account. If the execution requires network access at any point, the execution must be run either as the Logged-on User or as a Specified User. The user must have access to the network locations used by either the command-line or the installer.
10. A common issue with user-based application (plug-ins for Internet Explorer that are user specific, for example) is that by default we don't run in the user context. To remedy this, set the user execution context to run as the Logged-on User, and check the option 'Run once for each Logged on User'. Note that the Program can run: setting must be set to 'Only when a user is logged on'.
11. Continuing on, another potential problem is a hanging task. If the Task hangs for 6 hours (by default, this can be changed) the Altiris Agent will end the process. The reason for the hang can be several. Check the section 'Revealing the Execution' below under Common Methods.

To conclude, if the problem is with the installer it is up to you to troubleshoot that issue using the vendor of the installer's documentation. Software Delivery is an execution engine, and while we've tried to provide a default framework that is friendly for most executables, there may be times we need to work through the execution environment and command-line to find the working combination.

Common Methods

The following items are often used as part of the troubleshooting a failed execution.

User Interaction

The default mode for Software Delivery is for a Silent installation. This ensures that users will not be impacted by the execution of a Software Delivery Task. As such a default Program is set to run hidden from the user. If the command-line doesn't provide the install what it needs to run silently without user interaction, the execution will appear to 'hang'. In reality the execution occurs as designated, but the installation has popped up a user prompt in the execution environment which the user will never seen.

Normally to fix this a silent or quiet switch must be specified in the command-line to suppress all user prompts. For large application often a transform file can be used to provide the input needed for the installation. Others will have a -s or -qm type switch that instructs the installer to install with defaults.

If you want to have the installation show up, see the above section on 'Revealing the Execution'.

Revealing the Execution

Since the context of a Software Delivery execution can't be duplicated manually, sometimes it is essential to reveal the execution to see if this shows any problems.

1. Create a collection based of one or two systems to test with.
2. Assign the above collection to the Software Delivery Task you are having the issue with.
3. In the Program details (found as a tab within the configuration of the package), set the Program can run: option to "Only when a user is logged on."
4. Check the option User Input Required.
5. Click Apply.
6. On the test system, update the configuration by going into the Agent UI (double-click on the tray icon, or if the icon is hidden, execute the file C:\Program Files\Altiris\Altiris Agent\AeXAgentActivate.exe) and click the icon to the left of the #Help icon at the top of the UI, and then click the option Update Configuration. To confirm the new changes were received, both the Last Configuration Requested and Last Configuration Changed dates should be current.
7. Back to the main agent UI, select the task you are having problems with and click the link under Application Tasks to execute.
8. The program will execute and you will see the execution.

Conclusion

The methodology is proven, but what to do with what you've learned may not be answered in this article. Hopefully this will provide enough instruction so that you may discover the cause of your issue quickly and provide suggestions in remedying the issue. For those issues that are not covered by this, please contact Altiris Support for assistance.