Extended properties (XP) best practices

Extended properties (XP) provide a mechanism for adding custom data points to OrderCloud objects that aren't natively supported in the platform's data models. While XP offers great flexibility, understanding its proper usage and limitations is crucial for building efficient applications.

Definition

Extended properties are more than just arbitrary JSON objects attached to OrderCloud models. They represent a purposeful way to extend the platform's data model with specific properties your application needs. Here's a simple example:

user.xp.FavoriteColor = "purple"

XP provides several key capabilities:

• Flexible data storage for custom properties
• Automatic property indexing for efficient queries
• Advanced search capabilities (for example, you can quickly find all users whose favorite color is purple)

This functionality is highly optimized for adding and managing individual data points, but it's important to understand that XP is not designed for storing large, complex data structures.

Guidelines

1. Use native properties first

Extended properties should be used as a last resort, not a default solution. Before using XP:

• Review all existing properties of the model you want to extend
• Understand their purpose and behavior
• Consider using writable IDs for external system integration

For example, if you're integrating with a back-office system, use order.ID directly instead of creating order.xp.ExternalSystemID. Remember that XP properties lack the validation, behavior, and referential integrity that native properties provide.

2. Data size limits

OrderCloud imposes size limits on XP data to ensure optimal performance. When using XP:

• Avoid storing large text content like blog posts or extensive descriptions
• Use native fields like Product.Description for content requiring full-text or natural language search
• Focus on small, discrete data points that complement the native data model
• Consider external storage solutions for larger content needs

These limitations help maintain system performance and ensure XP remains efficient for its intended purpose.

3. Object structure

While XP supports arbitrarily deep objects, it's optimized for simple name/value pairs. When structuring your XP data:

• Use straightforward, flat property structures when possible
• Limit nested objects to cases where hierarchy adds clear value
• Keep object structures consistent across similar items

Here's an example of acceptable nesting for geographic coordinates:

address.xp.Coordinates = {
  Latitude: value,
  Longitude: value
}

This structure makes sense because latitude and longitude are inherently related properties that form a single logical unit.

4. List management

Lists in XP require careful consideration because they can grow unpredictably. When using lists:

• Choose lists only when you can reasonably predict their maximum size
• Use simple value arrays rather than object arrays
• Verify that the native data model doesn't already provide a suitable list structure

Here's an example of an appropriate list usage:

user.xp.PetNames = ["Max", "Bella"]

This works because:

• The list has a natural size limit (number of pets is typically small)
• It uses simple string values
• The information is specific to the user

5. Avoid duplicate data

Storing repeated lookup data in XP can lead to maintenance issues and increased storage costs. Consider this problematic approach:

order.xp.Category = {
  ID: "xyz123",
  Name: "Category Name",
  Description: "Long description..."
}

This practice creates several problems:

• Redundant storage of the same data across multiple orders
• Difficulty in updating information (requires changes to all instances)
• Increased data storage costs
• Potential for inconsistency

A better approach is to store only the reference:

order.xp.CategoryID = "xyz123"

This solution:

• Maintains data integrity
• Reduces storage requirements
• Makes updates simpler
• Follows proper data normalization practices

6. Configuration data

Most applications require some form of global configuration data. Before storing this in XP, consider:

• Does the data change frequently?
• Do you need a UI for managing the configuration?
• Is the data specific to individual resources?

For static or rarely changing configuration:

• Store in front-end code (e.g., JSON configuration files)
• Use environment variables
• Implement external configuration services

Only use XP for configuration when:

• The data changes frequently
• You need a UI for configuration management
• The configuration is specific to individual resources

7. Security considerations

XP data is visible to anyone with access to the parent object. Therefore:

Never store sensitive information in XP, including:

• Passwords
• Credit card numbers
• Personal identification numbers
• Authentication tokens
• Encryption keys

Storing credit card information in XP is not only a security risk but also violates OrderCloud's terms and conditions. For sensitive data:

• Use appropriate secure storage solutions
• Implement proper encryption
• Follow industry security standards
• Consider tokenization for sensitive references

Implementation examples

The following examples demonstrate proper XP usage patterns, from basic properties to more complex structures. Each example follows the guidelines outlined above.

Basic property

// Add single property
user.xp.Department = "Sales"

// Add multiple properties
user.xp = {
  Department: "Sales",
  EmployeeID: "E123",
  StartDate: "2025-01-15"
}

Nested data

// Location data
address.xp.GeoLocation = {
  Latitude: 44.9778,
  Longitude: -93.2650,
  Accuracy: "high"
}

// Contact preferences
user.xp.Communication = {
  PreferredMethod: "email",
  OptIn: true,
  Frequency: "weekly"
}

List handling

// Simple list
product.xp.Tags = ["new", "featured", "sale"]

// Structured list (use sparingly)
user.xp.Certifications = [
  {
    Name: "Security+",
    ExpiryDate: "2026-12-31"
  }
]

External storage options

Remember that OrderCloud is not a complete solution by itself. Just as you build custom front-ends to create useful applications, you may need additional back-end services for complex data requirements. Modern cloud platforms offer excellent options for handling data needs that exceed XP's scope:

• Firebase: Google's real-time database and backend services
• DynamoDB: Amazon's fast and flexible NoSQL database
• DocumentDB: Microsoft's globally distributed database service

These services excel at handling complex data structures, large datasets, and specialized querying needs that fall outside XP's intended use.

Support

OrderCloud's success depends on your application's success. We provide several support options to help you make the most of XP and other features:

• Free support resources and documentation
• Paid support packages for enterprise needs
• Early development guidance to ensure proper architecture

We encourage you to reach out during the early stages of development when architectural decisions have the most impact. Our team can help you determine the best way to use XP within your application's context.

XP exemplifies our flexibility over features philosophy, providing powerful customization capabilities while maintaining clear boundaries and purpose. Understanding these boundaries helps you build scalable, maintainable applications that make the most of OrderCloud's capabilities.

Related reading

• Using Extended Properties in Custom eCommerce Apps
• Configuring User and Application Data Access
• Ad-Hoc Products