Status Field Type

Description:
The status field type is a specialized field used to represent and manage the current state of a case within its defined workflow. This field integrates with the case’s state machine and workflow transitions, allowing users to update the case’s status based on predefined statuses and transitions defined in the case type. It’s essential for controlling the progression of a case through its lifecycle, ensuring that business rules and processes are followed.

YAML Definition 

- name: current_state
  type: status
  display_name: "Current Status"
  guidance: "Update the current status of the case."
  required: true
  readonly: false

Attributes

  • name (string): Required.
    The unique identifier for the field, typically set to current_state to reflect the case’s status.

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

  • display_name (string): Optional.
    The label displayed to the user in the 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 status.

  • required (boolean): Optional.
    If true, the field must have a value before submission.

  • readonly (boolean): Optional.
    If true, the field is displayed as read-only and cannot be edited by the user.

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

Example

Suppose you have a case type for handling support tickets, and you want to allow users to update the status of a ticket.

- name: current_state
  type: status
  display_name: "Ticket Status"
  guidance: "Select the current status of the support ticket."
  required: true
  readonly: false

In this example:

  • current_state: Represents the current status of the support ticket.
  • type: Set to status, indicating that this field is tied to the case’s workflow.

Usage Notes

  • Integration with Workflow:

    • The status field is directly connected to the case type’s workflow and state machine.
    • The available statuses are derived from the statuses defined in the case type’s workflow configuration.

  • User Interaction:

    • Users can select a status from a dropdown list, which is populated based on the valid transitions from the current status.
    • The list of statuses is dynamic and respects the workflow rules, ensuring that users can only select valid next statuses.

  • Data Binding:

    • When a user selects a new status, the current_state field is updated with the name of the status.
    • Additionally, a current_state_id field may be updated with the unique identifier of the status.

  • Validation:

    • The field ensures that only valid status transitions are allowed, preventing users from moving cases to invalid states.
    • Validation rules are enforced based on the workflow definitions in the case type.

  • Readonly Fields:

    • Setting readonly to true is useful when the status should not be manually changed by users, perhaps because it’s managed automatically by the system or based on specific conditions.

  • Guidance and Labels:

    • Use display_name to provide a clear label for the field, making it intuitive for users.
    • The guidance attribute helps users understand any implications of changing the status.

  • Use Cases:

    • Support Tickets: Managing the lifecycle of a ticket through statuses like “New”, “In Progress”, “Resolved”, “Closed”.
    • Order Processing: Tracking an order through stages like “Received”, “Processing”, “Shipped”, “Delivered”.
    • Project Management: Updating project phases such as “Planning”, “Execution”, “Monitoring”, “Closure”.

  • Permissions and Access Control:

    • Implement role-based permissions to control who can change the status, especially for critical transitions.
    • Certain statuses might only be available to users with specific roles or permissions.

  • Status Transitions:

    • Define clear transitions in your case type’s workflow configuration to control how cases can move between statuses.
    • This ensures consistency and adherence to business processes.

  • Internationalization:

    • If your application supports multiple languages, ensure that status labels are localized accordingly.
    • Use internal status codes and map them to user-friendly labels in the appropriate language.

YAML Definition with Workflow Integration

Here’s how you might define the statuses and transitions within your case type’s workflow:

case_type:
  code: support_ticket
  statuses:
    - id: 1
      state: "New"
    - id: 2
      state: "In Progress"
    - id: 3
      state: "Resolved"
    - id: 4
      state: "Closed"
  transitions:
    - from: "New"
      to: ["In Progress", "Closed"]
    - from: "In Progress"
      to: ["Resolved", "Closed"]
    - from: "Resolved"
      to: ["Closed"]

In your field definition, the items for the dropdown are dynamically generated based on the valid transitions from the current status:

- name: current_state
  type: status
  display_name: "Ticket Status"
  required: true
  readonly: false

Technical Implementation Notes

  • Component Behavior:

    • The field component fetches the list of valid statuses from caseType.statuses.
    • It populates the dropdown with these statuses, allowing the user to select one.

  • Event Emission:

    • When a new status is selected, the component emits events to update both current_state and current_state_id.
    • This ensures that both the status name and its identifier are stored.

  • Computed Properties:

    • The items computed property generates the list of statuses.
    • The selection computed property handles getting and setting the selected status.

By integrating the status field type into your schema, you provide users with a seamless way to manage the lifecycle of cases according to your business workflows. It ensures that cases move through the defined processes correctly and that all status changes are valid and intentional.

Copyright © 2024 Caseblocks Limited.