pro-web v18.9.3

Pro Web

A modern web-based version of ITrack Pro.

Moved from SVN to GitHub at SVN revision 32416

Getting started for development

• clone repo
• make sure you have node version 20+ installed
• make sure you are logged into an npm account(npm login) that has access to the @isoftdata npm organization. If you don't have access, ask another ISoft developer for an invite.
• Run npm i in the cloned pro-web directory
• create a config.json file (see config.template.json)
• build the server with npm run build-server-watch
• start the server for dev by running npm run startdev. This will also build and serve the client.
  • By default, this will look for a config.json file. If you want to user another file, run npm run startdev <theFileName>
• open your browser to localhost on the port specified in the config.json file's webport property.

Instead of running build-server-watch and startdev manually, you can run the "Server: Dev" debug configuration

Yup Schema Validation

Yup is used for schema validation, custom methods have been added to make handling dates and other data types easier. To access these on the server, you should require tools/yup-helper instead of yup. This will give you access to all the features of yup, plus the added custom methods, which are detailed below.

yup.mixed().dateNowOnInsert(primaryKeyName)

If the named primary key is truthy (i.e., when inserting a new row), it will strip off this property. Otherwise (i.e. updating an existing row), it will replace the property's value with the current date and time according to the database. This will also work fine if you already pass db.NOW on the property, since it matches the shape enforced by this function.

yup.mixed().dateNow()

Replaces the current value with the current date and time according to the database.

yup.boolean().enumBool()

Coerces a string ('True' or 'False'), native JS boolean, or other value(truthyness test) to a string with the value of either "True" or "False".

yup.number().precision(integer)

Evaluates whether the current value has at most the specified number of digits.

yup.string().ensureValidIsoDate()

Evaluates whether the current value is a valid string representation of an ISO date

yup.string().isValidJSON()

Evaluates whether the current value is valid JSON by parsing it.

printValueAndType

Prints the value and type of the current value without mutating it. Used for debugging.

Error logging and handling

Logging errors in mediator requests

Whenever you make a mediator request to emitToServer or noAuthEmitToServer, any errors thrown by the server will implicitly be caught, logged, and an alert will be shown to the user. If you want to override the default behavior, you can optionally pass a third parameter in your mediator request, an object with the properties shown below.

logOptions properties

Example

const auth = await mediator.call('noAuthEmitToServer', 'authenticate', {
	userName,
	passphrase,
	storeId,
}, { doNotAlert: true, message: '', context: 'login' })

Logging errors elsewhere in client code

If you want to log errors outside of mediator requests, you can do so with the logAndAlert function, which is included in the context object passed to every state.

Function arguments

Example

try {
	// Something that can throw an error
} catch (err) {
	logAndAlert(
	err,
	mediator,
	'This will be shown to the user and logged with the error. It should be a string',
	'This will be logged alongside the error. It can be of any type.',
	{
		type: 'danger', // Bootstrap alert class
		time: 3000, // Milliseconds before the alert dismisses itself
		dismissable: true // Whether to allow the user to dismiss the alert
	})
}

Retrieving the error log

The error log is stored in the localStorage variable errorLog. You can view it from the web browser's console. At the top level, it is an object whose keys are the userAccountId of the logged in user when the error was logged. Each of these properties is an array of objects, representing any errors that were logged, sorted by age, newest first. Only 100 logs will be stored per user, then the oldest will be removed whenever a new error is inserted.

There is also a function, getErrorLog, that retrieves this object from localStorage.

Reporting/Charting

Pro web has a set of three database tables and views where reports, charts, and their associations are defined: wa_dashboard_report, wa_dashboard_chart, and wa_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.

Defining a Report

Inside of Pro web, reports can be created on the Configuration > Dashboard screen. This includes the report 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 Pro web, because all charts require the date range parameter, and support no others.

Report Database Row - wa_dashboard_report

Parameter Object

dateRange Type Properties

In the UI, the user will see a dropdown with the possible date range values(see default description below).

date Type Properties

In the UI, the user will see a dropdown with a date picker.

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).

Example

Defining a Chart

Currently, charts cannot be defined within Pro web, and must be created in the database view wa_dashboard_chart. Currently, 19 charts are defined, but some are set to not show as options in the user interface.

Chart Database Row - wa_dashboard_chart

MultiSeries Object

Formatting Object

An object whose property names are the columns in the query to be formatted. Currently only currency formatting is supported.

JSON Example

{
	"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 is handled entirely in the interface of Pro web, on the Configuration > Dashboard screen. Each row in the database view wa_dashboard_report_chart defines the association of one chart to one report, the rank of the chart within the report, and any JSON to apply to the chart when displayed in that report.

Report Chart Database Row - wa_dashboard_report_chart