Core Concepts
Product Relationships Documentation
The product is the heart of all relationships within the system. From the product, several key relationships branch out, each serving an important role in defining user access and capabilities.
The Product
Product Components
A product consists of the following components:
- weight_curation: Integer value representing the curation weight of the product.
- name: Character varying, representing the product’s name.
- description: Text providing a detailed description of the product.
- support_url: Character varying, URL for product support.
- try_url: Character varying, URL for trying the product.
- source_url: Character varying, URL of the product source.
- submission_notes: Text field for submission notes related to the product.
- notification_emails: Character varying, email addresses for notifications related to the product.
- instructions: Character varying, providing instructions for the product.
- weight_search: Integer value representing the search weight of the product.
MimeType Relationship
Products have an associated MimeType, which defines the format of the product and how it should be handled.
A MimeType consists of the following components:
- name: Character varying, representing the name of the MIME type.
- value: Character varying, representing the value of the MIME type.
- default: Boolean indicating whether this MIME type is the default.
- priority: Integer representing the priority of the MIME type.
Badge Relationship
Products can have multiple Badges to highlight specific features or attributes.
A Badge consists of the following components:
- visible_in_listing: Boolean indicating whether the badge is visible in product listings.
- name: Character varying, representing the name of the badge.
- description: Text providing a description of the badge.
- pinned: Boolean indicating whether the badge is pinned for emphasis.
- priority: Integer representing the priority of the badge.
- category: Character varying, representing the category of the badge.
- visible_in_catalog: Boolean indicating whether the badge is visible in product catalogs.
Reference Relationship
Products can have multiple References that provide additional information or external resources related to the product.
A Reference consists of the following components:
- name: Character varying, representing the name of the reference.
- url: Character varying, representing the URL of the reference.
- description: Character varying, providing a description of the reference.
Screenshot Relationship
Products can have multiple Screenshots to visually represent the product’s features or usage.
A Screenshot consists of the following components:
- Caption: Character varying, providing a caption for the screenshot.
- Name: Character varying, representing the name of the screenshot.
Sub-Product Relationship
Products can have Sub-Products, which represent the hierarchical structure of related products within the system. A Sub-Product is a product that exists under a parent product, either extending its capabilities or acting as a component of a larger suite.
A SubProduct consists of the following components:
- parent_id: UUID, linking the sub-product to its parent product.
- child_id: UUID, linking the sub-product to the product that acts as its child.
Philosophy of Sub-Product Relationships
The Sub-Product relationship allows for the modular design of product offerings, where complex products can be broken down into smaller, related components. This structure supports bundling, customization, and scalability in product offerings.
Sub-products can either inherit licenses and capabilities from the parent product, or they can have their own specific configurations. This flexibility is essential for addressing varying customer needs, providing options to combine products or build tailored solutions that best fit the requirements of users.
The Products’ License
License Relationship
The product’s crucial relationship is with the license. This relationship grants the product various capabilities for users, such as the ability to download and access it. Permissions are provided through this license, giving users the necessary access to utilize the product effectively.
A license consists of the following components:
- name: Character varying, representing the license’s name.
- url: Character varying, providing a link to the license details.
- description: Character varying, providing a description of the license.
- expiry: Integer value representing the duration of the license in days.
- expires_at: Timestamp without time zone, indicating when the license will expire.
- days_valid: Integer value indicating the number of days the license is valid.
- uses: Integer value representing the number of times the license can be used.
Philosophy of the License Relationship
The philosophy behind the license relationship is centered on providing structured, yet flexible, access to the product. A license serves as the foundational permission framework that governs how and when a user can interact with a product. By defining key elements such as validity duration, usage limits, and conditions for access, the license ensures both compliance and adaptability to different user needs.
Licensing allows for tailored access control, enabling products to be distributed under various terms, such as limited-time access, usage-based permissions, or unrestricted access. This flexibility is crucial to accommodate diverse scenarios, from trials and evaluations to full-fledged deployments. The dynamic nature of licensing makes it possible to align product distribution with business models, ensuring that access terms can evolve as products and user needs change.
Product License and Fee Relationships
The Product License represents the specific linkage between a product and its license. It serves as the intermediary that ties a particular product to the conditions defined by its license.
A Product License consists of the following components:
- product_id: UUID, linking to the associated product.
- license_id: UUID, linking to the specific license applied to the product.
- external_id: UUID, an external reference identifier.
- created_at: Timestamp without time zone, indicating when the product license was created.
- updated_at: Timestamp without time zone, indicating when the product license was last updated.
The Fee relationship is tied to the Product License. Fees represent the financial aspect of acquiring and maintaining a license for the product. They provide an important bridge between the contractual relationship of the license and the practical, financial obligations it entails.
A Fee consists of the following components:
- name: Character varying, representing the name of the fee.
- description: Character varying, providing details about the fee.
- kind: Character varying, categorizing the type of fee (e.g., subscription, one-time, etc.).
- amount: Numeric value representing the monetary amount of the fee.
- event_key: Character varying, indicating the event or trigger associated with the fee.
Philosophy of Product License and Fee Relationships
The Product License relationship is essential for managing how specific products are connected to their respective licenses. By having a distinct entity that ties a product to a license, the system allows for greater flexibility in defining different licensing conditions for different products. This approach enables businesses to adapt their offerings based on customer needs, market demands, and strategic goals.
Licenses
A Marketplace License defines usage terms outside of any specific product and independent of financial requirements. Each license type governs how entitlements are dynamically interpreted and enforced. The primary types include:
- Indefinite: These licenses come with no time-based restrictions, making them ideal for open-source software (F/OSS) products or shareware, such as those covered under licenses like Apache 2.0, MIT, or BSD.
- Relative: Valid for a specific period relative to the datetime the entitlement is activated. These are suitable for models like long-term subscriptions, short-term rentals, or evaluation copies, offering a flexible time-bound usage framework.
- Absolute: These licenses have a fixed validity until a specific date or event, like the end of a calendar year or a special release period, making them suitable for beta testing or pre-release reviewer access.
A given product may be available under multiple license types. Curators can define business rules that govern which licenses are offered and under what circumstances, as long as these rules align with the authorization API endpoints to ensure compliance.
When a user acquires a license for a product (a ProductLicense), this record forms an Entitlement. The entitlement is directly linked to the user acquiring the product and includes additional metadata that captures the specifics of the licensing transaction. Commercial systems often extend these records to integrate with order processing providing a comprehensive view of customer interactions.
It is crucial to implement a diverse array of licensing models to support both F/OSS and commercial works. When fully implemented, the system can accommodate a range of revenue models, offering flexibility to meet the varied needs of customers.
Fee Structures
The Fee relationship complements the licensing model by attaching financial terms to the product license. Fees are integral to the overall licensing strategy, as they directly influence the perceived value and accessibility of the product. The fees can be classified into three primary types:
- Initial Price: This fee represents the cost of purchasing the product with a specific license at the time of acquisition. Prices may vary over time, making it important to differentiate between the initial price and subsequent renewal fees.
- Current Renewal Fee: This fee specifies the cost to renew access to the product under the same license at a later date. For instance, a product may have an initial fee of $2000 for a one-year license, but the renewal fee after a year could rise to $4000.
- Metered Usage: This model is based on variable charges, such as those related to API requests or compute resource usage (e.g., API and EC2 charges). Metered billing leverages telemetry to track user interactions with the product automatically, offering detailed reports on usage patterns and costs.
The Fee relationship enriches the licensing model by providing a dynamic and adaptable pricing structure. It allows businesses to manage and communicate the cost structures associated with accessing or using their products transparently. With event-based fees, companies gain granular control over when and how charges apply, such as during renewals or through usage-based billing.
A Dynamic and Decoupled Model
Together, the Product License and Fee relationships embody a philosophy of decoupled management of access rights and their economic implications. This separation offers flexibility, allowing businesses to adjust licensing conditions or pricing models independently. This approach ensures that the framework remains robust and adaptable, capable of meeting the diverse needs of customers while aligning with evolving business strategies.
Entitlement Relationship
The Entitlement relationship represents the direct association between a user and a product license. It defines the user’s right to access a product under specific licensing conditions and serves as the mechanism by which users are granted permissions to interact with products.
An Entitlement consists of the following components:
- valid_from: Timestamp without time zone, indicating when the entitlement becomes valid.
Philosophy of the Entitlement Relationship
The Entitlement relationship is fundamental to managing how users interact with products in a licensed environment. It represents the user’s authorization to use the product, bridging the gap between the product license and the end user. By linking users to specific product licenses, entitlements allow for precise control over who can access a product and under what conditions.
The entitlement model is designed to be flexible, allowing entitlements to be granted based on varying conditions such as time periods, specific users, or particular usage events. This adaptability ensures that access to the product is controlled in a way that aligns with business needs, whether for short-term trials, long-term subscriptions, or role-based access.
By decoupling user access from the license itself, entitlements enable dynamic adjustments to user permissions without altering the underlying product license. This approach allows for seamless changes in user access based on evolving requirements, making it easier to manage individual user rights while maintaining consistent licensing structures across the product ecosystem.
Claim Relationship
The Claim relationship is a further extension of the Entitlement relationship. It represents the specific instance where a user (claimant) exercises their entitlement to access a product. Claims are a record of the authorization process, capturing when and how a user has been granted access to a product under a particular entitlement.
A Claim consists of the following components:
- claimant_type: Character varying, indicating the type of claimant (e.g., individual user, organization).
- authorization_count: Integer, indicating how many times the claim has been authorized.
Philosophy of the Claim Relationship
The Claim relationship is essential for tracking and managing how entitlements are used in practice. It provides a mechanism for logging each instance of product access, thereby enabling a detailed audit trail for how users interact with the product under a particular license. This relationship helps ensure transparency, accountability, and effective management of user access rights.
Claims also allow for fine-grained tracking of product usage. By capturing details such as the number of authorizations and the time of authorization, the system can provide valuable insights into product utilization patterns. This information can be used to evaluate product demand, ensure compliance with licensing terms, and make informed decisions about renewing or updating licenses.
In essence, the Claim relationship supports a proactive approach to managing entitlements, ensuring that product access is both controlled and traceable. By keeping a detailed record of each claim, the system ensures that users are adhering to their entitlements while allowing administrators to effectively monitor and adjust access as needed.
Claim Relationship with Users and Groups
At a fundamental level, a Claim is related to a User. A claim is initiated by a user (claimant) who seeks access to a product under a specific entitlement.
However, claims can also belong to a Group. A group is a collection of users, and claims made by a group can be exercised on behalf of its members. This relationship allows for more organized and scalable management of access rights, particularly in scenarios where multiple users need similar access.
A Member consists of the following components:
- group_id: UUID, linking the membership to the associated group.
- user_id: UUID, linking the membership to the associated user.
Philosophy of Claim Relationship with Users and Groups
The Claim relationship with Users and Groups reflects a dual approach to managing access rights in both individual and collective contexts. For individual users, claims provide a straightforward mechanism for accessing products based on specific entitlements. This ensures that access is granted based on individual rights, providing a personalized and precise control mechanism.
For Groups, claims allow collective management of entitlements. Groups are particularly useful in organizational settings where multiple users require similar access rights. By associating claims with groups, it becomes easier to manage permissions at scale, ensuring consistency and reducing administrative overhead. Group-based claims also allow members to inherit entitlements, simplifying the process of onboarding new users or adjusting access as group membership changes.
This dual approach ensures that access rights are flexible, scalable, and aligned with both individual and collective needs. By enabling claims to be made by either users or groups, the system supports a wide range of use cases, from personal access requests to enterprise-level entitlement management, ensuring both granular control and operational efficiency.
Sub-Products and Licensing
Products can also have sub-products, which may have their own licenses or inherit licensing from the parent product. There are a few common types of licensing agreements used for sub-products:
- Inherited Licensing: All sub-products inherit the license of the parent product. This is useful for bundled products that share the same licensing terms as the parent product.
- Custom Licensing: Sub-products can have their own unique licensing agreements, different from the parent product. This allows for more tailored licensing in cases where sub-products require different terms to meet specific use cases.
The Products’ Build
Build Relationship
A Build represents a specific version of a product that has been developed and packaged for deployment. Builds are integral to both product and user interactions, providing a bridge between product versions and user-deployed instances.
A Build consists of the following components:
- product_id: UUID, linking the build to the associated product.
- version: Character varying, representing the version of the build.
- container_repository: Character varying, indicating the container repository for the build.
- container_tag: Character varying, representing the container tag for the build.
- permissions: JSON containing permissions associated with the build.
- release_notes: Text providing release notes for the build.
- configuration_id: UUID, linking to the configuration associated with the build.
Relationships Involving Builds
- Product: Each Build is associated with a specific Product, representing a particular version or iteration of that product. This relationship ensures that all updates, releases, or patches are tracked and linked back to the original product.
- Configuration: A Build is linked to a Configuration that defines the settings and tasks needed for the build to operate effectively.
- Platform: Users interact with Builds through Platforms, which serve as the deployment environment.
Configuration and Task Relationships
A Configuration represents the settings or parameters needed for a Build or Sub-Product to function correctly. Configurations allow for a consistent setup across different versions or components of a product.
A Configuration consists of the following components:
- id: UUID, unique identifier for the configuration.
- name: Character varying, representing the name of the configuration.
Relationships Involving Configurations
- Build: Each Build has a Configuration associated with it that provides the necessary parameters and settings for the build.
- Sub-Product: Sub-Products can also have configurations, ensuring that the settings for each sub-product are maintained independently or inherited from the parent product as needed.
- Task: Each Configuration can contain one or multiple Tasks that define specific actions to be executed as part of the configuration.
A Task consists of the following components:
- id: UUID, unique identifier for the task.
- configuration_id: UUID, linking the task to its associated configuration.
- name: Character varying, representing the name of the task.
- command: Character varying, representing the command to be executed.
- created_at: Timestamp without time zone, indicating when the task was created.
- updated_at: Timestamp without time zone, indicating when the task was last updated.
Philosophy of Configuration and Task Relationships
The Configuration and Task relationships are designed to provide a flexible yet consistent way to manage how products and builds are set up and maintained. Configurations encapsulate all the necessary parameters, while tasks define the actions required to apply these settings.
By separating Tasks from Configurations, the system allows for reuse and modularity, ensuring that similar tasks can be applied across different builds or products without redundant definition. This separation also supports scalability, enabling administrators to create complex setups by combining different configurations and tasks as needed.
Platform and Instance Relationships
A Platform serves as a deployment environment where users can manage instances of product builds. It represents the technical infrastructure used to launch and run products.
A Platform consists of the following components:
- logs_url: Character varying, representing the URL for platform logs.
- name: Character varying, representing the platform’s name.
- user_id: UUID linking the platform to its owner (the user).
- key: Text representing the platform’s access key.
- notes: Character varying, containing notes related to the platform.
- traces_enabled: Boolean indicating if traces are enabled on the platform.
- traces_url: Character varying, representing the URL for traces.
- metrics_enabled: Boolean indicating if metrics are enabled.
- metrics_url: Character varying, representing the URL for metrics.
Relationships Involving Platforms
- User: A Platform is created and managed by a User, providing the environment where builds can be deployed and managed.
Philosophy of Product, Build, Platform, Configuration, and Task Relationships
The relationship between Products, Builds, Platforms, Instances, Configurations, and Tasks provides a comprehensive framework for product lifecycle management:
- Products represent the conceptual and functional components that are offered to users.
- Builds are specific versions of products that have been developed, validated, and prepared for deployment, ensuring that changes and improvements can be effectively tracked and managed.
- Configurations define the settings and parameters required for builds and sub-products, ensuring that each deployment follows consistent guidelines.
- Tasks provide specific variables and actions within configurations, allowing for flexible and reusable setup processes.
- Platforms serve as the environments where builds are deployed, providing the necessary infrastructure to bring a product version to life.
This layered relationship model ensures that the product lifecycle is managed in a structured yet flexible manner, enabling rapid iterations, scalability, and efficient deployment strategies.