Templates

The following processors rely on XML template files in addition to any required variables:

• JamfComputerGroupUploader
• JamfPolicyUploader
• JamfPatchUploader
• JamfComputerProfileUploader
• JamfMacAppUploader
• JamfMobileDeviceAppUploader
• JamfMobileDeviceProfileUploader
• JamfObjectUploader (XML or JSON depending on object type)

An easy way to create a new template is to create an object in the Jamf Pro GUI, and then download it using the API.

How to download an API object

The easiest way to download a Policy or Smart Group is using ExportJamfXML.html by Gabriel Sroka. This is a web browser extension that allows you to download the XML directly from the GUI page of the object you want.

You can also download the XML or JSON object using JamfObjectReader. This is most easily done using jamf-upload.sh. For example, the following command will download the XML for the policy named "Firefox" and save it in the /Users/Shared folder:

./jamf-upload.sh read --url https://my.jamfcloud.com --type policy --name "Firefox" --output /Users/Shared

Another good way to download an API object is using jamf-cli. This works using a command such as:

# get the ID of an object by listing them all
jamf-cli pro <endpoint> list

# download the template in the appropriate format (XML for classic endpoints, JSON for Pro/Platform endpoints)
jamf-cli pro <endpoint> get <id> --output xml --out-file /path/to/file.xml

Note that jamf-cli prettifies the XML that you download - no need to use xmllint to reformat it.

The appropriate commands for obtaining the correct template for some example endpoints are as follows:

Processor	jamf-cli endpoint name	appropriate output format
JamfComputerGroupUploader	classic-computer-groups	xml
JamfPolicyUploader	classic-policies	xml
JamfPatchUploader	classic-patch-policies	xml
JamfComputerProfileUploader	classic-macos-config-profiles	xml
JamfMacAppUploader	classic-mac-apps	xml

Run jamf-cli pro --help for a complete list of endpoints. For anything classic, output asxml. For everything else, output as json.

How to convert a downloaded API object file into a template

Converting a downloaded API object file into a template involves three stages:

• Remove all id keys
• Remove unnecessary sections
• Replace unique names with variables

Click here for an example downloaded Policy XML file.

Remove id keys

All id keys need to be removed from the file. Providing id values are not necessary when uploading, and uploads will fail if they are not removed. So remove all id tags completely (note there are no id keys in Smart Groups):

e.g. Before:

    <category>
      <id>2</id>
      <name>Testing</name>
    </category>

After:

    <category>
      <name>Testing</name>
    </category>

Remove unnecessary sections

You only need to provide a small number of keys that are essential to the API object. Everything else can be removed, with the slight caveat that if values in a section had previously been provided, and you remove the entire section before uploading the template to the same ID, the earlier values will remain. You can instead provide an empty tag for that section (Note: there are no unnecessary sections in Smart Groups).

As an example, we will look at the downloaded "Install Latest Adium" policy we linked to above. Here is the user_interaction section:

  <user_interaction>
    <message_start/>
    <allow_users_to_defer>false</allow_users_to_defer>
    <allow_deferral_until_utc/>
    <allow_deferral_minutes>0</allow_deferral_minutes>
    <message_finish/>
  </user_interaction>

If we don't need to set any non-default values in this section, we can delete all these lines. Or, to be extra sure to remove any earlier non-default values, we can replace it with this:

  <user_interaction/>

It's quite common to reduce the keys to a bare minimum. The general section can often be reduced to:

  <general>
    <name>Install Latest Adium</name>
    <enabled>true</enabled>
    <trigger>USER_INITIATED</trigger>
    <frequency>Ongoing</frequency>
    <category>
      <name>Testing</name>
    </category>
  </general>

The scope section may be reduced to:

  <scope>
    <all_computers>false</all_computers>
    <computers/>
    <computer_groups>
      <computer_group>
        <name>Adium-update-smart</name>
      </computer_group>
    </computer_groups>
    <exclusions>
      <computers/>
      <computer_groups/>
    </exclusions>
  </scope>

Or if the policy is to be scoped to all computers, this section can simply be:

  <scope>
    <all_computers>true</all_computers>
  </scope>

