aps_issues_list

Instructions

Implementation Reference

• src/index.ts:454-529 (registration)

  Tool registration and input schema for 'aps_issues_list' – defines the tool's name, description, and inputSchema with all filter/sort/pagination parameters.

  // 12 ── aps_issues_list
  {
    name: "aps_issues_list",
    description:
      "List and search issues in a project with optional filtering. " +
      "Returns a compact summary per issue: id, displayId, title, status, assignee, dates, comment count. " +
      "Supports filtering by status, assignee, type, date, search text, and more. " +
      "This is much smaller than the raw API response.",
    inputSchema: {
      type: "object" as const,
      properties: {
        project_id: {
          type: "string",
          description: "Project ID – accepts with or without 'b.' prefix.",
        },
        filter_status: {
          type: "string",
          description:
            "Filter by status. Comma‑separated. " +
            "Values: draft, open, pending, in_progress, in_review, completed, not_approved, in_dispute, closed.",
        },
        filter_assigned_to: {
          type: "string",
          description: "Filter by assignee Autodesk ID. Comma‑separated for multiple.",
        },
        filter_issue_type_id: {
          type: "string",
          description: "Filter by category (type) UUID. Comma‑separated for multiple.",
        },
        filter_issue_subtype_id: {
          type: "string",
          description: "Filter by type (subtype) UUID. Comma‑separated for multiple.",
        },
        filter_due_date: {
          type: "string",
          description: "Filter by due date (YYYY‑MM‑DD). Comma‑separated for range.",
        },
        filter_created_at: {
          type: "string",
          description: "Filter by creation date (YYYY‑MM‑DD or YYYY‑MM‑DDThh:mm:ss.sz).",
        },
        filter_search: {
          type: "string",
          description: "Search by title or display ID (e.g. '300' or 'wall crack').",
        },
        filter_root_cause_id: {
          type: "string",
          description: "Filter by root cause UUID. Comma‑separated for multiple.",
        },
        filter_location_id: {
          type: "string",
          description: "Filter by LBS location UUID. Comma‑separated for multiple.",
        },
        limit: {
          type: "number",
          description: "Max issues to return (1‑100). Default 100.",
        },
        offset: {
          type: "number",
          description: "Pagination offset. Default 0.",
        },
        sort_by: {
          type: "string",
          description:
            "Sort field(s). Comma‑separated. Prefix with '-' for descending. " +
            "Values: createdAt, updatedAt, displayId, title, status, assignedTo, dueDate, startDate, closedAt.",
        },
        region: {
          type: "string",
          enum: ["US", "EMEA", "AUS", "CAN", "DEU", "IND", "JPN", "GBR"],
          description: "Data centre region. Defaults to US.",
        },
      },
      required: ["project_id"],
    },
  },

• src/index.ts:1240-1271 (handler)

  Tool handler for 'aps_issues_list' – validates project_id, builds query parameters from arguments, calls the Issues API GET endpoint, and returns summarised results.

  // ── aps_issues_list ─────────────────────────────────────────
  if (name === "aps_issues_list") {
    const projectId = args.project_id as string;
    const err = validateIssuesProjectId(projectId);
    if (err) return fail(err);
  
    const pid = toIssuesProjectId(projectId);
    const region = args.region as string | undefined;
    const t = await token();
  
    const query: Record<string, string> = {};
    if (args.filter_status) query["filter[status]"] = args.filter_status as string;
    if (args.filter_assigned_to) query["filter[assignedTo]"] = args.filter_assigned_to as string;
    if (args.filter_issue_type_id) query["filter[issueTypeId]"] = args.filter_issue_type_id as string;
    if (args.filter_issue_subtype_id) query["filter[issueSubtypeId]"] = args.filter_issue_subtype_id as string;
    if (args.filter_due_date) query["filter[dueDate]"] = args.filter_due_date as string;
    if (args.filter_created_at) query["filter[createdAt]"] = args.filter_created_at as string;
    if (args.filter_search) query["filter[search]"] = args.filter_search as string;
    if (args.filter_root_cause_id) query["filter[rootCauseId]"] = args.filter_root_cause_id as string;
    if (args.filter_location_id) query["filter[locationId]"] = args.filter_location_id as string;
    if (args.limit != null) query.limit = String(Math.min(Math.max(Number(args.limit) || 100, 1), 100));
    if (args.offset != null) query.offset = String(Number(args.offset) || 0);
    if (args.sort_by) query.sortBy = args.sort_by as string;
  
    const raw = await apsDmRequest(
      "GET",
      `construction/issues/v1/projects/${pid}/issues`,
      t,
      { query, headers: issuesHeaders(region) },
    );
    return json(summarizeIssuesList(raw));
  }

• src/aps-issues-helpers.ts:86-117 (helper)

  Helper function 'summarizeIssuesList' – extracts pagination info and maps raw API response to IssueSummary objects (id, displayId, title, status, assignee, dates, comment count, etc.).

  export function summarizeIssuesList(raw: unknown): {
    pagination: { limit: number; offset: number; totalResults: number };
    issues: IssueSummary[];
  } {
    const r = raw as Record<string, unknown> | undefined;
    const pagination = extractPagination(r);
    const results = Array.isArray(r?.results)
      ? (r!.results as Record<string, unknown>[])
      : [];
  
    const issues: IssueSummary[] = results.map((issue) => ({
      id: issue.id as string,
      displayId: (issue.displayId as number) ?? 0,
      title: (issue.title as string) ?? "",
      status: (issue.status as string) ?? "",
      assignedTo: (issue.assignedTo as string) ?? undefined,
      assignedToType: (issue.assignedToType as string) ?? undefined,
      dueDate: (issue.dueDate as string) ?? undefined,
      startDate: (issue.startDate as string) ?? undefined,
      locationDetails: (issue.locationDetails as string) ?? undefined,
      rootCauseId: (issue.rootCauseId as string) ?? undefined,
      published: (issue.published as boolean) ?? false,
      commentCount: (issue.commentCount as number) ?? 0,
      createdBy: (issue.createdBy as string) ?? "",
      createdAt: (issue.createdAt as string) ?? "",
      updatedAt: (issue.updatedAt as string) ?? "",
      closedBy: (issue.closedBy as string) ?? undefined,
      closedAt: (issue.closedAt as string) ?? undefined,
    }));
  
    return { pagination, issues };
  }

• src/aps-issues-helpers.ts:10-28 (helper)

  IssueSummary interface – type definition used by the issues list summariser.

  export interface IssueSummary {
    id: string;
    displayId: number;
    title: string;
    status: string;
    assignedTo?: string;
    assignedToType?: string;
    dueDate?: string;
    startDate?: string;
    locationDetails?: string;
    rootCauseId?: string;
    published: boolean;
    commentCount: number;
    createdBy: string;
    createdAt: string;
    updatedAt: string;
    closedBy?: string;
    closedAt?: string;
  }