Jamf Pro External Patch Source Endpoints

Updated: 26 July 2022
Product: Jamf Pro

You can integrate external patch sources with Jamf Pro. Software titles hosted on an external source can be used for patch reporting, patch notifications, and patch policies. This article describes the endpoints required to host an external patch source in your environment.

Requirements

You can expand Jamf Pro patch management functionality by connecting to a source hosted by the community, or by using a server application in your environment that responds to the following endpoints and can receive communication from Jamf Pro. Your implementation may be as simple as a small Python server.

To connect Jamf Pro to an external patch source, navigate to Settings > Computer Management > Patch Management.

The following endpoints are required to integrate an external patch source with Jamf Pro:

  • /software—This endpoint returns an array of Software Title Summary objects.

  • /software/{ids}—This endpoint returns a subset array of Software Title Summary objects that match any of the given {ids}.

  • /patch/{id}—This endpoint returns a Software Title object.

Objects

Software Title Summary Object

The information in the Software Title Summary object must match the information in the Software Title object that shares id. None of the following values can be null. In addition, the id cannot include any special characters or spaces.

Key

Value Type

Value Description

name

String

Name of the patch management software title.

publisher

String

Publisher of the patch management software title.

lastModified

String

Jamf Pro uses this key to display the Last Updated value in the computer inventory information.

Note:

Must be ISO-8601 format.

currentVersion

String

Used for reporting the latest version of the patch management software title to Jamf Pro.

id

String

Uniquely identifies this software title on the external source.

Note:

An id cannot be duplicated on an individual external source.

Software Title Object

The information in the Software Title object must match the information in the Software Title Summary object that shares id. None of the following values can be null. In addition, the id cannot include any special characters or spaces.

Key

Value Type

Value Description

name

String

Name of the patch management software title.

publisher

String

Publisher of the patch management software title.

appName

String

Deprecated

bundleId

String

Deprecated

lastModified

String

Jamf Pro uses this key to display the Last Updated value in the computer inventory information.

Note:

Must be ISO-8601 format.

currentVersion

String

Used for reporting the latest version of the patch management software title to Jamf Pro.

requirements

Array of criteria objects

Criteria used to determine which computers in your environment have this software title installed.

patches

Array of patch objects

Software title version information; one patch is one software title version.

Note:

Must be listed in descending order with the newest version at the top of the list.

extensionAttributes

Array of extensionAttributes objects

Extension attributes that are required by Jamf Pro to use this software title. Terms must be accepted in Jamf Pro.

id

String

String that uniquely identifies this software title on the external source.

Note:

An id cannot be duplicated on an individual external source.

criteria Object

The following values correspond with a row in a smart computer group or advanced search.
Note:

Criteria objects in an array must be ordered in the same way that smart group criteria is ordered.

Key

Value Type

Value Description

name

String

Any valid Jamf Pro smart group criteria.

When type is extensionAttribute, the name value is the key defined in the extensionAttribute object.

operator

String

Any valid Jamf Pro smart group operator for the given name.

value

String

Search value for the smart group criteria.

type

String

Valid values are recon for everything other than extension attribute, and extensionAttribute for extension attributes.

and

Boolean

true specifies an and operator.

false specifies an or operator.

Optional. Defaults to true if not specified.

patch Object

Key

Value Type

Value Description

version

String

Version associated with this patch.

releaseDate

String

Date that this patch version was released.

standalone

Boolean

true specifies a patch that can be installed by itself.

false specifies a patch that must be installed incrementally.

Note:

Used for reporting purposes. It is not used by patch policy processes.

minimumOperatingSystem

String

Lowest macOS version capable of installing this patch.

Note:

Used for reporting purposes. It is not used by patch policy processes. See the capabilities array for patch policy implementation.

reboot

Boolean

true specifies that the computer must be restarted after the patch policy has completed successfully.

false specifies that the computer will not be restarted

killApps

Array of killApp objects

Specifies processes that will be stopped before a patch policy runs.

components

Array of component objects

Defines the elements that comprise this patch version.

Note:

Only one element is supported by Jamf Pro at this time.

capabilities

Array of criteria objects

Criteria used to determine which computers in your environment have the ability to install and run this patch.

dependencies

Array of criteria objects

Not currently used by Jamf Pro.

Note:

Cannot be a null value.

extensionAttributes Object

Key

Value Type

Value Description

key

String

