[TYPE 1] [Collections] #1754

Activity

1. jorwoods

   added

   enhancement

   needs investigationIssue needs to be looked at by TableauIssue needs to be looked at by Tableau

   on Mar 10, 2026
2. jorwoods commented on Mar 10, 2026

   

   jorwoods

   on Mar 10, 2026

   ContributorAuthor

   More actions

   The Collections API endpoints return JSON by default. They can be made to return XML by passing in the correct request header. Regarding adding the support, I have a few questions.

   1. Should the Collections endpoints operate in JSON, their default, or XML the way most of TSC does?
   2. The fields within the collections endpoint to "List items in a collection" don't have the same structure as what is returned by the rest of the XML endpoints. E.G. for workbooks, owner details are not nested under an owner element. Tags are <tags><value>some tag</value></tags> instead of <tags><tag>some tag</tag></tags>. So even if the XML is used, the parsing will have to follow separate paths.
   3. If the we decide not to include full object parsing directly in the Collections listing, does it support anything like fields so we can reduce network traffic of unused XML attributes?
   4. The "List Items in a collection" XML contains a "position" attribute on the item element. This value is negative. Can you help me understand this value? Is a closer to 0 value earlier or later in the collection?
   5. The official API docs don't contain any details on the various error codes and what they might mean. Should I try to parse these into ServerResponseErrors or something else?
   6. There are values like id, ownerId, siteId, etc. that are purely numeric and not UUID4s like I am used to seeing. Do we need to do anything with those IDs? Do they correspond to IDs returned by other REST or Metadata endpoints?
3. jacalata commented on Jun 17, 2026

   

   jacalata

   on Jun 17, 2026

   Last edited by jacalata

   Contributor

   More actions

   Thanks for the great questions — here are answers from the server-side implementation:

   1. JSON vs XML?
   Both are equally supported server-side. Since TSC uses XML throughout, I'd recommend sticking with XML for consistency.

   2. Why is the XML structure different for List Items?
   This is intentional. The Collections service uses a reflection-based adapter (CollectionItemContentAdapter) that serializes content items by reflecting on the content type's methods via @ContentFieldDefinition annotations. This produces a flat structure — owner fields come out as siblings (ownerId, ownerName, etc.) rather than nested under <owner>. The <value> tag for list items (including tags) is the adapter's generic list serialization pattern, not tags-specific. So yes, the parsing will need separate paths from the standard endpoints.

   3. Does it support fields to reduce network traffic?
   No — the only query parameters supported are sort, filter, pageSize, page, and search. No field selection.

   4. What does the negative position value mean?
   The negative positions come from how items are inserted: each time you add items, the server finds the current minimum position and assigns minPosition - 1 to new items, so new items always land at the front of the list. A fresh collection starts at 0, so the first item added gets position -1, the next batch gets -2, -3, etc. More negative = earlier/first in the collection.
   This is a transient state. Once you call PATCH .../orderItems to reorder anything, verifyAndFixPositions rewrites all positions as sequential integers (1, 2, 3...) and the negatives disappear. After that point positions are stable positive integers.
   So in practice: sort by position asc to get correct order regardless of whether you're in the negative or positive regime.

   5. Error codes — parse into ServerResponseError?
   Collections has its own set of 16 error codes in the range 450xxx:
   COLLECTION_NOT_FOUND (450404), PERMISSION_DENIED (450403), DUPLICATE_KEY (450409), INVALID_LUID (450008), TOO_MANY_ITEMS (450013), COLLECTIONS_NOT_ENABLED (450014), TOO_MANY_COLLECTIONS (450015), etc. These are distinct from general REST error codes. I'd parse them into ServerResponseErrors like we do elsewhere — the codes are distinct enough to be meaningful.

   6. Are the numeric IDs useful?
   The numeric id, ownerId, and siteId values are internal database PKs — not the same IDs used elsewhere in the REST API and not useful for interoperability. Content items (workbooks, views, datasources, flows, and projects) all expose a luid field within the item's content block. That luid is a standard UUID4 and matches the identifier returned by the normal REST API endpoints. TSC should use luid rather than id when cross-referencing collection items with other endpoints.
4. jacalata

   assigned

   jorwoods

   on Jul 22, 2026
5. github-actions commented on Sep 21, 2026

   

   github-actionsBot

   on Sep 21, 2026 – with GitHub Actions

   More actions

   This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 14 days if no further activity occurs. If this is still relevant, please comment to keep it open.
6. github-actions

   added

   stale

   on Sep 21, 2026
7. github-actions commented on Oct 5, 2026

   

   github-actionsBot

   on Oct 5, 2026 – with GitHub Actions

   More actions

   Closing due to inactivity. If this is still relevant, please reopen or file a new issue.
8. github-actions

   closed this as not plannedon Oct 5, 2026
9. jacalata

   reopened this on Oct 9, 2026
10. jacalata

    removed

    stale

    on Oct 9, 2026