In the bookingtime API, additionalData and customEntities are two powerful features designed for extending functionality and customizing data handling. These entities allow developers to add and organize flexible, dynamic information tied to core objects in the system, such as appointment, employee, or customer. This guide explains their purpose, how they are structured, and best practices for using them effectively.

What is additionalData?

The additionalData field is a key-value pair structure used to attach arbitrary information to various entities. It is particularly useful when predefined fields in the system do not cover your specific requirements. Here are the primary features of additionalData:

• Flexibility: You can store data of any kind, such as extra fields for reporting, configuration details, or customer-specific metadata.
• No Validation: The system does not enforce validation on additionalData fields. This provides the freedom to define and modify data structures as needed.
• Inheritance: For some objects, additionalData can be inherited from parent objects (like from a bookingTemplate to an appointment).
• Common Use Case: For example, in a customer object, additionalData might store preferences such as "preferred contact method" or "discount eligibility."

Example

"additionalData": {
"preferredLanguage": "EN",
"loyaltyPoints": 500,
"membershipLevel": "Gold"
}

Suggestions

• Use clear and consistent naming for your keys.
• Regularly document the structure and purpose of the additionalData fields to ensure maintainability.
• Avoid storing sensitive or critical business logic in additionalData fields, as they are loosely managed.

What are customEntities?

customEntities provide a way to define entirely new data models within the bookingtime system. While additionalData is suited for extending existing entities, customEntities allow you to build independent, reusable objects. They are particularly useful for representing domain-specific data that does not fit into existing system structures.

customEntities can be linked to several parent entities.

• appointment
• appointmentTemplate
• bookingTemplate
• bookingResource
• customEntity
• customer
• employee
• file
• resource

Features of customEntities

• Custom Data Models: Define unique fields, properties, and data types for your entity.
• Entity Management: Easily manage customEntities across the organization and integrate them into booking workflows.
• Linking: You can link customEntities to other system entities, such as appointment or organization, for context-specific use.

Example use case

A subscription service might need to manage various membership tiers for its customers. Using customEntities, you can define an entity called "membershipLevel" with fields like "tierName" (e.g., Basic, Premium, VIP), "monthlyFee", "includedFeatures" (e.g., priority support, free shipping), and "discountRate". These "membershipLevel" entities can be linked to customers or used in appointments to apply specific rules or benefits during the booking process.

Integrating additionalData and customEntities

Both additionalData and customEntities can work in tandem. For example, a custom entity could have additional metadata stored in its additionalData field for further customization.

Implementation Workflow

1. Define Custom Entities: Use the API to define a customEntity with the required fields and relationships.
2. Store Extra Data: Use additionalData to attach temporary or situation-specific information.
3. Link to Core Entities: Link customEntities to appointments, customers, or other core entities.
4. Query and Filter: Use the API to filter and search based on custom data fields.

API endpoints

• addCustomEntity: Defines a new custom entity.
• linkCustomEntityToAppointment: Links a custom entity to an appointment.
• editCustomEntity: Modifies or adds new key-value pairs to the additionalData field.

Conclusion

additionalData and customEntities are essential tools for developers working with the bookingtime API. They offer unparalleled flexibility and extensibility for tailoring the system to unique business needs.