Skip to main content

Integration Edit Property Dialog

Overview​

Custome Integrations are composed of two dialogs, the Edit Property dialog and Edit Integration dialog. The Property dialog settings will control what UX exist on the Edit Integration dialog.

The Edit Property dialog is used to define or modify the core attributes and behaviors of a custom Integration. By specifying a unique name, descriptive purpose, data retrieval methods, response handling, and optional post-processing logic, you can create an Integration that seamlessly integrates with your data sources and delivers meaningful results.

The Edit Property dialog is used to define or modify the core attributes and behaviors of a custom Integration. By specifying a unique name, descriptive purpose, data retrieval methods, response handling, and optional post-processing logic, you can create an Integration that seamlessly integrates with your data sources and delivers meaningful results. fields are Name, Description, Data Source, Handle Response, Custom Function

Fields and Descriptions​

  1. Name

    • Purpose: Assign a unique, descriptive identifier to your Integration.
    • Guidance:
      Choose a name that clearly reflects the Integration’s role or function to ensure easy identification by both team members and the LLM reasoning engine.

  2. Description

    • Purpose: Provide a concise explanation of the Integration’s purpose and functionality. Limit to 1000 characters
    • Guidance:
      Focus on the Integration’s primary role and the type of data or tasks it handles. This helps the Language Learning Model (LLM) invoke the Integration at the appropriate times and scenarios.

  3. Data Source

    • Purpose: Specify the type of API from which the Integration will receive its data.
    • Options:
      • None: The Integration does not fetch any external data. Example you want the Integration to be a Template (HTML) i.e. a widget that needs no data, like an iFrame or Calculator
      • GraphQL: Data is retrieved from a GraphQL API.
      • REST API: Data is retrieved from a RESTful API.
      • Model Context Protocol (MCP): Data is retrieved from a MCP API.
    • Guidance:
      Select the data source that best matches the service you request date to. If your Integration needs dynamic, real-time information, use REST or GraphQL. If it doesn’t require external data, select None. Example would be a Template (HTML widget)

  4. Handle Response

    • Purpose: Determine how the Integration’s returned JSON data to.

    • Options:

      • LLM to process data (Default): The JSON is returned to the Reasoning Engine LLM for processing.
      • Carousel: JSON is passed directly to the client to render as a visual carousel or list.
      • Template (HTML): JSON and LLM-generated data are injected into a custom HTML template for rich, formatted output. Example a Google Chart.
      • Form: Dynamically creates a form, leveraging the ai12z form control for user input or data processing.

    • Process (Optional; controlled by the endpoint) When the Handle Resonse is set to carousel. The data source can override the Handle Response property by setting the process field in the returned object to carousel, llm, or both. For example, if you’re interacting with a ticketing system and only one event is returned, you might set process to both so the LLM can provide additional context while the event also appears in the carousel. If your request returns zero results, set process to llm so the LLM can display a helpful message instead of simply “No results.” And if you have many results, you can bypass the LLM entirely by setting process to carousel and sending the data straight to the client’s carousel.

    • Guidance:
      Choose the format that best suits your application’s user experience.

  5. Custom Function (Python)

    • Purpose: Optionally apply Python code to further refine or manipulate the JSON or GraphQL response data. This is An optional final processing step where Python code can modify or process the JSON data before returning results to the LLM, HTML widget or to the client, depending on how Handle Response is configured.
    • Guidance:
      Best practice it is often easier to use JSONata, but there are some cases Python might be a better fit. GraphQL, usually it filters the results and typically do not need JSONata or Python.

After updating this dialog, click the Next to go to the Edit Integration dialog

Best Practices​

  • Be Descriptive, Yet Concise:
    Use the Name and Description fields to clearly convey the Integration’s purpose. A well-defined name and description help ensure the LLM leverages the Integration effectively.
  • Select the Right Data Source:
    Align the Data Source with your backend infrastructure. GraphQL and REST are ideal for real-time data retrieval and updating.
  • Tailor the Response Handling:
    Think about how end-users will interact with the returned data. For direct, processed answers, stick to LLM processing. For visually rich or interactive experiences, leverage Carousel, Template HTML. Use a Form if you need to collect data, but you can also uset a Template HTML widget to collect data
  • Leverage the Custom Function Wisely:
    If your use case demands additional logic beyond the standard flows, take advantage of the Custom Function to clean, transform, or enhance the data before it’s rendered.

Conclusion​

The Edit Property dialog provides a flexible, customizable framework for defining how your custom Integration will behave within the ai12z platform. By thoughtfully configuring each field—Name, Description, Data Source, Handle Response, and Custom Function—you ensure your Integration not only gathers the right data but also presents it in the most engaging and contextually relevant form for your users.