Fractal Forge icon

Fractal Forge

Retrieve data from FractalForge API

Actions9

Overview

This node integrates with the FractalForge API to retrieve or manipulate data related to entity collections and objects within those collections. Specifically, for the Query resource with the Custom (Collection) operation, it allows users to execute custom queries on a specified entity collection. This is useful when predefined query operations do not cover specific data retrieval needs, enabling flexible querying of collections by specifying custom query names.

Practical scenarios include:

  • Fetching filtered or aggregated data from a particular collection using a custom query defined in FractalForge.
  • Running specialized reports or data extractions that are implemented as custom queries on the server side.
  • Extending standard data retrieval capabilities without modifying the node code, by leveraging custom queries configured in FractalForge.

Properties

Name Meaning
Entity Collection Name or ID (collection) Selects the target entity collection either by choosing from a loaded list or specifying an ID via expression.
Custom Query (customQuery) The name of the custom query to execute on the selected collection. This identifies which custom query logic to run.

Output

The node outputs JSON data representing the results returned by the FractalForge API for the executed custom query on the collection. The output structure depends on the specific custom query but generally consists of an array of objects corresponding to the queried data entries.

No binary data output is produced by this operation.

Dependencies

  • Requires an API key credential for authenticating requests to the FractalForge API.
  • Needs the API endpoint URL configured in the credentials.
  • The node uses HTTP requests to communicate with the FractalForge API.
  • The Entity Collection Name or ID options are dynamically loaded from the API endpoint /system/commands-events-per-entity.

Troubleshooting

  • Common issues:

    • Invalid or missing API key or endpoint configuration will cause authentication failures.
    • Specifying a non-existent collection or custom query name will result in API errors.
    • Network connectivity problems can prevent successful API calls.

  • Error messages:

    • "The operation \"custom_collection_query\" is not known!": Indicates an unsupported operation was selected; ensure the correct operation is chosen.
    • API errors wrapped as NodeApiError typically indicate issues returned from the FractalForge API such as invalid parameters or authorization failures.

  • Resolutions:

    • Verify API credentials and endpoint correctness.
    • Confirm the collection and custom query names exist and are spelled correctly.
    • Check network access and proxy settings if applicable.
    • Use the "Continue On Fail" option to handle individual item errors gracefully during batch executions.

Links and References

Discussion