Support include=planName on List User Plans

[adecounter]

Pull Request

Summary

GET /2.0/users/{userId}/plans gained an optional include query parameter whose only accepted value is planName, matching the response field it controls. When requested, each returned plan carries the name of the organization that owns it. This adds SDK support for it.

New listUserPlans overload. UserResources.listUserPlans gains a five-argument overload taking EnumSet<UserPlanInclusion>, serialized comma-separated via QueryUtil.generateCommaSeparatedList like every other include parameter in the SDK. The existing four-argument signature is untouched and simply delegates to the overload passing null, so source compatibility is preserved and existing callers need no changes.

Omitting the parameter is byte-identical to today. The include key is only added to the parameter map when includes != null, so callers on the original signature produce exactly the same request URL as before this change.

New planName field on UserPlan. It is optional and deserializes to null in two distinct cases: when the enrichment was not requested, and when the owning organization has no name. A null therefore does not by itself mean the enrichment was not requested, which the javadoc calls out.

Design note

The inclusion enum follows existing precedent rather than introducing a new pattern: 23 inclusion enums already exist in models/enums/, and listUsers in this same interface already takes an EnumSet<ListUserInclusion>.

Caching caveat

Organization names are cached server side for roughly four hours. A recently renamed organization may briefly report its previous name through this field. This is documented in the javadoc on both the overload and UserPlan.getPlanName() so callers are not surprised.

Files changed

File	Change
src/main/java/com/smartsheet/api/UserResources.java	Declares the new five-arg listUserPlans overload
src/main/java/com/smartsheet/api/internal/UserResourcesImpl.java	Implements the overload; original signature delegates to it
src/main/java/com/smartsheet/api/models/UserPlan.java	Adds the planName property with getter/setter
src/main/java/com/smartsheet/api/models/enums/UserPlanInclusion.java	New enum, single value PLAN_NAME -> planName
src/test/java/com/smartsheet/api/sdktest/users/TestListUserPlans.java	Asserts the query parameter and planName deserialization
CHANGELOG.md	Two bullets under Unreleased / Added

Testing

Run against the shared WireMock mappings from smartsheet/smartsheet-sdk-tests mainline, which now includes planName on the List User Plans all-properties mapping.

• ./gradlew sdkTest - 181 tests, 179 passed, 0 failures, 2 skipped
• ./gradlew test - 662 tests, 661 passed, 0 failures, 1 skipped
• ./gradlew clean build - BUILD SUCCESSFUL

All 3 skips are pre-existing and unrelated to this change (AutomationRulesTest.updateAutomationRule, SightsTest.copySight, UserResourcesImplTest.testPromoteAlternateEmail).

Test coverage in TestListUserPlans asserts include=planName appears in the request query params, that getPlanName() returns "Acme Corporation" for the plan that has one, and that it is null both for a plan omitting it and in the required-properties case.

One note for reviewers: this change adds a fourth checkstyleMain violation, MultipleStringLiterals for the string "include" now appearing 3 times in UserResourcesImpl.java. The baseline on mainline is 3 violations and checkstyleMain allows up to 5, so the build still passes. Happy to extract a constant if you would prefer to keep the count flat.

Checklist

• Read the contribution guide
• Successfully build your changes locally - Run ./gradlew clean build
• Include a title that clearly describes your changes and references relevant issues / backlog items
• Include a summary of your changes
• Include tests for your changes where possible

Summary by CodeRabbit

• New Features
  • Added support for requesting plan names when listing user plans.
  • User plan results can now include a planName value when requested; it remains unavailable when not included.
  • Added documentation describing the new query option and response field.

[coderabbitai]

📝 Walkthrough

Walkthrough

The SDK adds PLAN_NAME support to listUserPlans, serializes the include query parameter, and exposes the returned value through the nullable UserPlan.planName property. Tests cover included and omitted plan names.

Changes

User plan inclusion

Layer / File(s)	Summary
Plan name response contract src/main/java/com/smartsheet/api/models/UserPlan.java, src/main/java/com/smartsheet/api/models/enums/UserPlanInclusion.java	Adds nullable UserPlan.planName accessors and the PLAN_NAME inclusion value serialized as planName.
User-plan request integration src/main/java/com/smartsheet/api/UserResources.java, src/main/java/com/smartsheet/api/internal/UserResourcesImpl.java	Adds an inclusion-aware listUserPlans overload. The implementation delegates the existing overload and adds the include query parameter when provided.
Plan name validation and release notes src/test/java/com/smartsheet/api/sdktest/users/TestListUserPlans.java, CHANGELOG.md	Tests URL serialization and nullable response properties. The changelog documents the new support.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant UserResources
  participant UserResourcesImpl
  participant ListUserPlansAPI
  Caller->>UserResources: listUserPlans(..., PLAN_NAME)
  UserResources->>UserResourcesImpl: Forward inclusion set
  UserResourcesImpl->>ListUserPlansAPI: Request include=planName
  ListUserPlansAPI-->>UserResourcesImpl: Return UserPlan records
  UserResourcesImpl-->>Caller: Return paginated results with planName

Loading

Possibly related issues

• smartsheet/smartsheet-python-sdk#162 — Covers the same include=planName support and UserPlan plan-name exposure in the Python SDK.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 38.46% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the main change: support for the planName inclusion on List User Plans.
Description check	✅ Passed	The description includes the required summary, completed checklist, implementation details, test coverage, and build results.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[ggoranov-smar]

nit:

Suggested change

	EnumSet<UserPlanInclusion> includes
	EnumSet<UserPlanInclusion> include