App Distribution Settings
Use the App Distribution > Settings page to configure app return code mappings. Executable and script package actions may return a positive or negative numeric code on exit indicating various outcomes. These return codes affect the app state and determine whether an action succeeds, fails, or requires a reboot.
Use custom return code mappings to customize the result of EXE, MSI, and script actions. For example, Microsoft's Robocopy utility has several return codes that indicate success. By default, a non-zero executable return code indicates failure. You could create a custom return code mapping for Robocopy that maps these non-zero return codes to success, allowing package processing to continue.
Return codes are stored in a log on the device as part of each app distribution. For more information on logs and how to access them, see Detection rule and action logging.
In addition to having numeric return codes stored in the log, you can map those return codes to informative strings. These strings describing the return codes will also appear in the log.
There are three return code template types:
- New templates that you create.
- Cloned copies of an existing template. To clone an existing template, use the options menu ( ) to the right of that template.
- Default templates that you can not edit or delete, other than marking one as a default template. You can edit a cloned copy.
These are the default return code templates. The default behavior for unmapped return codes in these templates is failure.
- System Template - Default MSI: Contains the standardized set of MSI return codes. These are preconfigured for you.
- System Template - Default EXE: Contains one return code mapping for the number zero, indicating success.
- System Template - Default PowerShell: Contains two return code mappings. The number zero indicating success, and the number one indicating failure.
One of each template type, MSI, EXE, and PowerShell can be marked as a default. The Return code mappings list has a column showing which templates are defaults. To change a default, edit the template and select that option.
When you create a package action that supports a return code template, the default will be preselected for you. If you do not want to use the default, you can select from other templates for that action type. Template changes you make take effect the next time the app distribution engine runs on the client.
MSI return code templates include a return code mapping for 3010, Success - Reboot required. This result is the same as Success, but with a note in the device's log for that distribution that it will need a reboot at some point. The deployment status will also show "Success (reboot required)" for that package.
To create or edit a return code template
- Select Create new and the template type you want, or select an existing template. The preconfigured system templates are read-only.
- Enter a Template name and Description.
- Under Make this the default template, select True if you want this template to be the default for the template type you selected (such as EXE or PowerShell).
- Select the Default result for unmapped return codes. The default is Failure. The result you select is what will occur for any return code that comes back from the action which is not listed in the return code list. For example, if you choose Failure (recommended), then all return codes not in the list will cause the action to be returned as failed. If you choose Success, then all other return codes will be returned as succeeded.
- Specify the Default message text that appears for your selected default unmapped return code result.
- Select + Add return code.
- Enter the Return code number or number range in integer format (no decimals), Result (Failure or Success), and the Message text you want logged along with the return code. To enter a number range, separate the numbers with two periods, such as 15..30.
- Select Save.
- Repeat steps 7 and 8 for each return code you want.
- When you are done, close the Add new mapping panel and select Save.