Identifier unique within Jamf Pro. It is used by criteria objects and displayed in the Jamf Pro computer inventory information.

Note:

Duplicate keys are not allowed.

value

String

Base64 encoded macOS script. Standard extension attribute script which must return a result.

displayName

String

Used on the Jamf Pro Patch Management > Extension Attributes tab.

killApps Object

Key

Value Type

Value Description

bundleId

String

Bundle identifier of the applications that will be stopped before a patch policy runs.

appName

String

Name of the application that will be stopped before a patch policy runs.

components Object

Key

Value Type

Value Description

name

String

Name of the patch management software title.

version

String

Version associated with this patch.

criteria

Array of criteria objects

Criteria used to determine which computers in your environment have this patch version installed.

Examples

/software

[
 {
    "name": "Java SE Runtime Environment JRE 8",
    "publisher": "Oracle",
    "lastModified": "2017-10-17T20:41:23Z",
    "currentVersion": "1.8.152",
    "id": "JavaSERuntimeEnvironmentJRE8"
  },
  {
    "name": "Google Chrome",
    "publisher": "Google",
    "lastModified": "2017-12-06T20:31:57Z",
    "currentVersion": "63.0.3239.84",
    "id": "GoogleChrome"
  },
  {
    "name": "Jamf Admin",
    "publisher": "Jamf",
    "lastModified": "2017-11-15T18:41:49Z",
    "currentVersion": "10.0.0",
    "id": "JamfAdmin"
  }
]

/software/{ids}

/software/JamfRemote,JavaSERuntimeEnvironmentJRE8

[
  {
    "name": "Java SE Runtime Environment JRE 8",
    "publisher": "Oracle",
    "lastModified": "2017-10-17T20:41:23Z",
    "currentVersion": "1.8.152",
    "id": "JavaSERuntimeEnvironmentJRE8"
  }
]

/patch/{id}

/patch/JamfAdmin

{
    "name": "Jamf Admin",
    "publisher": "Jamf",
    "appName": "Jamf Admin.app",
    "bundleId": "com.jamfsoftware.JamfAdmin",
    "lastModified": "2017-11-15T18:41:49Z",
    "currentVersion": "10.0.0",
    "requirements": [
        {
            "name": "Application Bundle ID",
            "operator": "is",
            "value": "com.jamfsoftware.JamfAdmin",
            "type": "recon",
            "and": false
        },
        {
            "name": "Application Bundle ID",
            "operator": "is",
            "value": "com.jamfsoftware.CasperAdmin",
            "type": "recon",
            "and": false
        }
    ],
    "patches": [
        {
            "version": "10.0.0",
            "releaseDate": "2017-10-31T12:00:00.270Z",
            "standalone": true,
            "minimumOperatingSystem": "10.9",
            "reboot": false,
            "killApps": [
                {
                    "bundleId": "com.jamfsoftware.CasperAdmin",
                    "appName": "Casper Admin.app"
                },
                {
                    "bundleId": "com.jamfsoftware.JamfAdmin",
                    "appName": "Jamf Admin.app"
                }
            ],
            "components": [
                {
                    "name": "Jamf Admin",
                    "version": "10.0.0",
                    "criteria": [
                        {
                            "name": "Application Bundle ID",
                            "operator": "is",
                            "value": "com.jamfsoftware.JamfAdmin",
                            "type": "recon",
                            "and": true
                        },
                        {
                            "name": "Application Version",
                            "operator": "is",
                            "value": "10.0.0",
                            "type": "recon"
                        }
                    ]
                }
            ],
            "capabilities": [
                {
                    "name": "Operating System Version",
                    "operator": "greater than or equal",
                    "value": "10.9",
                    "type": "recon"
                }
            ],
            "dependencies": []
        },
        {
            "version": "9.101.0",
            "releaseDate": "2017-9-12T14:19:38.270Z",
            "standalone": true,
            "minimumOperatingSystem": "10.9",
            "reboot": false,
            "killApps": [
                {
                    "bundleId": "com.jamfsoftware.CasperAdmin",
                    "appName": "Casper Admin.app"
                }
            ],
            "components": [
                {
                    "name": "Jamf Admin",
                    "version": "9.101.0",
                    "criteria": [
                        {
                            "name": "Application Bundle ID",
                            "operator": "is",
                            "value": "com.jamfsoftware.CasperAdmin",
                            "type": "recon",
                            "and": true
                        },
                        {
                            "name": "Application Version",
                            "operator": "is",
                            "value": "9.101.0",
                            "type": "recon"
                        }
                    ]
                }
            ],
            "capabilities": [
                {
                    "name": "Operating System Version",
                    "operator": "greater than or equal",
                    "value": "10.9",
                    "type": "recon"
                }
            ],
            "dependencies": []
        },
        {
            "version": "9.100.0",
            "releaseDate": "2017-7-20T16:54:29.814Z",
            "standalone": true,
            "minimumOperatingSystem": "10.9",
            "reboot": false,
            "killApps": [
                {
                    "bundleId": "com.jamfsoftware.CasperAdmin",
                    "appName": "Casper Admin.app"
                }
            ],
            "components": [
                {
                    "name": "Jamf Admin",
                    "version": "9.100.0",
                    "criteria": [
                        {
                            "name": "Application Bundle ID",
                            "operator": "is",
                            "value": "com.jamfsoftware.CasperAdmin",
                            "type": "recon",
                            "and": true
                        },
                        {
                            "name": "Application Version",
                            "operator": "is",
                            "value": "9.100.0",
                            "type": "recon"
                        }
                    ]
                }
            ],
            "capabilities": [
                {
                    "name": "Operating System Version",
                    "operator": "greater than or equal",
                    "value": "10.9",
                    "type": "recon"
                }
            ],
            "dependencies": []
        },
        {
            "version": "9.99.0",
            "releaseDate": "2017-05-23T18:09:29.814Z",
            "standalone": true,
            "minimumOperatingSystem": "10.9",
            "reboot": false,
            "killApps": [
                {
                    "bundleId": "com.jamfsoftware.CasperAdmin",
                    "appName": "Casper Admin.app"
                }
            ],
            "components": [
                {
                    "name": "Jamf Admin",
                    "version": "9.99.0",
                    "criteria": [
                        {
                            "name": "Application Bundle ID",
                            "operator": "is",
                            "value": "com.jamfsoftware.CasperAdmin",
                            "type": "recon",
                            "and": true
                        },
                        {
                            "name": "Application Version",
                            "operator": "is",
                            "value": "9.99.0",
                            "type": "recon"
                        }
                    ]
                }
            ],
            "capabilities": [
                {
                    "name": "Operating System Version",
                    "operator": "greater than or equal",
                    "value": "10.9",
                    "type": "recon"
                }
            ],
            "dependencies": []
        }
    ],
    "extensionAttributes": [],
    "id": "JamfAdmin"
}

