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 torelation
for relation fields. -
display_name (string): Optional.
The label displayed in the user interface. If not provided, a formatted version ofname
is used. -
guidance (string): Optional.
Help text or instructions for the field, assisting users in selecting the correct related case. -
required (boolean): Optional.
Iftrue
, 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.
Iftrue
, the field is read-only, and users cannot modify the relation. -
hidden (boolean): Optional.
Iftrue
, 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 typestring
. - 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 thecode
of an existing case type. - This ensures that only cases of the specified type can be linked.
- The
-
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.
- The
-
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.
- If the relation field is
-
Readonly and Hidden Fields:
- Setting
readonly
totrue
prevents users from changing the linked case. - Use
hidden
to include the relation in the data model without displaying it in the UI.
- Setting
-
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
-
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.
- Lookup Defaults: Configure default search parameters or filters to narrow down the cases presented to the user. Use the
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.