Enhance custom license fields documentation with use cases and examples #3794
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This update adds conceptual guidance and practical examples to complement the existing procedural content for managing custom license fields. Key improvements: - Added "About License Fields" section with cross-links to field access documentation (SDK, KOTS, Helm, verification) - Added "Common Use Cases" section with concrete examples (capacity limits, feature tiers, configuration, credentials, business logic) - Added "How Custom Fields Appear in Licenses" subsection with example license YAML showing custom fields in entitlements - Enhanced Field Types table with "Purpose" and "When to Use" columns with practical examples - Added Vendor API v3 reference for programmatic field management - Improved formatting with proper note callouts These enhancements help vendors understand when and why to use custom fields, not just how to create them. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
✅ Deploy Preview for replicated-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
replicated-ci
added
type::docs
✅ Deploy Preview for replicated-docs-upgrade ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
paigecalvert
approved these changes
Jan 28, 2026
Contributor
paigecalvert
left a comment
paigecalvert
left a comment
There was a problem hiding this comment.
thanks amber! good additions
| | Field | The name used to reference the field. This value cannot be changed. | | ||
| | Title| The display name for the field. This is how the field appears in the Vendor Portal and the Admin Console. You can change the title in the Vendor Portal. | | ||
| | Type| The field type. This value cannot be changed. See [Understanding Custom License Field Types](#understanding-custom-license-field-types) for more information. | ||
| | Type| The field type. This value cannot be changed. See [Custom License Field Types](#custom-license-field-types). |
| | Boolean | True or false | checkbox | | ||
| | Password | A short string of text that is masked on display | password | | ||
| | Enum | Provides a list of possible values | dropdown | | ||
| | Type | Description | Use cases | Widget | |
Contributor
There was a problem hiding this comment.
combined the purpose and when to use columns into "use cases" (seemed like they mostly said the same thing)
| | Type | Description | Use cases | Widget | | ||
| |------|-------------|-----------|--------| | ||
| | Integer | A whole number numeric value | Use for numeric capacity limits, quotas, or counts. For example, `seats: 100` or `max_nodes: 5`. | Text field | | ||
| | String | Single-line text values | Use for short form text that fits on a single line, like short identifiers or environment names. For example, `account_manager: jeff_noble`. | Text field | |
Contributor
There was a problem hiding this comment.
changed the example for string fields to account_manager : firstname_lastname, since tier was mentioned as an example of when to use Enum
| ::: | ||
|
|
||
| String, Text, Password, and Enum types are all represented as strings in the license. | ||
| ### How Custom Fields Appear in Licenses |
Contributor
There was a problem hiding this comment.
small reorg to move this new section under the table that describes all the field types
| - Enable access to certain features or tiers. For example, you could add a `tier` license field with values such as "basic", "premium", or "enterprise". You could also add a `support_level` field with options for "standard" or "priority". | ||
| - Store configuration settings like `api_endpoint`, `region`, `data_center`, or `environment` | ||
| - Include credentials in the license like `api_key`, `auth_token`, or `encryption_key` using the "Password" license field type to mask values in the UI | ||
| - Add metadata such as `contract_type`, `renewal_date`, or `account_manager` for reporting and workflows |
Contributor
There was a problem hiding this comment.
moved the new use case examples to the Manage Custom License Fields subheading where some of this conceptual info was living
| * You can also create custom fields to define entitlements for your application. For example, you can create a custom field to set the number of active users permitted, or add metadata like `contract_type`, `renewal_date`, or `account_manager` for reporting purposes. | ||
|
|
||
| For more information, see [Manage Customer License Fields](/vendor/licenses-adding-custom-fields). | ||
| For more information, see [Manage Built-In License Fields](/vendor/licenses-adding-custom-fields#manage-built-in-license-fields) and [Manage Custom License Fields](/vendor/licenses-adding-custom-fields#manage-custom-license-fields). |
Contributor
There was a problem hiding this comment.
updated the xref on the main About Licenses page so that people can go direct to the subsection on custom license fields (easier to find)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR enhances the custom license fields documentation by adding conceptual guidance and practical examples to complement the existing procedural how-to content.
Preview: https://deploy-preview-3794--replicated-docs.netlify.app/vendor/licenses-adding-custom-fields
Original: https://docs.replicated.com/vendor/licenses-adding-custom-fields#manage-built-in-license-fields
Key Changes
1. Added "About License Fields" section (May not be necessary but I didn't necessarily recognize that the querying info was a separate page at first)
licenses-reference-sdk- For Replicated SDKlicenses-reference-kots-runtime- For KOTS installerslicenses-reference-helm- For Helm installationslicenses-verify-fields-sdk-api- For verification2. Added "Common Use Cases for Custom License Fields" section (I like this section because it helps people understand how they could use these which is a common question)
Provides concrete examples organized by category:
max_users,seats,storage_gb,api_calls_per_monthtier,support_levelapi_endpoint,region,data_center,environmentapi_key,auth_token,encryption_keycontract_type,renewal_date,account_manager3. Added "How Custom Fields Appear in Licenses" subsection
spec.entitlements4. Enhanced Field Types table. (goal was to extend the 'how you might use these' examples)
Added two new columns to the existing table:
Before:
After:
5. Added Vendor API v3 reference
createcustomlicensefieldAPI endpointBenefits
These enhancements provide vendors with:
What's NOT Changed
This PR preserves all existing content:
Testing Plan
licenses-reference-sdk, etc.)🤖 Generated with Claude Code + Amber notes/edits