Jamf New Mac Enrollment Check
Draft
Jamf New Mac Enrollment Check
Draft
Press a step to see its codeList recently enrolled Macs, lines 137 to 169Look up each assigned user, lines 171 to 177Summarize the new Macs, lines 179 to 189Open a ticket for Macs that need attention, lines 191 to 201

List recently enrolled Macs

Jamf Pro returns the newest enrollments first, so paging stops early.

for (let page = 0; page < MAX_PAGES && !done; page++)

response.status_code !== 200

Fail

`Jamf Pro returned ${response.status_code} for the computer ` + "inventory. Check that the Jamf connection's …

macs.length === 0

Return

return

Look up each assigned user

Each assigned email should belong to an active person in the directory.

for (const email of assignedEmails(macs))

Summarize the new Macs

flagged.length === 0 || !params.open_ticket_for_problems

Return

return

Open a ticket for Macs that need attention

Return

return

body
true
false
done
true
false
done
true
false
1// List the Macs that enrolled in Jamf Pro in the last few hours, with serial
2// number, model and assigned user, flag the ones that need attention, and
3// open one ticket for them. Returns a summary an automation can post to an
4// alerts channel as is.
5//
6// Before publishing: replace acme.jamfcloud.com, here and in the `domains`
7// export, with your Jamf Pro server as saved on Settings > Integrations >
8// Jamf. The Jamf connection's API client needs the Read Computers privilege.
9
10type NewMac = {
11 name: string;
12 serial: string;
13 model: string;
14 email: string | null;
15 fileVaultOn: boolean;
16 managed: boolean;
17};
18
19// The directory entry for an assigned email, or null when there is none.
20type Person = { active: boolean } | null;
21
22export const input = z.object({
23 hours: z
24 .number()
25 .int()
26 .min(1)
27 .max(168)
28 .default(24)
29 .describe("How many hours back to look for new enrollments, 1 to 168"),
30 open_ticket_for_problems: z
31 .boolean()
32 .default(true)
33 .describe("Open one ticket listing the new Macs that need attention"),
34});
35
36// GET only. The org's Jamf connection authenticates every call.
37export const domains = { "acme.jamfcloud.com": "read" };
38
39// Four pages of 50 keep the run well inside its time limit.
40const PAGE_SIZE = 50;
41const MAX_PAGES = 4;
42
43const isObject = (value: unknown): value is Record<string, unknown> =>
44 typeof value === "object" && value !== null;
45
46const getNested = (value: unknown, path: string[]): unknown => {
47 let current: unknown = value;
48 for (const key of path) {
49 if (!isObject(current)) {
50 return undefined;
51 }
52 current = current[key];
53 }
54 return current;
55};
56
57const getString = (value: unknown, path: string[]): string | null => {
58 const found = getNested(value, path);
59 return typeof found === "string" && found.trim() !== "" ? found : null;
60};
61
62const toMac = (record: unknown): NewMac => ({
63 name: getString(record, ["general", "name"]) ?? "Unnamed Mac",
64 serial: getString(record, ["hardware", "serialNumber"]) ?? "no serial",
65 model: getString(record, ["hardware", "model"]) ?? "unknown model",
66 email: getString(record, ["userAndLocation", "email"]),
67 fileVaultOn:
68 getNested(record, ["diskEncryption", "fileVault2Enabled"]) === true,
69 managed:
70 getNested(record, ["general", "remoteManagement", "managed"]) === true,
71});
72
73// The new Macs on one page, newest first, and whether paging can stop: the
74// page came back short, or it reached a Mac enrolled before the window.
75const readPage = (body: unknown, since: number) => {
76 const records =
77 isObject(body) && Array.isArray(body.results) ? body.results : [];
78 const macs: NewMac[] = [];
79 let done = records.length < PAGE_SIZE;
80 for (const record of records) {
81 const enrolled = Date.parse(
82 getString(record, ["general", "lastEnrolledDate"]) ?? "",
83 );
84 if (enrolled >= since) {
85 macs.push(toMac(record));
86 } else if (!Number.isNaN(enrolled)) {
87 done = true;
88 }
89 }
90 return { macs, done };
91};
92
93const assignedEmails = (macs: NewMac[]): string[] => [
94 ...new Set(macs.flatMap((mac) => (mac.email === null ? [] : [mac.email]))),
95];
96
97// find_users matches on substrings, so keep only the exact email.
98const findPerson = (
99 matches: Array<{ email: string; active: boolean }>,
100 email: string,
101): Person =>
102 matches.find((user) => user.email.toLowerCase() === email.toLowerCase()) ??
103 null;
104
105const problemsFor = (mac: NewMac, people: Map<string, Person>): string[] => {
106 const problems: string[] = [];
107 const person = mac.email === null ? null : (people.get(mac.email) ?? null);
108 if (mac.email === null) {
109 problems.push("no assigned user");
110 } else if (person === null) {
111 problems.push("assigned user not in the directory");
112 } else if (!person.active) {
113 problems.push("assigned user is inactive");
114 }
115 if (!mac.fileVaultOn) {
116 problems.push("FileVault off");
117 }
118 if (!mac.managed) {
119 problems.push("not managed");
120 }
121 return problems;
122};
123
124const macLine = (mac: NewMac, people: Map<string, Person>): string => {
125 const problems = problemsFor(mac, people);
126 const user = mac.email ?? "no user";
127 const line = `• ${mac.name}: ${mac.serial}, ${mac.model}, ${user}`;
128 return problems.length === 0
129 ? line
130 : `${line}. Needs: ${problems.join(", ")}`;
131};
132
133const plural = (count: number, word: string): string =>
134 `${count} ${word}${count === 1 ? "" : "s"}`;
135
136export default async function run(params: z.infer<typeof input>) {
137 // **List recently enrolled Macs**
138 // Jamf Pro returns the newest enrollments first, so paging stops early.
139 const since = Date.now() - params.hours * 60 * 60 * 1000;
140 const macs: NewMac[] = [];
141 let done = false;
142 for (let page = 0; page < MAX_PAGES && !done; page++) {
143 // A literal URL, so Risotto checks it against your Jamf server on save.
144 // The sections are the only parts of each record this check reads.
145 const response = await http.get(
146 "https://acme.jamfcloud.com/api/v4/computers-inventory?section=GENERAL&section=HARDWARE&section=USER_AND_LOCATION&section=DISK_ENCRYPTION",
147 {
148 query: {
149 page: String(page),
150 "page-size": String(PAGE_SIZE),
151 sort: "general.lastEnrolledDate:desc",
152 },
153 auth: { type: "jamf" },
154 },
155 );
156 if (response.status_code !== 200) {
157 fail(
158 `Jamf Pro returned ${response.status_code} for the computer ` +
159 "inventory. Check that the Jamf connection's API client has the " +
160 "Read Computers privilege, then run the tool again.",
161 );
162 }
163 const batch = readPage(response.body, since);
164 macs.push(...batch.macs);
165 done = batch.done;
166 }
167 if (macs.length === 0) {
168 return `No Macs enrolled in Jamf Pro in the last ${params.hours} hours.`;
169 }
170
171 // **Look up each assigned user**
172 // Each assigned email should belong to an active person in the directory.
173 const people = new Map<string, Person>();
174 for (const email of assignedEmails(macs)) {
175 const matches = await risotto.find_users({ query: email });
176 people.set(email, findPerson(matches, email));
177 }
178
179 // **Summarize the new Macs**
180 const flagged = macs.filter((mac) => problemsFor(mac, people).length > 0);
181 const cutOff = done ? "" : ` Showing the newest ${macs.length} only.`;
182 const summary = [
183 `${plural(macs.length, "Mac")} enrolled in Jamf Pro in the last ` +
184 `${params.hours} hours; ${flagged.length} need attention.${cutOff}`,
185 ...macs.map((mac) => macLine(mac, people)),
186 ].join("\n");
187 if (flagged.length === 0 || !params.open_ticket_for_problems) {
188 return summary;
189 }
190
191 // **Open a ticket for Macs that need attention**
192 const ticket = await risotto.create_ticket({
193 title: `${plural(flagged.length, "new Mac")} in Jamf Pro need attention`,
194 description: [
195 `These Macs enrolled in Jamf Pro in the last ${params.hours} hours:`,
196 ...flagged.map((mac) => macLine(mac, people)),
197 "Assign each one to an active person in Jamf Pro, turn on FileVault, " +
198 "and check that Jamf Pro manages it.",
199 ].join("\n"),
200 });
201 return `${summary}\nOpened ticket ${ticket.ticket_id} for them.`;
202}
137 // **List recently enrolled Macs**
138 // Jamf Pro returns the newest enrollments first, so paging stops early.
139 const since = Date.now() - params.hours * 60 * 60 * 1000;
140 const macs: NewMac[] = [];
141 let done = false;
142 for (let page = 0; page < MAX_PAGES && !done; page++) {
143 // A literal URL, so Risotto checks it against your Jamf server on save.
144 // The sections are the only parts of each record this check reads.
145 const response = await http.get(
146 "https://acme.jamfcloud.com/api/v4/computers-inventory?section=GENERAL&section=HARDWARE&section=USER_AND_LOCATION&section=DISK_ENCRYPTION",
147 {
148 query: {
149 page: String(page),
150 "page-size": String(PAGE_SIZE),
151 sort: "general.lastEnrolledDate:desc",
152 },
153 auth: { type: "jamf" },
154 },
155 );
156 if (response.status_code !== 200) {
157 fail(
158 `Jamf Pro returned ${response.status_code} for the computer ` +
159 "inventory. Check that the Jamf connection's API client has the " +
160 "Read Computers privilege, then run the tool again.",
161 );
162 }
163 const batch = readPage(response.body, since);
164 macs.push(...batch.macs);
165 done = batch.done;
166 }
167 if (macs.length === 0) {
168 return `No Macs enrolled in Jamf Pro in the last ${params.hours} hours.`;
169 }
171 // **Look up each assigned user**
172 // Each assigned email should belong to an active person in the directory.
173 const people = new Map<string, Person>();
174 for (const email of assignedEmails(macs)) {
175 const matches = await risotto.find_users({ query: email });
176 people.set(email, findPerson(matches, email));
177 }
179 // **Summarize the new Macs**
180 const flagged = macs.filter((mac) => problemsFor(mac, people).length > 0);
181 const cutOff = done ? "" : ` Showing the newest ${macs.length} only.`;
182 const summary = [
183 `${plural(macs.length, "Mac")} enrolled in Jamf Pro in the last ` +
184 `${params.hours} hours; ${flagged.length} need attention.${cutOff}`,
185 ...macs.map((mac) => macLine(mac, people)),
186 ].join("\n");
187 if (flagged.length === 0 || !params.open_ticket_for_problems) {
188 return summary;
189 }
191 // **Open a ticket for Macs that need attention**
192 const ticket = await risotto.create_ticket({
193 title: `${plural(flagged.length, "new Mac")} in Jamf Pro need attention`,
194 description: [
195 `These Macs enrolled in Jamf Pro in the last ${params.hours} hours:`,
196 ...flagged.map((mac) => macLine(mac, people)),
197 "Assign each one to an active person in Jamf Pro, turn on FileVault, " +
198 "and check that Jamf Pro manages it.",
199 ].join("\n"),
200 });
201 return `${summary}\nOpened ticket ${ticket.ticket_id} for them.`;
Config you will fill in

None. It signs in through your Jamf Pro connection, so there is no key to store.