Skip to main content

Integration Guide — Dynamic Charts

API Areas: report service (/gateway/dynamic-chart-reports) — persistence, configuration, and export; main API (/gateway/dynamic-chart-report) — paginated catalog and menu.
Authentication: Bearer Token (JWT) or API Key header X-API-KEY.

Authentication requirement

To successfully follow this guide using JWT authentication, use the following endpoint:

POST /gateway/auth/combined-login

Learn more…

Introduction​

This guide describes how to integrate with dynamic charts: saved configurations that associate a dynamic report (tabular data source and parameters @p_…) with visual definitions (series type, diagram, palette, axes, and legend).

There is no chart-specific SQL. The data source is always the dynamic report referenced by selectedDynamicReportGuid. At runtime, data is obtained with GET /gateway/dynamic-reports/{guid}/data?jsonParameters=…, as explained in the Dynamic Reports Guide.

This document is organized for step-by-step reading and tool reference: prerequisites and fields ↔ axes mapping, permissions, flows (creation, update, data retrieval), underlying report parameters, jsonParameters, visual enumerations, endpoint and DTO references, examples, and errors. See Document Map.

When to use​

  • Create or modify a chart linked to an existing dynamic report.
  • List charts (full list in the report service, paginated catalog or menu entries in the main API).
  • Get configuration (…/config) to build filters and know which report and fields to use on the axes.
  • Export the chart’s internal JSON (backup or diagnostics).

Document Map​

  1. Prerequisites — valid dynamic report and columns aligned with the chart; section Prerequisites.
  2. Fields and axes — argument, value, serieMember; section Mapping to report data.
  3. Permissions — permissionType, groups, user; section Permissions.
  4. Implementation flows — creation, update, data execution; section Implementation flows.
  5. Underlying report parameters — reuse of the dynamic report model; section Underlying report parameters.
  6. jsonParameters — query string format; section Query parameter jsonParameters.
  7. Visual types — series, diagrams, and numeric palettes; section Visual enumerations.
  8. Gateway prefixes — Two prefixes.
  9. Reference — Available endpoints, DTO structure, JSON examples, error handling, related resources.

Prerequisites: dynamic report​

Before creating a dynamic chart:

  1. Have a dynamic report created and saved (known GUID). The flow includes SQL validation, configuration of fields and parameters — see Dynamic Reports Guide.
  2. Confirm that the columns returned by the SQL (property name in each report field) cover the names you will use in argument, value, and, if applicable, serieMember in the chart definitions.
  3. Ensure permissions to read data from that report in the authenticated context (GET …/dynamic-reports/{guid}/config and GET …/dynamic-reports/{guid}/data).

If selectedDynamicReportGuid points to a non-existent or inaccessible report, write operations or GET …/config may fail on the server when resolving the underlying report.

Mapping to report data​

Property in settingsEntity / DynamicChartConfigRoleCorrespondence in the report
argumentCategory axis (e.g., X axis)name of a column in the report result (e.g., SQL alias).
valueMagnitude represented (e.g., Y axis)name of a typically numeric column.
serieMemberGrouping into multiple series (optional)name of a column that distinguishes series (text or categorization).

Names must match exactly the identifiers of the columns configured in the dynamic report (do not confuse with caption, which is for presentation only).

Underlying report change

If you change the SQL or the fields of the dynamic report, revalidate that argument, value, and serieMember still exist in the result; otherwise, the chart client may receive incomplete or empty data without explicit error at the chart layer.

Permissions​

The model of permissionType, permissionGroupsId, and userId follows the same pattern as dynamic reports (sharing concepts with GC):

permissionType valueUsual meaningNotes
0All usersNo restriction by user or group in the “chart” model.
1Current userAssociation to the authenticated user; userId may be managed by the server.
2GroupsFill permissionGroupsId with the IDs of authorized groups.

In PUT, the service may preserve the userId already stored on the server even if the client sends a different value — check behavior in your version and test with GET …/dynamic-chart-reports/{guid} after updating.

Implementation flows​

The recommended behavior follows two paths: creating a new chart and updating an existing one. In both, the referenced dynamic report must remain valid.

Runtime execution (getting data for the chart)​

To render the chart on the client, the data flow is a layer on top of the dynamic report:

StepDynamic report (tabular)Dynamic chart (visualization)
Identify resourceReport GUIDChart GUID
Configuration for screen (filters + metadata)GET /gateway/dynamic-reports/{guid}/configGET /gateway/dynamic-chart-reports/{chartGuid}/config (includes dynamicReportGuid and parameters of the underlying report)
Get rowsGET /gateway/dynamic-reports/{guid}/data?jsonParameters=…Same request, using the dynamicReportGuid returned in the chart’s config and the same jsonParameters
MappingColumns → tableEach row → argument, value, serieMember as per chart config

In other words: the chart does not replace the report’s data endpoint; it only indicates which report to use and how to map columns to the charting library.

Creating a new chart​