Self Service policies can have the self_service section reduced to the following. Note that the self_service_icon section should be removed, because you cannot supply a policy icon directly from a URL (this is handled separately in the JamfPolicyUploader processor - you have to put the icon in your repo):

  <self_service>
    <use_for_self_service>true</use_for_self_service>
    <self_service_display_name>Adium</self_service_display_name>
    <install_button_text>Install 1.5.10.4</install_button_text>
    <reinstall_button_text>Reinstall 1.5.10.4</reinstall_button_text>
    <self_service_description>Popular instant messaging client supports a plethora of services.</self_service_description>
    <force_users_to_view_description>false</force_users_to_view_description>
    <feature_on_main_page>false</feature_on_main_page>
    <self_service_categories>
      <category>
        <name>Testing</name>
        <display_in>true</display_in>
        <feature_in>false</feature_in>
      </category>
    </self_service_categories>
    <notification>false</notification>
    <notification>Self Service</notification>
    <notification_subject/>
    <notification_message/>
  </self_service>

Package configuration:

  <package_configuration>
    <packages>
      <size>1</size>
      <package>
        <name>Adium-1.5.10.4.pkg</name>
      </package>
    </packages>
  </package_configuration>

Scripts (if there are none):

  <scripts>
    <size>0</size>
  </scripts>

And maintenance (if you want a recon after the policy runs):

  <maintenance>
    <recon>true</recon>
  </maintenance>

Click here to see the final edited policy.

Replace unique names with variables

Of course, to become a template, we need to remove the values specific to the item we downloaded and replace them with variables. In AutoPkg, variables are wrapped with percent signs, for example %policy_name%. So, to replace our unique policy name and category with variables:

Before:

  <general>
    <name>Install Latest Adium</name>
    <enabled>true</enabled>
    <frequency>Ongoing</frequency>
    <category>
      <name>Testing</name>
    </category>
  </general>

After:

  <general>
    <name>%policy_name%</name>
    <enabled>true</enabled>
    <frequency>Ongoing</frequency>
    <category>
      <name>%POLICY_CATEGORY%</name>
    </category>
  </general>

The package name is provided as follows, since the pkg_name variable is supplied by a parent .pkg recipe:

  <package_configuration>
    <packages>
      <size>1</size>
      <package>
        <name>%pkg_name%</name>
      </package>
    </packages>
  </package_configuration>

Any desired version strings can be replaced with %version%, which should also have been provided in a parent recipe. For example:

    <install_button_text>Install %version%</install_button_text>
    <reinstall_button_text>Reinstall %version%</reinstall_button_text>

Click here for the same policy template with all values substituted for variables. This file is now ready for use as your policy template.

<?xml version="1.0" encoding="UTF-8"?>
<policy>
  <general>
    <name>%POLICY_NAME%</name>
    <enabled>true</enabled>
    <frequency>Ongoing</frequency>
    <category>
      <name>%POLICY_CATEGORY%</name>
    </category>
  </general>
  <scope>
    <all_computers>false</all_computers>
    <computers/>
    <computer_groups>
      <computer_group>
        <name>%GROUP_NAME%</name>
      </computer_group>
    </computer_groups>
    <exclusions>
      <computers/>
      <computer_groups/>
    </exclusions>
  </scope>
  <self_service>
    <use_for_self_service>true</use_for_self_service>
    <self_service_display_name>%SELF_SERVICE_DISPLAY_NAME%</self_service_display_name>
    <install_button_text>Install %version%</install_button_text>
    <reinstall_button_text>Reinstall %version%</reinstall_button_text>
    <self_service_description>%SELF_SERVICE_DESCRIPTION%</self_service_description>
    <force_users_to_view_description>false</force_users_to_view_description>
    <feature_on_main_page>false</feature_on_main_page>
    <self_service_categories>
      <category>
        <name>%POLICY_CATEGORY%</name>
      </category>
    </self_service_categories>
  </self_service>
  <package_configuration>
    <packages>
      <size>1</size>
      <package>
        <name>%pkg_name%</name>
      </package>
    </packages>
  </package_configuration>
  <scripts>
    <size>0</size>
  </scripts>
  <maintenance>
    <recon>true</recon>
  </maintenance>
</policy>

Where to store templates

JamfUploader processors will look in the following locations for your templates (in this order):

1. The RecipeOverrides directory/ies
2. The same directory as the recipe
3. Anywhere in the same repo as the recipe (the repo must be in the RECIPE_SEARCH_DIRS).
4. Anywhere in the parent recipe's repo, if recipe is an override (the repo must be in the RECIPE_SEARCH_DIRS).