Overview

This guide walks you through managing scheduled tasks, jobs, and their statuses in the N-central platform. The Task & Job Management API allows you to create, retrieve, and monitor tasks and jobs across your managed devices. In this guide, you'll learn how to:

1. List and manage scheduled tasks
2. Create direct support tasks
3. Monitor task status
4. Track job statuses
5. Handle task execution results

Create Direct Support Task

To execute an immediate task on a specific device, use the Create Direct Support Task endpoint. This method is particularly useful for running scripts or automation policies that need immediate execution.

Required Parameters:

• name: Unique identifier for your task
• itemId: The ID of the remote execution item
• taskType: Must be one of: "AutomationPolicy", "Script", or "MacScript"
• customerId: The customer ID where the task will run
• deviceId: The target device for task execution

Optional Parameters:

• credential: Authentication settings for task execution
• parameters: Additional task-specific configuration

Request

POST https://your-ncentral-instance/api/scheduled-tasks/direct
Authorization: Bearer <YOUR_ACCESS_TOKEN>
Content-Type: application/json

{
  "name": "Security Update Task",
  "itemId": 1001,
  "taskType": "Script",
  "customerId": 100,
  "deviceId": 987654321,
  "credential": {
    "type": "LocalSystem"
  },
  "parameters": [
    {
      "name": "CommandLine",
      "value": "security_update.ps1",
      "type": "string"
    }
  ]
}

Response

Upon success, N-central returns a 201 status code with the task details:

{
  "data": {
    "taskId": 1985975
  },
  "_links": {
    "task": "/api/scheduled-tasks/1985975"
  }
}

Key points in the response:

• taskId: Use this identifier for status checking
• _links: Contains related endpoints for task management

Retrieve Task Information

To get details about a specific task, use the Get Task Information endpoint with the task's unique identifier.

Request

GET https://your-ncentral-instance/api/scheduled-tasks/{taskId}
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Response

{
  "data": {
    "taskId": 905592865,
    "name": "Security Update Task",
    "type": "Script",
    "isEnabled": true,
    "deviceIds": ["987654321"],
    "orgUnitId": 100,
    "isReactive": false
  }
}

Key response fields:

• taskId: Unique task identifier
• type: Task execution type
• isEnabled: Current activation status
• deviceIds: List of affected devices

Monitor Task Status

Track the execution progress of a task using the Get Task Status endpoint.

Request

GET https://your-ncentral-instance/api/scheduled-tasks/{taskId}/status
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Response

{
  "data": {
    "taskName": "Security Update Task",
    "statusCounts": {
      "Completed": 3,
      "In Progress": 2
    }
  }
}

Key status information:

• statusCounts: Aggregated execution statistics
• Status types include: Completed, In Progress, Failed, Pending

List Organization Job Statuses

Monitor job execution states at the organization unit level using the Get Job Statuses endpoint.

Required Parameters:

• orgUnitId: The organization unit identifier
• pageNumber: Page number for results (starts at 1)
• pageSize: Number of items per page

Request

GET https://your-ncentral-instance/api/org-units/{orgUnitId}/job-statuses
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Response

{
  "data": [
    {
      "jobId": "12345",
      "status": "Completed",
      "startTime": "2024-02-28T15:25:05.939-0500",
      "completionTime": "2024-02-28T15:40:42.407-0500"
    }
  ],
  "totalItems": 50
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

• 200: Successful operation
• 201: Resource created successfully
• 400: Invalid request format
• 401: Authentication failure
• 403: Insufficient permissions
• 404: Resource not found
• 429: Too many requests
• 500: Internal server error

Example error response:

{
  "status": 400,
  "message": "Invalid taskType specified. Must be one of: AutomationPolicy, Script, MacScript"
}

Task Types

The DirectSupportTask endpoint supports three specific task types:

Task Type Options

• AutomationPolicy
• Script
• MacScript

When creating a direct support task, specify the task type using the taskType parameter in your request. The task type determines how the task will be executed and what parameters are required.

For example:

{
  "name": "Update Script",
  "itemId": 1001,
  "taskType": "Script",  // Must be one of the three supported types
  "customerId": 100,
  "deviceId": 987654321
}

📘

Important Note

Each task type requires an itemId that references an existing remote execution item in your N-central system. This item must have the "Enable API" flag set to "ON" in the N-central UI under "Configuration" → "Scheduled Tasks" → "Script/software Repository".