Tasks Service - API Documentation

🏠 Home › tasks / docs

Tasks Service - API Documentation

Overview

Authentication & Authorization

All endpoints (except Diagnostic/Ping) require: 1. A valid JWT Bearer token in the Authorization header 2. Persona claim matching the endpoint's requirement via [CustomAuthorization]

Persona Description
DirectSupplyPartner Internal/partner administrative access
Customer Customer-level access

JWT claims provide: PersonId, DisplayName, Persona, BearerToken

Global Response Codes

Code Meaning
200 Success
201 Created (returns ID or location)
204 No Content (successful update/delete)
400 Bad Request (validation error, returns GenericActionResponse)
401 Unauthorized (missing/invalid token or persona)
403 Forbidden
404 Not Found

Diagnostic

Method Path Auth Description
GET /Diagnostic/Ping None Health check

Tasks

Method Path Auth Description
GET /Tasks Partner, Customer List tasks. Query: chainId, marketSegments, pageSize, pageKey
GET /Tasks/{taskId} Partner, Customer Get a single task
POST /Tasks Partner, Customer Create a task
PATCH /Tasks/{taskId} Partner, Customer Update a task
DELETE /Tasks/{taskId} Partner, Customer Delete a task
GET /Tasks/{taskId}/defaults Partner Get best practice task defaults
PATCH /Tasks/{taskId}/defaults Partner Patch task defaults (LogTemplateId)
POST /Tasks/{taskId}/commands/removeDefaultLogTemplate Partner Remove default log template
POST /Tasks/businessUnits/{businessUnitId}/commands/assignDefaultDocumentUpload Partner Assign default document upload for BU
POST /Tasks/businessUnits/{businessUnitId}/commands/assignDefaultLogTemplates Partner Assign default log templates for BU

CreateTaskRequest:

{
  "chainId": 123,
  "categoryName": "string",
  "title": "string",
  "instructions": "string",
  "type": "TaskType",
  "defaultRecurrence": { "unit": "Month", "every": 3, "offset": 0 },
  "citationCodes": ["string"],
  "programId": 1,
  "referenceMaterials": [{ "..." }],
  "marketSegmentId": 1
}

PatchTaskRequest:

{
  "title": "string",
  "instructions": "string",
  "type": "TaskType",
  "defaultRecurrence": { "unit": "Month", "every": 3 },
  "citationCodes": ["string"],
  "programId": 1,
  "referenceMaterials": [{ "..." }]
}

Instances

Method Path Auth Description
GET /Instances Partner, Customer Search instances (filtered by facility, status, time period, etc.)
GET /Instances/{instanceId} Partner, Customer Get a single instance
GET /Instances/summary Partner, Customer Get instance summary statistics
POST /Instances/{instanceId}/commands/complete Partner, Customer Complete an instance
POST /Instances/{instanceId}/commands/skip Partner, Customer Skip an instance
POST /Instances/{instanceId}/commands/reopen Partner, Customer Reopen a completed/skipped instance
PATCH /Instances/{instanceId}/assignment Partner, Customer Assign instance to a person
PATCH /Instances/{instanceId}/userNote Partner, Customer Set user note on instance

CompleteTaskRequest: { "isOnTime": true, "userNote": "string" }

SkipTaskRequest: { "userNote": "string" }

TaskInstanceAssignmentRequest: { "personId": 123 }

Instance Logs

Method Path Auth Description
GET /Instances/{instanceId}/logs Partner, Customer Get logs for an instance
POST /Instances/{instanceId}/logs Partner, Customer Associate log template to instance
PATCH /Instances/{instanceId}/logs/{logId}/answers/{answerId} Partner, Customer Patch a log answer

AssociateLogRequest: { "layoutIds": [1, 2, 3] }

Instance Files

Method Path Auth Description
POST /Instances/{instanceId}/files Partner, Customer Attach a file to an instance

AttachFileRequest: { "fileGuid": "guid-string" }

Instance Time Logs

Method Path Auth Description
GET /Instances/{instanceId}/timeLogs Partner, Customer Get time logs for an instance
POST /Instances/{instanceId}/timeLogs Partner, Customer Create a time log entry
DELETE /Instances/{instanceId}/timeLogs/{timeLogId} Partner, Customer Delete a time log entry

TaskInstanceTimeLogRequest: { "personId": 123, "personName": "string", "durationInMinutes": 30 }

Instance Material Costs