Flow diagram for first save:

  1. Choose selectedDynamicReportGuid and define settingsEntity (argument, value, serieMember, series type, diagram, palette, title, legends).
  2. Optional: validate columns with GET /gateway/dynamic-reports/{selectedDynamicReportGuid}/config on the report before saving the chart.
  3. POST /gateway/dynamic-chart-reports with empty (or omitted) guid as per client.
  4. On HTTP 200, the body contains the GUID of the created chart (text).
  5. Optional: GET …/{guid}/config to get parameters already prepared for the execution form.

Updating an existing chart​

To modify a saved chart, you need the chart’s guid and the current configuration or a coherent delta:

  1. GET /gateway/dynamic-chart-reports/{guid} — retrieves the persisted DynamicChartDataDTO (recommended before a PUT to avoid overwriting fields by omission).
  2. Adjust name, description, selectedDynamicReportGuid, permissions, or settingsEntity.
  3. PUT /gateway/dynamic-chart-reports with the correct guid in the body.
  4. Expected response: 204 No Content.

If you only have a list from the main API catalog:

Catalog versus full list

GET /gateway/dynamic-chart-report returns a paginated catalog (integration like a selection list in the main gateway). GET /gateway/dynamic-chart-reports (report service) returns all dynamic charts in a single array — useful for administrative tools; may be heavier in large installations.

Associated user on PUT

When updating, the backend may keep the userId already stored for the chart; do not assume the value sent in the body always replaces the persisted one without validating with a subsequent GET.

Underlying report parameters​

GET /gateway/dynamic-chart-reports/{guid}/config returns parameters as a collection of ReportParameterDetail: the same type of information the client uses to build filters before executing the dynamic report.

  • The keys in jsonParameters when calling GET /gateway/dynamic-reports/{dynamicReportGuid}/data must align with the paramHolder / markers @p_… of that report (see Parameters: configuration and visualization logic in the dynamic reports guide).
  • The control type on screen (ViewType, lists, Lookup, etc.) follows the same documented rules for dynamic reports; the chart only routes the user to fill the source report filters.

There is no dedicated “verify” operation for charts: changes to the SQL or report parameters are handled in the dynamic report flow (verify-sqlquery, etc.).

Query parameter jsonParameters​

To get the rows used in the chart, use GET /gateway/dynamic-reports/{dynamicReportGuid}/data with the optional query parameter jsonParameters: a JSON object serialized as text and URL-encoded, as in Standard Reports and the dynamic reports guide.

  • Keys: same as the report parameters’ names (@p_…).
  • Values: formatted according to type (date, number, text, etc.).
Important

Send jsonParameters as JSON text encoded in the query string. Common HTTP libraries handle serialization and URL encoding automatically.

Visual types (series, diagram, palette)​

In the API, selectedSeries, selectedDiagram, and selectedPalette are integers. The order of values corresponds to the server enumerations (also reflected in the OpenAPI schema of the report service).

DiagramType (values 0…5)​

ValueMember
0SimpleDiagram2D
1XYDiagram2D
2RadarDiagram2D
3PolarDiagram2D
4SimpleDiagram3D
5XYDiagram3D

PaletteName (values 0…8)​

ValueMember
0Chameleon
1DXCharts
2InAFog
3NatureColors
4NorthernLights
5Office
6PastelKit
7TerracottaPie
8TheTrees

SeriesType (values 0…29)​

ValueMemberValueMember
0Pie15OverlappedRangeBar
1Donut16Line
2Area17StackedLine
3StackedArea18FullStackedLine
4FullStackedArea19StepLine
5Bubble20ScatterLine
6Point21Stock
7StepArea22CandleStick
8RangeArea23ManhattanBar
9SideBySideBar24RadarArea
10SideBySideStackedBar25RadarLine
11SideBySideFullStackedBar26RadarPoint
12StackedBar27PolarArea
13FullStackedBar28PolarLine
14SideBySideRangeBar29PolarPoint

Some series types expect compatible diagram types in the visualization client (server code metadata Description associates series with diagram families). When in doubt, try in the product or consult the generated Swagger/OpenAPI schema.

Two prefixes in the gateway​

PrefixTypical origin in gatewayPurpose
/gateway/dynamic-chart-reportsReport serviceCRUD, /{guid}/config, /{guid}/export.
/gateway/dynamic-chart-reportMain APIGET paginated catalog; GET …/menu for menu entries.

Do not confuse dynamic-chart-report (singular, catalog/menu) with dynamic-chart-reports (plural, full resource in the report microservice).

Available endpoints​

Paginated catalog (main API)​

URL: /gateway/dynamic-chart-report
Method: GET
Query (optional): page, pageSize

Returns a paginated listing of dynamic charts in the main API model (EntityListingDTO). Useful to select a guid before GET /gateway/dynamic-chart-reports/{guid}.
See more →

Visible menu entries (main API)​

URL: /gateway/dynamic-chart-report/menu
Method: GET

List of charts marked to appear in the menu (integration with product ribbon/menu).
See more →

Operations under /gateway/dynamic-chart-reports​

All following requests use this prefix and require authentication.

List all charts (report service)​

URL: /gateway/dynamic-chart-reports
Method: GET

