aps_issues_update

Instructions

Implementation Reference

• src/index.ts:1344-1389 (handler)

  The handler function for 'aps_issues_update' tool. It validates project_id and issue_id, strips 'b.' prefix from project ID, builds a request body from provided optional fields (title, description, status, assigned_to, due_date, etc.), then sends a PATCH request to construction/issues/v1/projects/{pid}/issues/{issueId}. The response is summarized via summarizeIssueDetail.

  // ── aps_issues_update ───────────────────────────────────────
  if (name === "aps_issues_update") {
    const projectId = args.project_id as string;
    const issueId = args.issue_id as string;
    const e1 = validateIssuesProjectId(projectId);
    if (e1) return fail(e1);
    const e2 = validateIssueId(issueId);
    if (e2) return fail(e2);
  
    const pid = toIssuesProjectId(projectId);
    const region = args.region as string | undefined;
    const t = await token();
  
    const body: Record<string, unknown> = {};
    if (args.title != null) body.title = args.title;
    if (args.description != null) body.description = args.description;
    if (args.status != null) body.status = args.status;
    if (args.assigned_to && !args.assigned_to_type)
      return fail("assigned_to_type is required when assigned_to is provided.");
    if (args.assigned_to != null && args.assigned_to_type != null) {
      body.assignedTo = args.assigned_to;
      body.assignedToType = args.assigned_to_type;
    } else if (args.assigned_to_type != null) {
      body.assignedToType = args.assigned_to_type;
    }
    if (args.due_date != null) body.dueDate = args.due_date;
    if (args.start_date != null) body.startDate = args.start_date;
    if (args.location_id != null) body.locationId = args.location_id;
    if (args.location_details != null) body.locationDetails = args.location_details;
    if (args.root_cause_id != null) body.rootCauseId = args.root_cause_id;
    if (args.published != null) body.published = args.published;
    if (args.watchers != null) body.watchers = args.watchers;
    if (args.custom_attributes != null) body.customAttributes = args.custom_attributes;
  
    if (Object.keys(body).length === 0) {
      return fail("No fields to update. Provide at least one field to change.");
    }
  
    const raw = await apsDmRequest(
      "PATCH",
      `construction/issues/v1/projects/${pid}/issues/${issueId}`,
      t,
      { body, headers: issuesWriteHeaders(region) },
    );
    return json(summarizeIssueDetail(raw));
  }

• src/index.ts:651-713 (registration)

  Registration of the 'aps_issues_update' tool in the TOOLS array. Defines the name, description, and inputSchema describing accepted parameters: project_id, issue_id, and optional fields like title, status, assigned_to, due_date, etc.

  // 15 ── aps_issues_update
  {
    name: "aps_issues_update",
    description:
      "Update an existing issue. Only include the fields you want to change. " +
      "⚠️ Requires 'data:write' in APS_SCOPE. " +
      "To see which fields the current user can update, check permittedAttributes in the issue detail.",
    inputSchema: {
      type: "object" as const,
      properties: {
        project_id: {
          type: "string",
          description: "Project ID – accepts with or without 'b.' prefix.",
        },
        issue_id: {
          type: "string",
          description: "Issue UUID to update.",
        },
        title: { type: "string", description: "New title. Optional." },
        description: { type: "string", description: "New description. Optional." },
        status: {
          type: "string",
          enum: ["draft", "open", "pending", "in_progress", "in_review", "completed", "not_approved", "in_dispute", "closed"],
          description: "New status. Optional.",
        },
        assigned_to: { type: "string", description: "New assignee Autodesk ID. Optional." },
        assigned_to_type: {
          type: "string",
          enum: ["user", "company", "role"],
          description: "Assignee type. Required if assigned_to is set.",
        },
        due_date: { type: "string", description: "New due date (ISO8601). Optional." },
        start_date: { type: "string", description: "New start date (ISO8601). Optional." },
        location_id: { type: "string", description: "New LBS location UUID. Optional." },
        location_details: { type: "string", description: "New location text. Optional." },
        root_cause_id: { type: "string", description: "New root cause UUID. Optional." },
        published: { type: "boolean", description: "Set published state. Optional." },
        watchers: {
          type: "array",
          items: { type: "string" },
          description: "New watcher list. Optional.",
        },
        custom_attributes: {
          type: "array",
          items: {
            type: "object",
            properties: {
              attributeDefinitionId: { type: "string" },
              value: {},
            },
            required: ["attributeDefinitionId", "value"],
          },
          description: "Custom attribute values to update. Optional.",
        },
        region: {
          type: "string",
          enum: ["US", "EMEA", "AUS", "CAN", "DEU", "IND", "JPN", "GBR"],
          description: "Data centre region. Defaults to US.",
        },
      },
      required: ["project_id", "issue_id"],
    },
  },

• src/index.ts:1177-1187 (helper)

  Helper functions used by the update handler: issuesHeaders() builds optional region headers, issuesWriteHeaders() adds Content-Type for PATCH requests.

  /** Build optional headers for Issues API calls. */
  function issuesHeaders(region?: string): Record<string, string> {
    const h: Record<string, string> = {};
    if (region) h["x-ads-region"] = region;
    return h;
  }
  
  /** Build headers for Issues API write operations (POST/PATCH). */
  function issuesWriteHeaders(region?: string): Record<string, string> {
    return { "Content-Type": "application/json", ...issuesHeaders(region) };
  }

• src/aps-issues-helpers.ts:69-71 (helper)

  The toIssuesProjectId helper strips the 'b.' prefix from project IDs, used by the update handler before making the API call.

  export function toIssuesProjectId(projectId: string): string {
    return projectId.replace(/^b\./, "");
  }

• src/aps-issues-helpers.ts:119-167 (helper)

  The summarizeIssueDetail helper transforms the raw API response into a compact IssueDetailSummary object, used by the update handler to return a clean result.

  /** Summarise a single issue response – keeps more detail than the list summary. */
  export function summarizeIssueDetail(raw: unknown): IssueDetailSummary {
    const issue = raw as Record<string, unknown>;
  
    const customAttrs = Array.isArray(issue.customAttributes)
      ? (issue.customAttributes as Record<string, unknown>[]).map((ca) => ({
          id: (ca.attributeDefinitionId as string) ?? "",
          value: ca.value,
          type: (ca.type as string) ?? undefined,
          title: (ca.title as string) ?? undefined,
        }))
      : undefined;
  
    const linkedDocs = Array.isArray(issue.linkedDocuments)
      ? issue.linkedDocuments.length
      : 0;
  
    return {
      id: issue.id as string,
      displayId: (issue.displayId as number) ?? 0,
      title: (issue.title as string) ?? "",
      description: (issue.description as string) ?? undefined,
      status: (issue.status as string) ?? "",
      issueTypeId: (issue.issueTypeId as string) ?? undefined,
      issueSubtypeId: (issue.issueSubtypeId as string) ?? undefined,
      assignedTo: (issue.assignedTo as string) ?? undefined,
      assignedToType: (issue.assignedToType as string) ?? undefined,
      dueDate: (issue.dueDate as string) ?? undefined,
      startDate: (issue.startDate as string) ?? undefined,
      locationId: (issue.locationId 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,
      customAttributes: customAttrs,
      linkedDocumentCount: linkedDocs,
      watchers: Array.isArray(issue.watchers)
        ? (issue.watchers as string[])
        : undefined,
      permittedStatuses: Array.isArray(issue.permittedStatuses)
        ? (issue.permittedStatuses as string[])
        : undefined,
    };
  }