Relation Field Type

Description:
The relation field type is used to create a link between cases of different types within Caseblocks. It allows you to associate the current case with another case, enabling you to reference and navigate between related cases easily. This field is essential for building relationships in your data model, such as linking a customer to their orders, a project to its tasks, or an employee to their manager.

YAML Definition 

- name: customer
  type: relation
  display_name: "Customer"
  guidance: "Select the customer associated with this order."
  required: true
  relation: "customer_case_type"
  uif: "customer_reference"

Attributes

  • name (string): Required.
    The unique identifier for the field.

  • type (string): Required.
    Must be set to relation for relation fields.

  • display_name (string): Optional.
    The label displayed in the user interface. If not provided, a formatted version of name is used.

  • guidance (string): Optional.
    Help text or instructions for the field, assisting users in selecting the correct related case.

  • required (boolean): Optional.
    If true, the field must be linked to another case before submission.

  • relation (string): Required.
    The code of the case type that this field should relate to. This defines the type of cases that can be linked.

  • uif (string): Optional.
    The name of an additional field to update when a case is linked or unlinked. Often used to store a reference or identifier from the related case.

  • lookup_defaults (object): Optional.
    Configures default search parameters to filter the available cases when selecting a relation. This helps narrow down the options presented to users.

    Properties:

    • lookup_field_name (string): The name of the field in the related case type to filter by.
    • type (string): The data type of the lookup field (e.g., string, number, boolean).
    • value (any): The value to filter for in the specified lookup field.

  • readonly (boolean): Optional.
    If true, the field is read-only, and users cannot modify the relation.

  • hidden (boolean): Optional.
    If true, the field is hidden from the user interface.

Example

Suppose you have an order case type and want to link each order to a customer case.

- name: customer
  type: relation
  display_name: "Customer"
  guidance: "Select the customer placing this order."
  required: true
  relation: "customer"
  uif: "customer_reference"

- name: customer_reference
  type: string
  display_name: "Customer Reference"
  readonly: true

In this example:

  • customer: The relation field that links an order to a customer case.
  • relation: Set to "customer", indicating the case type to relate to.
  • uif: Updates the customer_reference field with data from the linked customer case.
  • customer_reference: A read-only field that displays a reference or identifier from the related customer case.

Example with Lookup Defaults

Here’s an example showing how to use lookup_defaults to filter available options when selecting a relation:

- name: assigned_to
  type: relation
  uif: employee_ref
  relation: employee
  lookup_defaults:
    lookup_field_name: current_state
    type: string
    value: Active

In this example:

  • assigned_to: A relation field that links to an employee case.
  • lookup_defaults: Filters the available employees to only show those with current_state set to "Active".
  • lookup_field_name: Specifies that the filter should be applied to the current_state field in the employee case type.
  • type: Indicates that the current_state field is of type string.
  • value: Sets the filter value to "Active", so only employees with an active status will be shown in the selection list.

Usage Notes

  • User Interaction:

    • Users can search for and select a related case using an autocomplete or search dialog.
    • The field may display summary information about the linked case, such as the title or key attributes.
    • Options may include creating a new related case or clearing the existing link.

  • Relation Attribute:

    • The relation attribute must match the code of an existing case type.
    • This ensures that only cases of the specified type can be linked.

  • Updating Additional Fields (uif):

    • The uif attribute specifies a field to update with data from the related case.
    • Commonly used to store a reference number or key identifier from the linked case.
    • The field specified in uif should be defined separately in the schema.

  • Validation:

    • If the relation field is required, validation should ensure that a case is linked before submission.
    • Additional validation may check that the linked case meets certain criteria.

  • Readonly and Hidden Fields:

    • Setting readonly to true prevents users from changing the linked case.
    • Use hidden to include the relation in the data model without displaying it in the UI.

  • Guidance and Labels:

    • Use display_name to provide a clear label for the field.
    • Provide instructions using the guidance attribute to help users understand how to select the correct related case.

  • Use Cases:

    • Customer Orders: Linking orders to customer cases.
    • Project Management: Associating tasks with projects.
    • HR Systems: Linking employees to their managers or departments.
    • Issue Tracking: Connecting support tickets to related incidents or problems.

  • Searching and Selecting Related Cases:

    • The user interface may provide options to search for related cases by keywords or attributes.
    • Implement quick search functionality to help users find and select the correct case efficiently.

  • Navigation:

    • Once linked, users can often navigate directly to the related case from the current case view.
    • Ensure that users have appropriate permissions to view the linked cases.

  • Data Integrity:

    • Be cautious when deleting or modifying linked cases, as this may affect the integrity of the relation.
    • Implement checks or warnings if unlinking or deleting a related case could have significant implications.

  • Performance Considerations:

    • For cases with a large number of potential relations, optimize search functionality to handle large datasets.

  • Advanced Configuration:

    • Lookup Defaults: Configure default search parameters or filters to narrow down the cases presented to the user. Use the lookup_defaults attribute to specify a field name, type, and value to filter the available options. This is particularly useful when you want to show only relevant cases based on their current state or other criteria.
    • Display Fields: Define which fields from the related case are shown in the summary to provide meaningful context.

By incorporating the relation field type into your schema, you enable the creation of interconnected data models within Caseblocks, enhancing data organization, navigation, and overall functionality of your application.

Copyright © 2025 Caseblocks Limited.