/patch/JavaSEDevelopmentKit8

Note:

This example includes an extension attribute.

{
    "name": "Java SE Development Kit 8",
    "publisher": "Oracle",
    "appName": "",
    "bundleId": "",
    "lastModified": "2017-10-19T12:38:58Z",
    "currentVersion": "1.8.152",
    "patches": [
        {
            "version": "1.8.152",
            "releaseDate": "2017-10-16T15:18:18.498Z",
            "standalone": true,
            "minimumOperatingSystem": "10.8.3",
            "reboot": false,
            "killApps": [],
            "components": [
                {
                    "name": "Java SE Development Kit 8",
                    "version": "1.8.152",
                    "criteria": [
                        {
                            "name": "java-8-jdk",
                            "operator": "is",
                            "value": "1.8.152",
                            "type": "extensionAttribute",
                            "and": true
                        }
                    ]
                }
            ],
            "capabilities": [
                {
                    "name": "Operating System Version",
                    "operator": "greater than or equal",
                    "value": "10.8.3",
                    "type": "recon",
                    "and": true
                }
            ],
            "dependencies": []
        },
        {
            "version": "1.8.151",
            "releaseDate": "2017-10-15T10:18:18.498Z",
            "standalone": true,
            "minimumOperatingSystem": "10.8.3",
            "reboot": false,
            "killApps": [],
            "components": [
                {
                    "name": "Java SE Development Kit 8",
                    "version": "1.8.151",
                    "criteria": [
                        {
                            "name": "java-8-jdk",
                            "operator": "is",
                            "value": "1.8.151",
                            "type": "extensionAttribute",
                            "and": true
                        }
                    ]
                }
            ],
            "capabilities": [
                {
                    "name": "Operating System Version",
                    "operator": "greater than or equal",
                    "value": "10.8.3",
                    "type": "recon",
                    "and": true
                }
            ],
            "dependencies": []
        }
    ],
    "extensionAttributes": [
        {
            "key": "java-8-jdk",
            "value": "IyEvdXNyL2Jpbi9lbnYgYmFzaA0KIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjDQojIENvbGxlY3RzIGluZm9ybWF0aW9uIHRvIGRldGVybWluZSB3aGljaCB2ZXJzaW9uIG9mIHRoZSBKYXZhIEpESyBpcyBpbnN0YWxsZWQgYnkgICAgICAgICMNCiMgbG9vcGluZyB0aHJvdWdoIGFsbCB0aGUgaW5zdGFsbGVkIEpES3MgZm9yIHRoZSBtYWpvciB2ZXJzaW9uIHNlbGVjdGVkLiBBbmQgdGhlbiAgICAgICAgIw0KIyBjb21wYXJpbmcgdGhlIGJ1aWxkIG51bWJlciB0byBkZXRlcm1pbmUgdGhlIGhpZ2hlc3QgdmFsdWUuIEJ1aWxkcyB0aGUgcmVzdWx0IGFzICAgICAgICAjDQojIDEuWC5ZLCBpZ25vcmluZyB0aGUgYnVpbGQgbnVtYmVyLCB3aGVyZSBYIGlzIG1ham9yIHZlcnNpb24gYW5kIFkgaXMgdGhlIG1pbm9yIHZlcnNpb24uICMJCQkJCQkJCSAgIwkNCiMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyANClNFQVJDSF9GT1JfVkVSU0lPTj0iOCINCkhJR0hFU1RfQlVJTEQ9Ii0xIg0KUkVTVUxUPSJOb3QgSW5zdGFsbGVkIg0KDQppbnN0YWxsZWRfamRrcz0kKC9iaW4vbHMgL0xpYnJhcnkvSmF2YS9KYXZhVmlydHVhbE1hY2hpbmVzLykNCg0KDQpmb3IgaSBpbiAke2luc3RhbGxlZF9qZGtzfTsgZG8NCgl2ZXJzaW9uPSQoIC91c3IvYmluL2RlZmF1bHRzIHJlYWQgIi9MaWJyYXJ5L0phdmEvSmF2YVZpcnR1YWxNYWNoaW5lcy8ke2l9L0NvbnRlbnRzL0luZm8ucGxpc3QiIENGQnVuZGxlVmVyc2lvbiApDQoNCgltYWpvcl92ZXJzaW9uPWBlY2hvICIkdmVyc2lvbiIgfCBhd2sgLUYnLicgJ3twcmludCAkMn0nYA0KDQoJaWYgWyAiJG1ham9yX3ZlcnNpb24iIC1lcSAiJFNFQVJDSF9GT1JfVkVSU0lPTiIgXSA7IHRoZW4NCgkJIyBTcGxpdCBvbiAxLlguMF9YWCB0byBnZXQgYnVpbGQgbnVtYmVyDQoJCWJ1aWxkX251bWJlcj1gZWNobyAiJHZlcnNpb24iIHwgYXdrIC1GJzBfJyAne3ByaW50ICQyfSdgDQoJCWlmIFsgIiRidWlsZF9udW1iZXIiIC1ndCAiJEhJR0hFU1RfQlVJTEQiIF0gOyB0aGVuDQoJCQlISUdIRVNUX0JVSUxEPSIkYnVpbGRfbnVtYmVyIg0KCQkJUkVTVUxUPSIxLiRtYWpvcl92ZXJzaW9uLiRidWlsZF9udW1iZXIiDQoJCWZpCQ0KCWZpCQkNCmRvbmUNCg0KZWNobyAiPHJlc3VsdD4kUkVTVUxUPC9yZXN1bHQ+Ig==",
            "displayName": "Java 8 SE Development Kit"
        }
    ],
    "requirements": [
        {
            "name": "java-8-jdk",
            "operator": "is not",
            "value": "Not Installed",
            "type": "extensionAttribute",
            "and": true
        },
        {
            "name": "java-8-jdk",
            "operator": "is not",
            "value": "",
            "type": "extensionAttribute",
            "and": true
        }
    ],
    "id": "JavaSEDevelopmentKit8"
}

Further Considerations

The Jamf Pro server performs very little verification on the accuracy of external patch source data. Because Jamf Pro depends on accurate information from the software title definitions, it is critical to verify the external patch sources hosted in your environment to ensure expected behavior.

Additional Information

For more information about patch notifications, patch reporting, and patch policies, see Patch Management in the Jamf Pro Documentation.