Response (200): array of DynamicChartDataDTO (complete list, no pagination in this resource).
See more →

Create dynamic chart​

URL: /gateway/dynamic-chart-reports
Method: POST
Body: DynamicChartDataDTO

Response (200): body with the created chart’s GUID (text).
See more →

Update dynamic chart​

URL: /gateway/dynamic-chart-reports
Method: PUT
Body: DynamicChartDataDTO (include guid)

Response: 204 No Content on success.
See more →

Get saved chart​

URL: /gateway/dynamic-chart-reports/{guid}
Method: GET

Response (200): complete DynamicChartDataDTO.
See more →

Delete dynamic chart​

URL: /gateway/dynamic-chart-reports/{guid}
Method: DELETE

Response: 204 No Content on success.
See more →

Get configuration for presentation​

URL: /gateway/dynamic-chart-reports/{guid}/config
Method: GET

Response (200): DynamicChartConfig — visual definitions, dynamicReportGuid, and parameters of the underlying report.
See more →

Export internal chart data​

URL: /gateway/dynamic-chart-reports/{guid}/export
Method: GET

Response (200): indented JSON string with the persisted internal state of the chart (useful for backup or diagnostics). Does not replace the GET …/dynamic-reports/…/data flow to feed the chart at runtime.
See more →

Main DTO structure​

Composition follows the model chart metadata + visual definitions + report reference. Numeric values of visual types are in Visual types.

DynamicChartDataDTO​

Body in POST / PUT and response in GET by GUID.

PropertyTypeRequired (typical creation)Description
guidstringUpdateEmpty or omitted on creation; required on PUT and routes with {guid} in path.
namestringYesShort name (max 25 characters).
descriptionstringYesDescription (max 250 characters).
addToRibbonbooleanNoExpose in product ribbon/menu when applicable.
selectedDynamicReportGuidstringYesGUID of the dynamic report data source.
permissionTypeintNoSee Permissions.
userIdint?NoPermission context; see note about PUT.
permissionGroupsIdint[]ConditionalRequired when permissionType indicates groups.
settingsEntityDynamicChartSettingsDTOYesFields mapping and visual options.

DynamicChartSettingsDTO​

PropertyTypeDescription
chartTitlestringChart title.
argumentstringData field (category axis).
valuestringData field (values).
serieMemberstringField for multiple series (optional).
selectedSeriesintSeriesType index.
selectedDiagramintDiagramType index.
selectedPaletteintPaletteName index.
animatebooleanAnimation.
showLegendbooleanMain legend.
showSeriesLegendbooleanSeries legend.

DynamicChartConfig​

Response of GET …/{guid}/config.

PropertyDescription
Mirrored definitionschartTitle, argument, value, serieMember, series, diagram, palette, animation, and legends (mirror of persisted).
dynamicReportGuidGUID of the report for GET …/dynamic-reports/{guid}/data.
parametersCollection of ReportParameterDetail to build the execution form.

JSON examples​

Creation body (POST /gateway/dynamic-chart-reports)​

{
  "guid": "",
  "name": "VendasMensais",
  "description": "Barras por mês e categoria",
  "addToRibbon": true,
  "selectedDynamicReportGuid": "fbdc2005-e157-4deb-9d49-a1a0557e4eef",
  "permissionType": 0,
  "userId": null,
  "permissionGroupsId": [],
  "settingsEntity": {
    "chartTitle": "Vendas por mês",
    "argument": "Mes",
    "value": "TotalVendas",
    "serieMember": "Categoria",
    "selectedSeries": 9,
    "selectedDiagram": 1,
    "selectedPalette": 4,
    "animate": true,
    "showLegend": true,
    "showSeriesLegend": true
  }
}

Mes, TotalVendas, and Categoria must correspond to name of columns in the referenced dynamic report. The integers for visual types must correspond to the tables in Visual types.

Update body (PUT /gateway/dynamic-chart-reports)​

Use the same DynamicChartDataDTO format, with guid filled with the identifier returned at creation. It is good practice to base the body on a prior GET and change only the desired fields.

Error handling​

Operations return Problem Details or errors aligned with the API standard when they fail (authentication, resource not found, persistence failure, invalid underlying report when building config, etc.).

The integration client should:

  1. Check the HTTP status code (4xx / 5xx).
  2. Read the body (title, detail, type) and correct the request, permissions, or data.

This guide does not fix internal numeric codes for localized messages: follow the returned text and the operation’s OpenAPI page.

Conclusion​

Integrating dynamic charts boils down to: (1) ensuring a suitable dynamic report; (2) saving the chart via POST /gateway/dynamic-chart-reports (or updating with PUT); (3) using GET …/{guid}/config to get dynamicReportGuid and parameters; (4) obtaining rows with GET /gateway/dynamic-reports/{guid}/data and jsonParameters, and mapping columns to argument / value / serieMember. For listings in the main gateway, use GET /gateway/dynamic-chart-report (pagination) or …/menu.

It is recommended to test changes to the underlying report, permissions, and series/diagram combinations in a quality environment before production.

Related resources​

Last updated: May 12, 2026