get_playbook_status
Check Ansible playbook execution status to monitor completion and track multiple playbooks using the Ara Records API.
Instructions
Get a quick summary of playbook execution status without detailed task information. Useful for checking if a playbook is complete or monitoring multiple playbooks.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| playbook_id | Yes | The ID of the playbook to check |
Implementation Reference
- ara-server.js:472-507 (handler)Specific handler logic for the 'get_playbook_status' tool. Fetches playbook details without tasks or results and returns a concise status summary including progress, timing, and path.if (name === 'get_playbook_status') { const { playbook_id } = args; try { const details = await fetchPlaybookDetails(playbook_id, false, false); // Return just the summary without task details const status = { id: details.id, status: details.status, progress: details.progress, started: details.started, ended: details.ended, duration: details.duration, path: details.path, }; return { content: [ { type: 'text', text: JSON.stringify(status, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text', text: `Error checking playbook ${playbook_id} status: ${error.message}`, }, ], }; } }
- ara-server.js:257-266 (schema)Input schema for the 'get_playbook_status' tool, defining the required 'playbook_id' parameter.inputSchema: { type: 'object', properties: { playbook_id: { type: 'number', description: 'The ID of the playbook to check', }, }, required: ['playbook_id'], },
- ara-server.js:254-267 (registration)Registration of the 'get_playbook_status' tool in the list returned by ListToolsRequestHandler, including name, description, and input schema.{ name: 'get_playbook_status', description: 'Get a quick summary of playbook execution status without detailed task information. Useful for checking if a playbook is complete or monitoring multiple playbooks.', inputSchema: { type: 'object', properties: { playbook_id: { type: 'number', description: 'The ID of the playbook to check', }, }, required: ['playbook_id'], }, },
- ara-server.js:298-390 (helper)Helper function fetchPlaybookDetails used by 'get_playbook_status' (and 'watch_playbook') to retrieve and summarize playbook data from the ARA API, with optional task and result details.async function fetchPlaybookDetails(playbookId, includeTasks = true, includeResults = false) { try { // Fetch playbook data const playbookResponse = await fetch(`${ARA_API_SERVER}${API_PATH}/playbooks/${playbookId}`, { headers: createAuthHeaders(), }); if (!playbookResponse.ok) { throw new Error(`HTTP ${playbookResponse.status}: ${playbookResponse.statusText}`); } const playbook = await playbookResponse.json(); // Calculate progress const totalTasks = playbook.items.tasks || 0; const totalResults = playbook.items.results || 0; const progressPercent = totalTasks > 0 ? Math.round((totalResults / totalTasks) * 100) : 0; const summary = { id: playbook.id, status: playbook.status, path: playbook.path, started: playbook.started, ended: playbook.ended, duration: playbook.duration, ansible_version: playbook.ansible_version, controller: playbook.controller, user: playbook.user, progress: { percent: progressPercent, tasks_total: totalTasks, tasks_completed: totalResults, plays: playbook.items.plays, hosts: playbook.items.hosts, }, labels: playbook.labels, }; // Optionally fetch task details if (includeTasks) { const tasksResponse = await fetch( `${ARA_API_SERVER}${API_PATH}/tasks?playbook=${playbookId}&limit=100&order=started`, { headers: createAuthHeaders(), } ); if (tasksResponse.ok) { const tasksData = await tasksResponse.json(); summary.tasks = tasksData.results.map(task => ({ id: task.id, name: task.name, status: task.status, action: task.action, started: task.started, ended: task.ended, duration: task.duration, tags: task.tags, })); summary.tasks_count = tasksData.count; } } // Optionally fetch result details if (includeResults) { const resultsResponse = await fetch( `${ARA_API_SERVER}${API_PATH}/results?playbook=${playbookId}&limit=100&order=started`, { headers: createAuthHeaders(), } ); if (resultsResponse.ok) { const resultsData = await resultsResponse.json(); summary.results = resultsData.results.map(result => ({ id: result.id, task: result.task, host: result.host, status: result.status, changed: result.changed, started: result.started, ended: result.ended, duration: result.duration, })); summary.results_count = resultsData.count; } } return summary; } catch (error) { throw new Error(`Failed to fetch playbook details: ${error.message}`); } }