@isoftdata/utility-dashboard-backend 1.0.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/README.md

@@ -0,0 +1,133 @@
+# utility-dashboard-backend
+ A backend utility for formatting and loading dashboard chart and report data to be usable by the [frontend dashboard component](https://github.com/ISoft-Data-Systems/ractive-component-web-dashboard).
+
+## Prerequisites
+
+* A MySQL database schema as outlined in [schema.md](schema.md)
+* A backend that can fetches rows from the chart, report, and report chart tables from the database with their primary keys. Any json columns should be parsed as objects.
+* A connection or pool of connections from the `mysql` NPM module for running the charts' queries
+* The [dashboard Ractive component](https://github.com/ISoft-Data-Systems/ractive-component-web-dashboard) on the client
+
+## API
+
+### formatReportMetadata
+
+This function returns data in the format expected for the `loadReportMetadata` function on the dashboard client component.
+
+#### Function signature:
+
+```js
+async formatReportMetadata(mysqlConnection, { report, chartsInReport })
+```
+
+#### Example Usage (From Pro Web `server/chart-loader.js`):
+
+```js
+async function loadReportMetadata({ dashboardReportId, chartId }) {
+	const report = await db.dashboardReport.loadById({ dashboardReportId }) // gets a report by its id
+	const chartsInReport = await db.dashboardChart.loadByReport({ dashboardReportId, chartId }) // gets all charts for a specified report, or if `chartId` is specified, only gets that chart for that report.
+	return await formatReportMetadata(db.pool, { report, chartsInReport })
+}
+```
+
+#### mysqlConnection
+A connection or pool of connections from the `mysql` npm module.
+
+#### report
+
+A report `object`, a single row from the `dashboard_report`/`wa_dashboard_report` table/view. The `parameters` Array from the `json` column should also be parsed from JSON and appended to this object.
+
+Example:
+
+```js
+{
+  dashboardReportId: 1,
+  reportName: 'report_overview',
+  reportTitle: 'Overview',
+  shareType: 'everyone',
+  shareId: null,
+  ownerId: null,
+  parameters: [ // parameters deconstructed from `json` column after parsing
+    {
+      name: 'date_range',
+      type: 'dateRange',
+      title: 'Date Range',
+      default: 'This Year'
+    }
+  ]
+}
+```
+
+#### chartsInReport
+
+An `Array` of chart `object`s, one for each chart in the report, multiple rows from the `dashboard_chart`/`wa_dashboard_chart` table/view joined with `dashboard_report_chart`/`wa_dashboard_report_chart` to get the chart's rank.
+
+Example:
+
+```js
+[
+  {
+    chartId: 10,
+    name: 'line_sales_over_time_and_previous_period',
+    title: 'Sales over Time',
+    supertype: 'google',
+    formatting: { Sales: [Object] },
+    multiSeries: {
+      value: 'Sales',
+      series: 'Period',
+      tooltip: 'Tooltip',
+      groupXAxisBy: 'Date'
+    },
+    chartWrapper: { options: [Object], chartType: 'LineChart' },
+    rank: 1
+  },
+  {
+    chartId: 16,
+    name: 'map_sales_by_lat_long',
+    title: 'Sales Map',
+    supertype: 'google',
+    formatting: { Sales: [Object] },
+    chartWrapper: { options: [Object], chartType: 'GeoChart' },
+    rank: 2
+  }
+]
+```
+
+### formatChartDataForReport
+
+This function returns data in the format expected for the `loadChartDataForReport` function on the dashboard client component, including applying any report-specific chart options overrides and running the chart's query.
+
+#### Function signature
+
+```js
+async formatChartDataForReport(mysqlConnection, { reportParameters, chart, reportChart, parameterSelectionList })
+```
+
+#### Example usage: (from Pro Web `server/chart-loader.js`)
+
+```js
+async function loadChartDataForReport ({ dashboardReportId, chartId, parameterSelectionList }) {
+	const report = await db.dashboardReport.loadById({ dashboardReportId }) // get the report object
+	const chart = await db.dashboardChart.loadById({ chartId }) // get the chart object
+	const reportChart = await db.dashboardReportChart.loadByReportAndChartId({ chartId, dashboardReportId }) // get the report chart for the rank/overrides
+	try {
+		const chartData = await formatChartDataForReport(db.pool, { reportParameters: report.parameters, chart, reportChart, parameterSelectionList })
+		return chartData
+	} catch (err) {
+		console.error(err)
+		return { isErrored: true }
+	}
+}
+```
+
+#### mysqlConnection
+A connection or pool of connections from the `mysql` npm module.
+
+#### reportParameters
+The `parameters` array from a report object.
+
+#### chartId
+The id of a chart row in `wa_dashboard_chart`.
+
+#### parameterSelectionList
+The array of selected parameters sent from the client dashboard.

package/chart-helper.js

@@ -0,0 +1,254 @@
+const { formatterTemplates } = require('./formatter-templates.json')
+const toSnakeCase = require('to-snake-case')
+const mysqlDataTypes = require('mysql/lib/protocol/constants/types')
+const klona = require('klona')
+
+const mysqlToGoogleChartsDataTypeMap = mysqlDataType => {
+	switch (mysqlDataType) {
+		case 'VAR_STRING':
+		case 'STRING':
+		case 'ENUM':
+		case 'VARCHAR':
+			return 'string'
+		case 'DECIMAL':
+		case 'NEWDECIMAL':
+		case 'BIT':
+		case 'TINY':
+		case 'SHORT':
+		case 'LONG':
+		case 'FLOAT':
+		case 'DOUBLE':
+		case 'LONGLONG':
+		case 'INT24':
+		case 'YEAR':
+			return 'number'
+		case 'TIMESTAMP':
+		case 'DATETIME':
+		case 'TIMESTAMP2':
+		case 'DATETIME2':
+			return 'datetime'
+		case 'DATE':
+		case 'NEWDATE':
+			return 'date'
+		case 'TIME':
+		case 'TIME2':
+			return 'timeofday'
+		default:
+			return 'string'
+	}
+}
+
+const makeDataTableCol = (key, fields, role = null) => {
+	return {
+		id: toSnakeCase(key).toLowerCase(),
+		label: key,
+		type: mysqlToGoogleChartsDataTypeMap(fields[key]),
+		role,
+	}
+}
+
+module.exports = {
+	queryWithFields: (connection, query) => { // the only function here that talks to the server at all
+		return new Promise((resolve, reject) => {
+			connection.query(query, (err, results, fields) => {
+				if (err) {
+					reject(err)
+				} else {
+					resolve({
+						results,
+						fields: fields.reduce((sum, field) => {
+							return {
+								...sum,
+								[field.name]: mysqlDataTypes[field.type] || field.type,
+							}
+						}, {}),
+					})
+				}
+			})
+		})
+	},
+	getMultiSeriesData: ({ data: queryResult, seriesOptions, formatting, fields }) => {
+		const { groupXAxisBy, series, value, tooltip } = seriesOptions
+		//Get an array of all of the keys for the series
+		const allOfTheKeysInTheSeries = new Set(queryResult.map(row => row[series]))
+
+		let objectOfAllKeysWithNullValues = {}
+		for (const key of allOfTheKeysInTheSeries) {
+			objectOfAllKeysWithNullValues[key] = null
+			//add in a spot for the tooltips for each column to go
+			if (tooltip) {
+				objectOfAllKeysWithNullValues[`${tooltip} ${key}`] = null
+			}
+		}
+
+		let grouped = {}
+
+		//create objects for each thing they're grouping by
+		// console.time(`create objects for each thing they're grouping by`)
+		for (const row of queryResult) {
+			//if we don't yet have a prop for what we're grouping by, then we need to initialize an object of all null values for it
+			if (!grouped[row[groupXAxisBy]]) {
+				grouped[row[groupXAxisBy]] = klona(objectOfAllKeysWithNullValues) //give nulls for all values by default
+			}
+
+			grouped[row[groupXAxisBy]][row[series]] = row[value]
+			// add the tooltips for each series in each row
+			if (tooltip) {
+				grouped[row[groupXAxisBy]][`${tooltip} ${row[series]}`] = row[tooltip]
+			}
+		}
+		// console.timeEnd(`create objects for each thing they're grouping by`)
+
+		//The mysql field types need to map to our output data
+		let seriesFields = { [groupXAxisBy]: fields[groupXAxisBy] }
+		let seriesFormatting = {}
+		for (const key of allOfTheKeysInTheSeries) {
+			seriesFields[key] = fields[value]
+			//add tooltips here, so a tooltip column is created for every series column
+			if (tooltip) {
+				seriesFields[`${tooltip} ${key}`] = fields[tooltip]
+			}
+			//If there is any formatting applied to the value, we need to apply it to all of the other keys
+			if (formatting && value in formatting) {
+				seriesFormatting[key] = formatting[value]
+			}
+		}
+
+		//turn it back to an array and make sure the grouping column is first as required by a pie chart(at least)
+		// console.time(`group it back together`)
+		let multiSeriesData = []
+		for (const key in grouped) {
+			multiSeriesData.push({
+				[groupXAxisBy]: key,
+				...grouped[key],
+			})
+		}
+		// console.timeEnd(`group it back together`)
+		// console.log(`${multiSeriesData.length} rows with ${Object.keys(multiSeriesData[0]).length} props each.`)
+		return {
+			data: multiSeriesData,
+			formatting: {
+				...formatting,
+				...seriesFormatting,
+			},
+			fields: seriesFields,
+		}
+	},
+	makeNegativeNumbericValuesZero: resultSet => {
+		const numberCols = Object.keys(resultSet[0]).filter(key => typeof resultSet[0][key] === 'number')
+
+		return resultSet.map(row => {
+			numberCols.forEach(col => {
+				if (row[col] < 0) {
+					row[col] = 0
+				}
+			})
+
+			return row
+		})
+	},
+	coerceNullColumn: (columnProp, data, destinationType) => {
+		const hasNullValue = data.find(row => row[columnProp] === null)
+
+		if (hasNullValue) {
+			const rowWithValidValue = data.find(row => row[columnProp] !== null)
+			let nullReplacement = ''
+
+			if ((destinationType && destinationType === 'number') || (typeof rowWithValidValue[columnProp] === 'number')) {
+				nullReplacement = 0
+			}
+
+			return data.map(row => {
+				return {
+					...row,
+					[columnProp]: row[columnProp] ?? nullReplacement,
+				}
+			})
+		} else {
+			return data
+		}
+	},
+	handleFormattingTemplates: formatting => {
+		if (formatting && typeof formatting === 'object') {
+			for (const key in formatting) {
+				if (typeof formatting[key].format === 'string') {
+					if (formatting[key].format in formatterTemplates) {
+						formatting[key].format = formatterTemplates[formatting[key].format]
+					} else {
+						formatting[key].format = {}
+					}
+				}
+			}
+		}
+
+		return formatting
+	},
+	getDataTableFormat: (data, fields, multiSeries) => {
+		let cols = []
+		// domain column for multiseries charts
+		if (multiSeries) {
+			cols = [ makeDataTableCol(multiSeries.groupXAxisBy, fields) ]
+		}
+		// All other columns (including domain for non multiseries charts)
+		for (const key in fields) {
+			if (!multiSeries || key !== multiSeries.groupXAxisBy) {
+				if (multiSeries && multiSeries.tooltip && key.includes(multiSeries.tooltip)) {
+					// If it's a tooltip, set the column's role exlicitly
+					cols.push(makeDataTableCol(key, fields, 'tooltip'))
+				} else {
+					// Otherwise, role is implicitly assigned
+					cols.push(makeDataTableCol(key, fields))
+				}
+			}
+		}
+
+		const rows = data.map(row => {
+			let items = []
+
+			for (const column in row) {
+				items.push({ v: row[column] })
+			}
+
+			return {
+				c: items,
+			}
+		})
+
+		return { cols, rows }
+	},
+	makeDataCumulative: dataTable => {
+		dataTable.rows.forEach((row, rowIndex) => {
+			if (rowIndex > 0) {
+				row.c.forEach((col, colIndex) => {
+					if (colIndex > 0 && col.v == null) {
+						col.v = dataTable.rows[rowIndex - 1].c[colIndex].v
+					} else if (colIndex > 0) {
+						col.v = col.v + dataTable.rows[rowIndex - 1].c[colIndex].v
+					}
+				})
+			}
+		})
+		return dataTable
+	},
+	getRactiveTableDataFormat: (data, fields, formatting) => {
+		const columns = Object.keys(fields).map(field => {
+			// right align currency values
+			if (formatting[field]?.type === 'NumberFormat' && formatting?.[field].format.prefix === '$') {
+				return {
+					property: field,
+					name: field,
+					class: 'text-right',
+				}
+			}
+			return {
+				property: field,
+				name: field,
+			}
+		})
+		return {
+			columns,
+			rows: data,
+			sortedRows: [],
+		}
+	},
+}

package/formatter-templates.json

@@ -0,0 +1,9 @@
+{
+	"formatterTemplates": {
+		"CURRENCY": {
+			"prefix": "$",
+			"fractionDigits": 2,
+			"groupingSymbol": ","
+		}
+	}
+}

package/index.js

@@ -0,0 +1,181 @@
+const db = require('@isoftdata/utility-db')
+const {
+	getMultiSeriesData,
+	makeNegativeNumbericValuesZero,
+	coerceNullColumn,
+	handleFormattingTemplates,
+	getDataTableFormat,
+	queryWithFields,
+	makeDataCumulative,
+	getRactiveTableDataFormat: getRactiveTableDataFormat } = require('./chart-helper.js')
+const { datesFromRange } = require('@isoftdata/utility-date-time')
+const formatDate = require('date-fns/format')
+
+const handleChartTypeSpecificQuirks = (chartType, resultSet) => {
+	if (resultSet.length) {
+		switch (chartType) {
+			case 'PieChart':
+				//PieCharts error if you have negative numbers, so we'll just set those to 0
+				resultSet = makeNegativeNumbericValuesZero(resultSet)
+				break
+			case 'TreeMap':
+				//tree charts need the 2nd columns to be not null
+				resultSet = coerceNullColumn(Object.keys(resultSet[0])[1], resultSet)
+				break
+			default:
+				//all charts need the first column to be not null
+				resultSet = coerceNullColumn(Object.keys(resultSet[0])[0], resultSet)
+		}
+	}
+
+	return resultSet
+}
+
+const loadChartData = async(mysqlConnection, { name, query: queryObject, formatting, chartWrapper, multiSeries, parameters, table, ...theRest }) => { // needs database connection
+	let { results: queryResultSet, fields } = (queryObject && queryObject.sql) ? await queryWithFields(mysqlConnection, queryObject) : { fields: [], results: [] }
+	let data = handleChartTypeSpecificQuirks(chartWrapper.chartType, queryResultSet)
+
+	if (multiSeries) {
+		({ data, formatting, fields } = getMultiSeriesData({
+			data,
+			seriesOptions: multiSeries,
+			formatting,
+			fields,
+		}))
+	}
+
+	const proccessedFormatting = handleFormattingTemplates(formatting)
+
+	let dataTable = getDataTableFormat(data, fields, multiSeries) //per the Google Charts docs, the DataTable object literal format is the most performant, so we'll turn it into that format before returning
+
+	// Stacked area charts will have holes / jagged lines if there are nulls in the middle of a column
+	// Presumably we'll also want to be able to have non-cumulative area charts at some point
+	if (chartWrapper.chartType == 'AreaChart') {
+		dataTable = makeDataCumulative(dataTable)
+	}
+
+	if (chartWrapper.chartType === 'Table') {
+		return {
+			...theRest,
+			chartWrapper,
+			table: { ...table, ...getRactiveTableDataFormat(data, fields, formatting) },
+			formatting: proccessedFormatting,
+		}
+	}
+	return {
+		...theRest,
+		chartWrapper: {
+			...chartWrapper,
+			dataTable,
+		},
+		formatting: proccessedFormatting,
+	}
+}
+
+const loadOptionList = async(mysqlConnection, optionListQuery, optionList = []) => {
+	return [
+		...optionList,
+		// ...(optionListQuery && await query(mysqlConnection, optionListQuery)) || [],
+		...(optionListQuery && await db.query(mysqlConnection, optionListQuery)) || [],
+
+	]
+}
+
+const loadOutputParameterValues = async(mysqlConnection, definitionList, selectionList = []) => {
+	let parameterValues = []
+
+	for (const definition of definitionList) {
+		const matchingParameterSelection = selectionList.find(param => param.name === definition.name)
+
+		let parameter = {
+			name: definition.name,
+			type: definition.type,
+			title: definition.title || definition.name,
+			default: definition.default,
+			value: (matchingParameterSelection && matchingParameterSelection.value) || definition.default,
+			queryValues: {},
+		}
+
+		if (definition.type === 'dateRange') {
+			parameter.dates = matchingParameterSelection?.dates || { to: null, from: null }
+			parameter.value = parameter.value || 'Last 30 Days'
+			if (parameter.value !== 'Custom') {
+				parameter.dates = datesFromRange(parameter.value)
+			}
+			parameter.queryValues = {
+				[`${parameter.name}_start_date`]: parameter.dates.from,
+				[`${parameter.name}_end_date`]: parameter.dates.to,
+			}
+		} else if (definition.type === 'selection') {
+			parameter.optionList = await loadOptionList(mysqlConnection, definition.optionListQuery, definition.optionList) // queries db
+			parameter.queryValues = {
+				[parameter.name]: parameter.value,
+			}
+		} else if (definition.type === 'date') {
+			parameter.value = parameter.value || formatDate(new Date(), 'yyyy-MM-dd')
+
+			parameter.queryValues = {
+				[parameter.name]: parameter.value,
+			}
+		}
+
+		parameterValues.push(parameter)
+	}
+
+	return parameterValues
+}
+
+const parameterizeQuery = (query, parameterValues) => {
+	const queryParameterValues = parameterValues.reduce((acc, val) => {
+		return val.queryValues ? {
+			...acc,
+			...val.queryValues,
+		} : acc
+	}, {})
+
+	//match on a token that starts with ${ and ends with a closing }.
+	//Then include a capture group to get the inner part of that to use as a key
+	const regexp = /\${([^}]+)}/g
+
+	const queryParameterKeys = [ ...query.matchAll(regexp) ].map(([ fullToken, insideToken ]) => insideToken.trim())
+	//if they put a token in the query that isn't one of the defined parameters of the report, just return null?
+	const queryParameters = queryParameterKeys.map(key => queryParameterValues[key] || null)
+
+	return {
+		sql: query.replace(regexp, '?'),
+		values: queryParameters,
+	}
+}
+
+module.exports = {
+	formatReportMetadata: async(mysqlConnection, { report, chartsInReport }) => {
+		const parameterValues = await loadOutputParameterValues(mysqlConnection, report.parameters)
+		const parameterValuesForClient = parameterValues.map(param => {
+			const { queryValues, ...parameterValuesForClient } = param
+			return parameterValuesForClient
+		})
+
+		return {
+			dashboardReportId: report.dashboardReportId,
+			name: report.reportName,
+			title: report.reportTitle,
+			charts: chartsInReport,
+			parameterValues: parameterValuesForClient,
+			ownerId: report.ownerId,
+		}
+	},
+	formatChartDataForReport: async(mysqlConnection, { reportParameters, chart, reportChart, parameterSelectionList }) => {
+		try {
+			const parameterValues = await loadOutputParameterValues(mysqlConnection, reportParameters, parameterSelectionList)
+			return await loadChartData(mysqlConnection, {
+				...chart,
+				reportChartId: reportChart.reportChartId,
+				...reportChart.jsonOverride, // overwrites whole chart wrapper :\
+				query: parameterizeQuery(chart.query, parameterValues),
+			})
+		} catch (err) {
+			console.error(err)
+			return { isErrored: true, err }
+		}
+	},
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+	"name": "@isoftdata/utility-dashboard-backend",
+	"version": "1.0.0",
+	"description": "A utility for formatting chart and report data to be usable by the frontend dashboard component.",
+	"main": "index.js",
+	"scripts": {
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"author": "Charles Kaup",
+	"license": "ISC",
+	"dependencies": {
+		"@isoftdata/utility-date-time": "^2.0.3",
+		"@isoftdata/utility-db": "^2.2.0",
+		"date-fns": "^2.23.0",
+		"klona": "^2.0.4",
+		"mysql": "^2.18.1",
+		"to-snake-case": "^1.0.0"
+	}
+}

package/schema.md

@@ -0,0 +1,120 @@
+## Reporting/Charting
+The dashboard component has a set of three database tables where reports, charts, and their associations are defined: `dashboard_report`, `dashboard_chart`, and `dashboard_report_chart`. Reports are a collection of various charts. Reports have parameters and charts can use said parameters. Currently Charts are rendered using [Google Charts](https://developers.google.com/chart/).
+
+### Defining a Report
+Reports can be created either with the frontend dashboard component or manually in the database. The frontend component supports setting the report's name, the charts contained within it, who it is shared with, and the default value of any parameters. Currently it is not possible to add or remove parameters for reports within the frontend component, as charts' queries also have to support any additional parameters.
+
+### Report Database Row - `dashboard_report`
+Property | Type | Description
+---- | ---- | -----------
+dashboard_report_id | `Unsigned integer` | **Required** - Primary key. Auto incremented.
+report_name | `String` | **Required** - a unique name for the report.
+report_title | `String` | When rendered, this title will be displayed at the top of the card. If omitted, `name` will be used.
+json | `JSON` | Should be parsed into a JS object. This field contains JSON for an array of parameter objects, the format of which is detailed below.
+share_type | `Enum` | Controls access to reports within the dashboard. Possible values include: `everyone`, `group`, `store`, and `user`. Defaults to `everyone`.
+share_id | `Unsigned integer` | Used in conjunction with `share_type` to control access to reports. When `share_type` is 'everyone', this field is null. Otherwise, it contains the id of the user, group, or store to share the report with. Defaults to `NULL`.
+owner_id | `Unsigned integer` | The `user_account_id` of the user who created the report in the dashboard. This user will always have access to the given report, regardless of its sharing settings, and will be shown as the report owner on the configuration screen. Defaults to `NULL`, which designates it as a default report.
+
+#### Parameter Object
+Property | Type | Description
+---- | ---- | -----------
+name | `String` | **Required** - a unique name for the parameter. This name is also used to reference param in a query.
+title | `String` | This is used to label the parameter for the user.
+type | `String` | Can be one of `dateRange`, `date`, or `selection`. See the tables below for parameter-type-specific properties
+
+##### `dateRange` Type Properties
+> In the UI, the user will see a dropdown with the possible date range values(see `default` description below).
+
+Property | Type | Description
+---- | ---- | -----------
+default | `String` | One of the following values: `'Today'`, `'Yesterday'`, `'Last 7 Days'`, `'Last 30 Days'`, `'Last 90 Days'`, `'Last 365 Days'`, `'This Week'`, `'This Month'`, `'This Quarter'`, `'This Year'`, `'Previous Week'`, `'Previous Month'`, `'Previous Quarter'`, or `'Previous Year'`. If the `default` property is omitted or [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), `'Last 30 Days'` will be used.
+
+##### `date` Type Properties
+> In the UI, the user will see a dropdown with a date picker.
+
+Property | Type | Description
+---- | ---- | -----------
+default | `String` | Can be an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string(eg. `'2021-01-13'`). If the `default` property is omitted or [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), the today's date will be used.
+
+##### `selection` Type properties
+> In the UI, the user will see a dropdown with the `optionList` values(if any) and the values returned from the `optionListQuery`(if any).
+
+Property | Type | Description
+---- | ---- | -----------
+default | `String` | The `id` of the option you'd like to be selected by default
+optionList | `Object` | Each object should have an `id`, and `name`. `id` is the value that will be given to you at query time and `name` is what will be displayed in the dropdown to the user.
+optionListQuery | `String` | A query that selects 2 columns `id` and `name`. The results of this query will be merged with `optionList` and put in the dropdown for the user.
+
+#### Example
+'dashboard_report_id' | 'report_name' | 'report_title' | 'json' | 'share_type' | 'share_id' | 'owner_id'
+-- | ---- | ---- | ------- | -- | -- | --
+1 | report_overview | Overview | `{"parameters": [{"name": "date_range", "type": "dateRange", "title": "Date Range", "default": "This Year"}]}` | everyone | `NULL` | `NULL`
+2 | shared_report | Shared Report | `{"parameters":[{"name":"date_range","type":"dateRange","title":"Date Range","default":"This Month"}]}` | user | 1 | 2
+
+### Defining a Chart
+Currently, charts cannot be defined within Pro web, and must be created in the database table `dashboard_chart`. Currently, 19 charts are defined, but some are set to not show as options in the user interface.
+
+### Chart Database Row - `dashboard_chart`
+Property | Type | Description
+---- | ---- | -----------
+chart_id | `Unsigned integer` | **Required** - primary key. Auto incremented.
+chart_name | `String` | **Required** - a unique name for the chart
+chart_title | `String` | When rendered, this title will be displayed at the top of the card. If omitted, `name` will be used.
+supertype | `Enum` | **Required** - designates how the chart should be loaded. Options include `google`, `table`, and `embed`. Defaults to `google`.
+json | `json` | Should be parsed to a JS object on the server. Contains several properties: `query` (string, **required**), [`chartWrapper`](https://developers.google.com/chart/interactive/docs/reference#chartwrapper-class) (object, **required** for Google charts), `multiSeries` (object, **required** for multi-series charts), `formatting` (object).
+show_chart | `Bit` | **Required** - Should be cast as a boolean on the server. Whether or not to show a chart in the configuration UI. Defaults to `1`.
+
+#### MultiSeries Object
+Property | Type | Description
+---- | ---- | -----------
+groupXAxisBy | `String` | **Required** - The name of the query column that determines the X axis of the chart.
+series | `String` | **Required** - The name of the query column that determines which series a query row corresponds to.
+value | `String` | **Required** - The namem of the query column that contains the value for that data point.
+tooltip | `String` | The name of the (optional) query column that contains a custom plaintext tooltip, which replaces the default Google Charts tooltip. Does not work for Tree Map type charts, which have special tooltip requirements.
+
+#### Formatting Object
+An object whose property names are the columns in the query to be formatted. Currently only currency formatting is supported.
+
+Property | Type | Description
+---- | ---- | ---------
+type | `String` | The name of a [Google Charts Formatter](https://developers.google.com/chart/interactive/docs/reference?hl=en#formatters).
+format | `String` | The name of a formatter template, defined in `formatter-templates.json`.
+#### JSON Example
+
+```json
+{
+	"chartWrapper": {
+		"chartType": "AreaChart",
+		"options": {
+			"isStacked": true,
+			"width": 1000,
+			"height": 1000
+		}
+	},
+	"multiSeries": {
+		"groupXAxisBy": "Date",
+		"series": "Part Type",
+		"value": "Sales",
+		"tooltip": "Tooltip"
+	},
+	"formatting": {
+		"Sales": {
+			"type": "NumberFormat",
+			"format": "CURRENCY"
+		}
+	},
+	"query": "SELECT t.date AS `Date`,\r\n       IFNULL (t.part_type, 'Misc. Lineitems') AS `Part Type`,\r\n       ROUND(@running_total:=@running_total + t.sales, 2) AS `Sales`\r\nFROM\r\n(SELECT \r\n`wa_sale`.`document_date` AS `Date`,\r\nIF(wa_sale_line.part_type = '', 'Misc. Lineitems', wa_sale_line.part_type) AS `part_type`,\r\nFORMAT(SUM(wa_sale_line.quantity * `wa_sale_line`.`price`), 2) AS `sales`\r\nFROM \r\n`wa_sale_line`\r\nINNER JOIN `wa_sale` USING(`sale_id`)\r\nWHERE\r\n`wa_sale`.`status` = 'Invoice' AND wa_sale.document_date IS NOT NULL\r\n GROUP BY \r\n `wa_sale`.`document_date`, `wa_sale_line`.`part_type`) t\r\n JOIN (SELECT @running_total:=0) r\r\n ORDER BY t.Date;"
+}
+```
+
+### Adding charts to reports
+Adding charts to reports can be handled entirely within the dashboard component. Each row in the database table `dashboard_report_chart` defines the association of one chart to one report, the rank of the chart within the report, and any additional object properties to apply to the chart when displayed in that report.
+
+### Report Chart Database Row - `dashboard_report_chart`
+Property | Type | Description
+---- | ---- | --------
+report_chart_id | `Unsigned integer` | **Required** - Primary key. Auto incremented.
+dashboard_report_id | `Unsigned integer` | **Required** - Foreign key constraint with `dashboard_report.dashboard_report_id`.
+chart_id | `Unsigned integer` | **Required** - Foreign key constraint with `dashboard_chart.dashboad_chart_id`. `chart_id` and `dashboard_report_id` must be a unique pair.
+rank | `Unsigned integer` | The order to display the chart in on the report. Defaults to 1.
+json_override | `Text` | Parsed as JSON on the server. Contains any JSON properties to be applied to the chart for the given report, overriding any of the same property on the base chart. Primarily used for chartWarpper options. Default `NULL`.