Data plugins
Data plugins post-process result data after an API finishes executing and before the response is returned. They do not change the SQL or the API logic, only "what is returned". Common uses: masking sensitive fields, renaming fields, converting codes into text, turning lists into trees, and picking a single record from multiple results.
Entry point
Click "Data plugins" on the right side of the workbench in any development mode. Plugins are organized into three groups:
| Category | Plugins |
|---|---|
| Data processing | Filter and clean, value formatting, value replacement, field merge |
| Data mapping | Field renaming, dictionary conversion |
| Result transformation | Tree structure, multi-level nesting, single object |
Each plugin has its own switch; the configuration takes effect only after the plugin is enabled. Click "Save configuration" to write it into the API definition, then you still need to save and release the API.
Only one of tree structure, multi-level nesting and single object can be enabled. Switching prompts you to disable the currently enabled plugin.
Execution order
When multiple plugins are enabled at the same time, they execute in a fixed order:
| Order | Plugin |
|---|---|
| 1 | Field renaming (fieldMapping) |
| 2 | Filter and clean (dataProcess) |
| 3 | Dictionary conversion (dictTransform) |
| 4 | Value formatting (fieldFormat) |
| 5 | Value replacement (fieldReplace) |
| 6 | Field merge (dataMerge) |
| 7 | Tree structure (treeTransform) |
| 8 | Single object (singleObject) |
| 9 | Multi-level nesting (nestedStructure) |
This means later plugins see the field names and values produced by earlier ones, so design configurations according to the actual order.
Filter and clean
Runs rules against the result list; multiple rules can be added and run in the order they were added:
| Rule type | Configuration | Description |
|---|---|---|
| Data filter | Field, operator, value | Keep only records that satisfy the condition |
| Data sort | Field, ascending/descending | Sort by field |
| Data masking | Fields (multiple allowed), masking type | Mask field values |
| Field calculation | Source field, operator, operand, new field name | Compute or concatenate and write into a new field |
Operators: equals, not equals, greater than, less than, greater than or equal to, less than or equal to, contains, not contains, is empty, is not empty. Calculation operators: +, -, *, /, concat.
Masking types:
| Type | Applies to |
|---|---|
| Generic masking | Any string |
| Phone number | Mobile phone numbers |
| ID card number | ID cards |
| Email addresses | |
| Bank card | Card numbers |
| Name | Personal names |
| Address | Address text |
For calculation rules, the "new field name" can be the same as the old field to overwrite the original value.
Field renaming
Maps source fields to new field names:
| Configuration | Description |
|---|---|
| Source field | Selected from the current response parameter tree |
| Target field | New field name |
| Default value | Fallback when the source field is empty |
| Delete source field | When checked, the original field is removed once the mapping completes |
Multiple mappings run in list order. If target field names duplicate, later mappings overwrite earlier values.
Dictionary conversion
Converts coded values into readable text:
- Select the source field and target field (if the target is left empty, the source field is overwritten).
- Maintain "original value → display value" mappings one by one.
- The default value is used when no mapping matches.
- If "Keep original field" is checked, the source field is preserved; otherwise it is replaced with the converted result.
Suitable for status codes, type codes, region codes and similar cases.
Value formatting
| Format | Description | Example template |
|---|---|---|
| Date and time | Formats dates by template | yyyy-MM-dd HH:mm:ss |
| Amount | Amount with thousands separators | #,##0.00 |
| Percentage | Percentage display | As prompted on the page |
| Number | Number format | #,##0.00 |
| To uppercase | Uppercase string | — |
| To lowercase | Lowercase string | — |
| Trim spaces | Removes leading and trailing spaces | — |
Dates, amounts and numbers require a format template.
Value replacement
Replaces field values by condition:
| Match type | Description |
|---|---|
| Equals | The value is exactly equal |
| Contains | Contains the target text |
| Starts with | Begins with the target text |
| Ends with | Ends with the target text |
| Regex match | Matches the regular expression |
| Replace when empty | The field is null |
| Replace when empty string | The field is an empty string |
When a rule matches, the replacement value is written. Useful for turning null into - consistently, converting abnormal values into fixed text, and similar cases.
Field merge
Concatenates multiple fields into a new field:
- Select multiple source fields.
- Set the target field name.
- Optionally set a separator (such as
-or a space). - Optionally delete the source fields after merging.
Source fields are concatenated in selection order, and empty values are treated as empty strings.
Tree structure
Converts a flat parent-child list into a tree:
| Configuration | Description |
|---|---|
| Node ID field | Unique identifier field |
| Parent node ID field | Points to the parent node ID |
| Child node field name | Field name that holds children; defaults to children |
| Root node ID | The value used as the root starting point; if left empty, nodes whose parent ID is missing or self-referencing are treated as roots |
Suitable for hierarchical data such as menus, departments and regions. Cycles in the data may cause nodes to be lost, so make sure parent-child relationships are valid before configuring.
Multi-level nesting
Collapses a list into multiple levels of children by one or more grouping fields:
- For each level, configure the grouping field, the children field name, the label field and the display field.
- Levels are nested in configuration order.
- Optionally keep the original fields of leaf nodes; if not kept, only the specified leaf display fields are output.
Difference from tree structure: tree restores hierarchy from parent-child IDs, while multi-level nesting regroups records by grouping fields.
Single object
Converts a result set into a single object:
| Mode | Description |
|---|---|
| First record | Returns the first record of the list directly |
| Conditional match | Filters by field, operator and target value, then returns the first record |
Returns null when the result set is empty. Suitable for APIs such as "detail queries" that should return a single record.
Field paths and nested results
Plugin fields come from the "Response parameters" tree and support full paths such as data.user.phone. The platform locates the actual list or object, runs the plugin at that level and then writes the result back into the original response structure. So when masking or mapping fields inside nested objects, simply select the full path.
Failures and troubleshooting
- If a plugin throws internally, the platform logs the error and returns the unprocessed original data rather than failing the API. Always verify results with a test or a real call after configuring.
- Plugins process only the data part of the execution result; wrapper fields such as pagination and total counts are maintained by the platform.
- After you change response parameters, previously selected fields in plugins may become invalid and must be reselected.
- Plugin configuration is stored in the API definition and takes effect with version releases and migrations.
FAQ
| Symptom | Cause | Resolution |
|---|---|---|
| The plugin does not take effect | The switch is off or the configuration was not saved | Turn on the switch, save the configuration, then save the API |
| A masked field disappears | Field renaming or replacement is also enabled | Check the execution order and field names |
| Dictionary conversion does not match | The original value type or letter case differs | Configure mappings for the actual values or set a default value |
| The list is not converted into a tree | Parent-child fields are misconfigured or the data contains cycles | Verify the ID and parent ID, and clean up invalid data |
| The single object returns null | No condition matches or the result is empty | Check the filter conditions |
| Enabling a second result transformation plugin is blocked | Result transformation plugins are mutually exclusive | Disable the current plugin before enabling another |