Add `split_by_ticket` Node To Editor: A Step-by-Step Guide
Hey guys! Today, we're diving deep into adding a super cool feature to our node editor: the split_by_ticket functionality. This will allow us to edit the open ticket action directly within the node configuration. We'll walk through the process step by step, ensuring you understand how to implement this effectively. So, let's jump right in!
Understanding the Task
Our primary goal is to enhance the node editor by incorporating the split_by_ticket node type. This involves creating a node configuration that allows users to modify the open ticket action. To get a clear picture, we'll be referring to the sample-flow.json file, which contains examples of both the node type and the desired configuration. The open ticket action needs to be versatile, allowing users to select a topic and optionally assign an agent. These selections will be backed by dedicated endpoints. Additionally, we’ll be adding static files for selection within the flow demo environment, ensuring a seamless user experience.
Setting Up Static Files for Topics and Agents
To make this feature interactive and user-friendly, we need to set up static files that provide options for topics and agents. These files will serve as the data source for the selection menus in our node editor. Let's take a closer look at the structure and content of these static files. Setting up static files correctly is crucial for the functionality of the split_by_ticket feature, ensuring that users can easily select topics and agents when configuring the node.
Topics Static File
The topics static file will contain a list of available topics, each with its unique identifier, name, and associated counts. This allows users to categorize tickets and manage them efficiently. Here's an example of what the JSON structure might look like:
{
"next": null,
"previous": null,
"results": [
{
"uuid": "1b1cb507-e079-4b30-818c-1898edcbd178",
"name": "General",
"counts": {
"open": 2,
"closed": 12
},
"system": true,
"created_on": "2021-08-25T22:50:51.381947Z"
},
{
"uuid": "2b2cb507-e079-4b30-818c-1898edcbd179",
"name": "Support",
"counts": {
"open": 5,
"closed": 20
},
"system": true,
"created_on": "2021-09-25T22:50:51.381947Z"
}
]
}
In this example, we have a General topic with its UUID, name, and counts for open and closed tickets. The system field indicates whether it’s a system-defined topic, and created_on provides the timestamp. You should add more topics following this structure, ensuring they are similar in schema but unique in content. For instance, you might include topics like "Technical Support," "Billing Inquiries," or "Feature Requests.” The key here is to mirror the structure while providing relevant and diverse topic options for users. This structure is important because it will dictate how the data is displayed and used within the node editor, so make sure to get it right!
Agents Static File
The agents static file will list available agents, including their UUID, email, first name, last name, role, and team information. This allows users to assign tickets to specific agents, ensuring accountability and efficient task management. Here’s an example of the JSON structure:
{
"next": null,
"previous": null,
"results": [
{
"uuid": "c0f5b431-35e9-429c-9d57-5fee2fac46a3",
"email": "[email protected]",
"first_name": "Marion",
"last_name": "Berry",
"role": "agent",
"team": {
"uuid": "15236c1e-9375-4f84-bb48-ec64283d1eb9",
"name": "All Topics"
},
"created_on": "2023-04-05T21:11:31.909765Z",
"avatar": null
},
{
"uuid": "ae79dd5b-8c34-4602-a2c1-1e4db2419f0f",
"email": "[email protected]",
"first_name": "Eric",
"last_name": "Newcomer",
"role": "administrator",
"team": null,
"created_on": "2013-02-26T21:19:44Z",
"avatar": "https://dl-textit.s3.amazonaws.com/avatars/4/b6d756224c61435bb36b57ae03b83359.jpg"
},
{
"uuid": "bf89ef9c-6b34-430a-b712-c4647cf50f0e",
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"role": "agent",
"team": {
"uuid": "15236c1e-9375-4f84-bb48-ec64283d1eb9",
"name": "Support Team"
},
"created_on": "2023-05-15T10:22:17.123456Z",
"avatar": null
}
]
}
Here, we have two agents: Marion Berry and Eric Newcomer, each with their respective details. Notice how the structure includes fields for uuid, email, first_name, last_name, role, team, created_on, and avatar. When adding more agents, maintain this structure and populate it with relevant information. For example, you could add agents from different teams or with varying roles. Ensure the email addresses and names are realistic, and the team assignments make sense within your demo environment. Realism in these static files will make the demo environment more engaging and useful for testing the split_by_ticket functionality.
Implementing the split_by_ticket Node Configuration
Now that we have our static files ready, let's focus on implementing the split_by_ticket node configuration. This involves modifying the node editor to include the new node type and its associated properties. To do this effectively, we'll need to understand the existing node structure and how to integrate our new functionality seamlessly. The goal is to create a user-friendly interface where users can easily configure the open ticket action by selecting topics and assigning agents.
Understanding the Node Structure
Before diving into the implementation, it's crucial to understand the current node structure within our editor. This typically involves looking at how existing nodes are configured, what properties they have, and how they interact with the system. By examining nodes like call_webhook and call_llm, we can get a good sense of the best practices and patterns to follow. Consistency with existing node structures will make our new split_by_ticket node feel like a natural part of the editor.
Creating the Node Configuration
The split_by_ticket node configuration will primarily consist of two key elements: a topic selector and an agent assignment option. The topic selector should allow users to choose from the topics listed in our static file, while the agent assignment should let them optionally assign a ticket to a specific agent. This configuration needs to be intuitive and easy to use.
Topic Selector
The topic selector can be implemented as a dropdown menu or a searchable list. When the user interacts with this element, it should fetch the list of topics from our static file and display them. Each topic should be represented by its name, and selecting a topic should store its UUID for later use. To ensure a smooth user experience, consider adding a search functionality to the dropdown, especially if the list of topics is extensive. The search functionality will allow users to quickly find the topic they're looking for without having to scroll through a long list. This searchability is a key feature for usability.
Agent Assignment
The agent assignment option can be a similar dropdown or searchable list, but it should also include a “No Agent” or “Unassigned” option. This gives users the flexibility to leave the ticket unassigned if needed. Like the topic selector, this element should fetch the list of agents from our static file. When an agent is selected, their UUID should be stored. It’s also important to consider the visual design of this component. Make sure the options are clearly labeled and the overall layout is clean and intuitive. Clarity in the interface will help users understand the functionality at a glance.
Integrating with Endpoints
Once a user has configured the split_by_ticket node, the selected topic and agent (if any) need to be sent to the appropriate endpoints. This ensures that the ticket is correctly categorized and assigned in the system. We'll need to create or modify existing endpoints to handle this data. These endpoints should be designed to receive the topic UUID and agent UUID (or null if no agent is assigned) and perform the necessary actions to open the ticket with the specified parameters. Proper endpoint integration is essential for the split_by_ticket node to function correctly within the overall system.
Referencing Existing Examples
To guide our implementation, we can refer to existing examples like call_webhook.ts / split_by_webhook.ts and call_llm.ts / split_by_llm.ts. These examples will provide insights into how similar node types are structured and configured. By studying these files, we can understand the best practices for handling node properties, integrating with endpoints, and ensuring a consistent user experience. Drawing inspiration from these examples will help us create a robust and well-integrated split_by_ticket node.
Key Files and References
To successfully implement the split_by_ticket node configuration, there are several key files and references we need to keep in mind. These include the core logic for the open ticket action, the overall flow configuration, and the demo environment setup. Let's break down these references and understand their role in the implementation process. Knowing these references will guide us in the right direction and ensure we don’t miss any crucial steps.
Core Logic: flow/actions/open_ticket.ts
This file likely contains the core logic for the open ticket action. It will define how tickets are created, how topics and agents are assigned, and any other relevant business rules. Understanding the code in this file is crucial for ensuring that our node configuration correctly triggers the intended behavior. When modifying this file, it’s essential to consider the existing logic and make changes in a way that is consistent and maintainable. Consistency in code style and architecture is paramount for long-term maintainability.
Flow Configuration: flow/config.ts
The flow/config.ts file probably defines the overall flow configuration, including the available node types and their properties. We'll need to modify this file to include our new split_by_ticket node type and its configuration schema. This will involve defining the properties that users can configure, such as the topic and agent selectors. The configuration schema should be well-defined and validated to prevent errors and ensure that the node behaves as expected. A well-defined schema will help catch configuration errors early in the development process.
Demo Environment: demo/data/sample-flow.json
The sample-flow.json file provides examples of flow configurations, which can serve as a guide for implementing our node. By examining how existing nodes are configured in this file, we can learn how to structure our split_by_ticket node configuration. This file is also a valuable resource for testing our implementation. We can add our new node to the sample flow and ensure that it functions correctly within the demo environment. Testing within the demo environment will give us confidence that our changes are working as expected.
Modeling After Previous Versions
To further guide our implementation, we can look at previous versions of similar features. The image provided gives us a visual reference for how the agent assignment component might look. By modeling our implementation after this design, we can ensure a consistent and user-friendly experience. It's important to understand the rationale behind the design choices in the previous version. Why were certain elements placed in specific locations? Why was a particular control chosen for agent selection? By understanding these decisions, we can make informed choices in our own implementation. The goal is to iterate on previous designs, improving them where possible while maintaining a cohesive user experience.
Conclusion
Alright guys, we've covered a lot in this guide! We've walked through the process of adding the split_by_ticket functionality to our node editor, from setting up static files to implementing the node configuration and integrating with endpoints. By following these steps and referencing the key files and examples, you'll be well-equipped to tackle this task. Remember, the key is to understand the existing structure, maintain consistency, and create a user-friendly experience. Happy coding!