Data Source Field

The Data Source field is a non-visual field that gathers a set of data one time and shares it with one or more visual fields on the form — charts, calendars and other "consumer" fields. It separates the job of getting the data from the job of displaying it. Instead of every chart or calendar carrying its own data expression, you create a single Data Source, point it at your data, and then bind as many display fields to it as you like. Another benefit to the Data Source field is that it loads the data client side so the initial loading of the form does not wait for its data call.


Because the Data Source itself draws nothing on the screen, it appears in the designer as a labeled placeholder and is invisible to the end user when the form is run. Its only purpose is to fetch data and hand it to the fields that are bound to it.


Tip: One Data Source can feed many fields at once. For example, a single Data Source that returns a list of invoices can drive a bar chart, a calendar and a table on the same dashboard — all showing the same rows, gathered only once.




How It Works


A Data Source has a single, central setting — the Data Expression. This is the recipe that tells the server how to gather the data. When the form is opened, the server runs the expression, gathers the data and stores the result on the Data Source field. Any consumer fields that are bound to the Data Source then read that result and display it.


The data is gathered in these situations:

    • On form load — the server resolves the expression and delivers the data with the form, so the form opens with the data already in place.
    • When a referenced field changes — if your expression refers to other fields on the form using {FieldName} syntax, the Data Source automatically re-gathers the data whenever one of those fields changes. This lets a chart or calendar react live to a date range, a selected vendor, and so on.
    • On demand — you can force a refresh at any time from a button or Multi-Action (see Commands below).



The Data Expression


The Data Expression supports the same server variables used elsewhere in DocMgt — the "DMGET" family of variables, SQL and REST lookups, and so on. Some common choices:


[DMGET2(...)] — searches your records and returns them as JSON rows. This is the most flexible choice and is recommended for charts. It returns an array of objects with named columns.


[DMGETEVENTS(...)] — searches your records and returns them formatted for calendars (date, description and id for each event).


[SQLGET(...)] / [RESTGET(...)] — pull data from a SQL query or a REST/internet call.


You can mix in field references with {FieldName} so the data responds to what the user enters. For example, the following gathers invoices for the vendor the user has selected and re-runs whenever that selection changes:


[DMGET2(12|0|Vendor={VendorName}|InvoiceDate^Vendor^Amount)]


Note: Server variables in square brackets — such as [DMGET2] — are always resolved on the server. The {FieldName} references are filled in first, then the completed expression is sent to the server to gather the data.




Data Format


The Data Source does not care what the data looks like — it simply holds whatever the expression produced and hands it to the consumers. The consumer fields are responsible for interpreting it. There are two common shapes:


JSON rows (recommended) — an array of objects with named columns. This is what [DMGET2] returns and is the easiest to work with, because consumers can map columns to roles by name. Example:

[{"InvoiceDate":"6/1/2025","Vendor":"ACME","Amount":"$1,200.00"}, ... ]


Delimited text — a pre-shaped string that a particular consumer understands. For example, [DMGETEVENTS] returns a calendar-shaped string of date^description^^id separated by semicolons, and a chart can accept a label^value^grouping string. These are positional — no column mapping is needed.




Connecting Consumer Fields


Consumer fields are the visual fields that display Data Source data. To connect one, edit the consumer field and choose the Data Source from its Data Source setting, then (for JSON data) map the columns to the field's roles. Fields that can consume a Data Source include:


  • Data Source Chart — a bar, line, pie, doughnut or stacked chart. Map columns to Label, Value and (optionally) Grouping, and choose how to aggregate and bucket the data.
  • Calendars (Month, Week, Day, Agenda) — bind a Data Source to populate calendar events instead of (or in addition to) the manual Events list. Map columns to Date, Description and ID, or feed it a [DMGETEVENTS] expression directly.


Tip: A consumer keeps its own original data option for backward compatibility. Binding a Data Source is an added option — leave it unset to keep using the field's built-in expression.



Using the Data Elsewhere


You can also read a Data Source's data from other fields and actions using the field's name:


{SourceName} — returns the whole data set (as JSON text when the data is structured).


{PROP(SourceName,Column)} — extracts a single property/column value from the data.


When you send a Data Source into an Action Set, the gathered data travels with it — useful for processing the same rows on the server.



Commands


You can control a Data Source by setting its value — typically from a button or Multi-Action using a Set Field Value action. The Data Source watches its value for these special commands:


REFRESH — re-runs the Data Expression and re-gathers the data. All bound consumers update.


CLEAR — empties the data.


Any other value set on the field is treated as data being pushed directly into the Data Source — for example, an Action Set can return rows and place them into the Data Source by name, bypassing the Data Expression entirely.




Settings


Field Name — the name used to refer to this Data Source, both when binding consumers and when reading its data with {Name} / {PROP(Name,Column)}.


Data Expression — the expression used to gather the data (for example a [DMGET2] or [DMGETEVENTS] call). May include {FieldName} references that make the data react to other fields.


Please Wait Message — the message shown in the global Please Wait dialog while the Data Source is gathering data from the server. Supports variables. Defaults to "Loading data..."; leave it blank to show no message. When several Data Sources load at once, the dialog stays open until the last one finishes.




Example: A Spend-by-Vendor Dashboard


1. Add a Data Source field named "Invoices" and set its Data Expression to return your invoice rows as JSON:

[DMGET2(12|0||InvoiceDate^Vendor^Amount)]


2. Add a Bar Chart, bind it to "Invoices", set the Label column to Vendor, the Value column to Amount, and aggregation to Sum. You now have spend-by-vendor.


3. Add a Calendar, bind it to the same "Invoices" Data Source, and map the Date column to InvoiceDate and the Description column to Vendor. The same rows now also appear as calendar events.


4. (Optional) Add a button with a Set Field Value action that sets "Invoices" to REFRESH so users can re-pull the data on demand.


The data is gathered once by the Data Source and shared by both the chart and the calendar — and a single REFRESH updates them together.