Method Path Auth Description
GET /Instances/{instanceId}/materialCosts Partner, Customer Get material costs for an instance
POST /Instances/{instanceId}/materialCosts Partner, Customer Create a material cost entry
DELETE /Instances/{instanceId}/materialCosts/{materialCostId} Partner, Customer Delete a material cost entry

TaskInstanceMaterialCostRequest: { "cost": 49.99, "assetId": 123, "title": "string" }

Schedules

Method Path Auth Description
GET /Schedules Partner, Customer Search schedules with filters
GET /Schedules/{scheduleId} Partner, Customer Get a single schedule
POST /Schedules Partner, Customer Create a schedule
PATCH /Schedules/{scheduleId} Partner, Customer Update a schedule
DELETE /Schedules/{scheduleId} Partner, Customer Delete a schedule
PATCH /Schedules/{scheduleId}/assignment Partner, Customer Assign schedule to a person

CreateScheduleRequest:

{
  "taskId": 123,
  "facilityId": 456,
  "personId": 789,
  "recurrence": { "unit": "Month", "every": 1, "offset": 0 },
  "startDate": "2024-01-01",
  "buildings": [1, 2],
  "activeRange": { "start": "date", "end": "date" },
  "programId": 1
}

Schedules By Facility

Method Path Auth Description
POST /SchedulesByFacility Partner, Customer Get schedules filtered by facility (complex query)

Categories

Method Path Auth Description
GET /Categories Partner, Customer Get task categories by facility. Query: facilityId

Departments

Method Path Auth Description
GET /Departments Partner, Customer Get departments by facility. Query: facilityId

Configuration

Method Path Auth Description
GET /Configuration/businessUnits/{businessUnitId} Partner Get BU configuration
PATCH /Configuration/businessUnits/{businessUnitId} Partner Update BU configuration

Business Unit Task Overrides

Method Path Auth Description
GET /BusinessUnitTaskOverrides/businessUnits/{businessUnitId} Partner Get all overrides for a BU
POST /BusinessUnitTaskOverrides/businessUnits/{businessUnitId}/tasks/{taskId} Partner Create an override
PATCH /BusinessUnitTaskOverrides/businessUnits/{businessUnitId}/tasks/{taskId} Partner Update an override
DELETE /BusinessUnitTaskOverrides/businessUnits/{businessUnitId}/tasks/{taskId} Partner Delete an override

Allowed file upload extensions: .pdf, .doc, .docx, .xls, .xlsx, .csv, .png, .jpg, .jpeg

Log Templates

Method Path Auth Description
GET /LogTemplates Partner, Customer Search log templates

Program Preferences

Method Path Auth Description
POST /ProgramPreferences/programs/{programId} Partner, Customer Set program preference for a person
DELETE /ProgramPreferences/programs/{programId} Partner, Customer Remove program preference

ProgramPreferenceRequest: { "personId": 123 }

Task Configuration Templates

Method Path Auth Description
GET /TaskConfigurationTemplates Partner List templates
GET /TaskConfigurationTemplates/{templateId} Partner Get a single template
POST /TaskConfigurationTemplates Partner Create a template
PATCH /TaskConfigurationTemplates/{templateId} Partner Update a template
DELETE /TaskConfigurationTemplates/{templateId} Partner Delete a template

Task Instance Generation (Commands)

Method Path Auth Description
POST /commands/generateTaskInstances Partner Generate instances for facilities
POST /commands/scheduleRecurringTaskInstanceGeneration Partner Schedule recurring generation (MassTransit request/response)
POST /commands/unscheduleRecurringTaskInstanceGeneration Partner Unschedule recurring generation (MassTransit request/response)

GenerateTaskInstancesRequest: { "facilityIds": [1, 2, 3] }

Schedule Migrations

Method Path Auth Description
POST /ScheduleMigrations Partner Migrate schedules for chains

ScheduleMigrationsRequest: { "chainIds": [1, 2, 3] }

Calculate Next Due Dates

Method Path Auth Description
POST /CalculateNextDueDates Partner, Customer Calculate next due dates for schedules

Key Enumerations

Enum Values
TaskInstanceStatus Open, Completed, Skipped
TaskType (domain-specific task types)
RecurrenceUnit Day, Week, Month, Year
TimePeriod (filtering time periods)

Pagination

List endpoints support cursor-based pagination: - pageSize (int) - Number of results per page - pageKey (string) - Cursor token for next page

Notes