Why is the JSON syntax so important?
As already mentioned in Cliosight's Features, the JSON definition of each UI and back-end component decides the characteristics of it.
The way we arrange these tags in their
hierarchical structure with options, will decide whether or not they serve the exact purpose without any errors.
Below are the highlights of the JSON configurations, along with some API method names. Please note that this is a work in progress. The complete documentation will be shared later.
Example of a Form JSON
"datasource_id" or "datasource_code" - These tags are used to specify the numeric ID or string alias of an internal or external datasource.
client_id, workspace_id, and code are other tags that are automatically added just like the datasource_id.
"table" and "sub_form_table" - To specify the database table name using "name" tag. In some cases, it may have a SQL query like those used for creating documents.
"sub_form_definition" - This indicates the start of a new form definition.
"is_public" - To specify if the form is publicly available using the boolean "status" (true/false) tag.
"inputs" - To indicate the start of an array of input fields in the form.
"cols" - To specify the number of columns that the input will occupy, similar to HTML col.
"input_category" - To define the broader type of input in the form (field/multiselect/form) under the "input" list.
"column" - This is for the "Field" tag that holds the name of the table column.
"input_type" - To specify the type of data for that input field (text/textarea/radio/checkbox/select/table_select/file). There are also the "input_label" and "placeholder" for the two common attributes of a text field.
"validation" - This umbrella tag holds all the validation parameters for the field
("isRequired"/"maxLength"/"minLength"/"size_in_kb"/"types"/"max_width_in_px"/"min_width_in_px").
"options" - The "value" and "label" tags of this array is for providing the hardcoded options of a drop down menu.
"report_config" - To specify which report column should be mapped to the table column of a subform using "column", "report_id", "column_label" and "term_column" tags.
"sub_form_table" - This has the "name" of the table where the subform entries will be written. This is followed by the "join_criteria_main_table_column" and "join_criteria_sub_table_column" having the "Field" values.
"input_links" - This is a list of links to other related forms that are associated in some way to the input field. We use the tags "type", "code" and "label" to add a form link.
"onFormSubmitComplete" - This is followed by a "report_config" or "options" block in case an "input link" form is added. "report_config" here is used to refer to the report column details of the one which is used to populate the values of the multiselect option drop down through the subform.
Other way is to provide hardcoded values as already mentioned through "options" list. This is a typical use case since a subform linked to a drop down in the main form is almost always used to add an additional value.
"rules" - This has the "column" and "value" tags to specify the logical branching for a "select" input_type. It is followed by
"action", "show", "input_category" with value "form", "sub_form_button_label", "hide_sub_form_button", "default_instances_count", "hide_instance_remove_button" and sub form details.
"helper_input" - This is useful in case of conditional field addition like the "Other" option at the end of drop down menus where a text field appears only on selecting this option.
"join_definition" - This tag is used to define the join criteria between the main form and the subform tables using the "sub_table_column" and "main_table_column".
"unique_keys" - This is used to provide a list of primary keys used in the sub form definition table.
"datepicker" - This has a boolean value to indicate whether or not this will have a date-time picker showing on click event.
This one is followed by "timepicker" which is also a boolean, "format" for examlple "m/d/Y H:i", "step", "update_value" having "{{current_datetime}}" and "update_on_update" flag. Other such values for "hidden" columns are
"{{token.userEmail}}".
"last_insert_id_key" - To specify the unique key for the main form table, which is the auto-generated "id" most of the time.
"submit_button_label" - This is a very useful tag as one can change the label of the submit button from "Submit" to something more suitable like "Send Message" in a "Contact us" form.
"pre_html", "post_html", "css_definition" - While the "css_definition" is common for all, each field can have its own "pre_html" and "post_html" tags. Using this,
a user can add text, hyperlinks, images and videos anywhere in the form. For a form, report and SPA this is useful for adding headers and footers.
"export_html" - This is for defining the structure of a document to be generated as an image containing a report's row values. It is used extensively in our templates for creating invoices, bills and receipts.
"uuid_column" - This is used to specify the "Field" name for the uuid_file_name in case of "file" input_type.
"mc_users" and "mc_groups" - To enable permissions for accessing a form. We have these tags to provide a list of numeric user and group IDs.
Example of a Report JSON
"datasource_id" or "datasource_code" - This is the tag used to specify the numeric ID or string alias of the internal or external datasource.
An example of a complete report config is given here.
"multiple_statements" - This flag indicates if the SQL query used to generate this report is a culmination of several queries to be executed concurrently.
"page_size" - To specify the number of rows in each numbered page (pagination).
"links" - This tag is followed by an array of actions that can be done on click, that which are related to that particular report cell.
For instance, fetching the record for editing, updating that value through an inline form, viewing another report filtered by that value, adding a new record, downloading invoice PDF and deleting the record from the report only.
"table_headers" - To group together related columns.
"filter_menu" - This is a simple way to add filters to the report that may be column values of
another report, date range, maximum and minimum values of a quantitative metric etc. They can be a single value or multiselect just like a form drop down.
"report_links" - This comes at the end to add optional links to the report as a whole, such as related forms. By default, all reports have the "Export" link to download the CSV values.
"pre_html", "post_html", "css_definition" - The HTML tags are similar to a form's.
"sort" - This is used to sort report columns in a particular order. Several columns can be mentioned under the same drop down with a description.
For instance, "Order Total (High to Low)" and "Client Name (A-Z)"
Below are the tags for changing the default chart view of a report:
"disable_table_view" - This is the tag used to disable viewing of report rows in text so that only the chart is seen.
"default_view" - To retain the tabular format but to make chart the default view, a user can set it to value "chart", else "table".
"disable_chart_view" - This tag is used to disable the chart view in case a user feels that it is irrrelevant for that report. For instance, if there are no numeric values to measure.
"default_chart_view" - This parameter specifies the type of chart to be used by default. It can have "bar", "line", "pie" and "stacked" values. It can be changed from the chart links drop down along with the Attributes and Metrics.
Public reports are available for Professional and Enterprise users.
Example of a SPA JSON
"hideToolbar" - This can be used to either hide or show the toolbar that holds the name of the single-page application and global filters connecting two
or more reports. Global filters are used to apply filters on several reports having common column data.
"widget_groups" - This tag is used to group together several widgets (reports) on which gloabl filters are applied.
"widgets" - To define the report, chart or form with id, columns and removeReportCss or removeFormCss flag.
"filter_menu" - This tag is similar to a report filter except for the fact that this is always a global filter. So, this array
will list the values of dropdown menu first using attributes like "column", "column_label", "label, "report_id" and "name" followed by each report with ID or code and similar details
Example of an Application JSON
"default_page_id" - This is the id of the landing SPA for the application.
"nav_links" - Just like a navigation bar on a website, we have the navigation links listing the SPAs. Using the "label" and "page_id", all of them can be arranged serially.
Example of a Trigger config
"trigger_type" - The type of trigger corresponds to a CRUD operation viz. create/update/delete. This comes under "trigger_definition" which marks the start of the attributes' list.
"trigger_entity" - The tag for naming the database table.
"trigger_condition_query" - Describes the check based on which the action will be executed.
"trigger_action_query" - The insert/update/delete query on the target entity using the values from the condition specifed.
"label" - A unique name for the trigger.
Example of a Datasource config (MySQL installed on EC2)
"id" - This is the numeric ID of the datasource.
"code" - This is a string alias for referring to the datasource.
"type" - Database type.
"dedicatedPool" - Dedicated connection pool for paying client if set to true.
"connectionLimit" - Maximum number of connections allowed at a time.
"host" - Public IP address of the VM
"port" - Port number on which the database server is running.
"user" - Database user name.
"password" - Database password.
"database" - Unique database name created in the database server.
"multipleStatements" - Boolean to enable concurrent query execution.
"label" - Database name for listing under datasources in the admin console.
The definitions for a containerized or fully-managed database will be slightly different. Same applies for GCP BigQuery, AWS Redshift or Snowflake data products.
Example of an API call in Python
Get Config Definition (Admin + User)
List Forms / Reports / SPAs / Applications (Admin + User)
List Datasources / Tables / Users / Groups / Triggers / Jobs / Workflows / Workspaces (Admin)
Import Project (Admin)
Disable / Enable API (Admin)
Dump Admin Action History (Admin)
Check API Status (Admin)
Form
Create / Update / Delete a Form (Admin)Import Data (Admin + User)
Submit a Form (Admin + User)
Report
Create / Update / Delete a Report (Admin)Export Data (Admin + User)
Generate File (Admin + User)
Download Generated File (Admin + User)
File Storage
Upload File (Admin + User)Download File (Admin + User)
Trigger
Create / Update / Delete Trigger (Admin)Notification
Send Email Notification (Admin + User)Job
Create / Update / Delete Job (Admin)Run a Job (Admin)
Stop a Job (Admin)
Pause a Job (Admin)
Resume a Job (Admin)
Workflow
Create / Update / Delete Workflow (Admin)Execute a Workflow (Admin)
Stop a Workflow (Admin)
Disable a Workflow (Admin)
Enable a Workflow (Admin)
Database Operations
Rollback (Admin)Check Integrity (Admin)
Get Backup (Admin)
Single-Page Application
Create / Update / Delete SPA (Admin)Application
Create / Update / Delete Application (Admin)Datasource
Create / Update / Delete Datasource (Admin)Run SQL Query on a Datasource (Admin)
Users and Groups
Create / Update / Delete User or Group (Admin)Add / Delete User in a Group (Admin)
Update Permissions for a User / Group (Admin)
Workspace
Create / Delete Workspace (Admin)AI
Generate SQL Query for a Datasource (Admin)Generate JSON config for a UI or automation component (Admin)
Generate text summary for a Report or Report row (Admin + User)
Generate Database Schema (Admin)
Generate App (Admin)