Export Module - Quick Start Guide

Export Module - Quick Start Guide


Welcome to the Quick Start Guide for The Export Module!

This guide will help you get up and running quickly with exporting data from your forms.

Our feature allows you to export form data into CSV, JSON, and XML formats, with customizable file structures using XSLT 1.0 to meet your specific needs. You can trigger exports via API calls or schedule them to run automatically, and then send the exported data through API response, webhook, or clevr SFTP.

Follow the steps in this guide to efficiently manage and share your form data in the desired format.

Step 1: Open the module

Go to the Configuration menu, and find "Export Module".

This feature is currently in closed Beta. Once widely released, if you do not see this option in your Configuration menu, please contact Clevr Support at support@clevr.ca and we will be happy to help you enable the feature.

Step 2: Create a New Export

A new export can be created by using the  button at the top of the left hand menu, or by using the large button on the Home screen.

When clicked, a modal will open and you will be presented with the following settings for your new Export:

Export Name
This is the name of the new export. The name will be used to differentiate the exports in the menu on the left.

Output Format
This setting determines the file type for the output files. We support CSV, JSON, and XML.

If the export is primarily for data archiving or if you do not have specific format requirements, we recommend using XML. This format allows you to take advantage of our Preset Generation feature, which will build an export for you with just a few settings.

Encoding
This setting determines the text encoding for the output files. Unless the software using the output files specifically requires ASCII, we recommend setting this to UTF-8 for better support of non-Latin characters.

Data Source
This is the form from which the data will be exported.
Once created, the Data Source can not be changed.

Once you are happy with the settings, click "Add".

Step 3: Open the Editor

Once an Export has been created, the definition must be published before any other settings can be configured.

In the Action Bar at the top of the page, find and click on "Edit". This will open the Export Editor.

Step 4: Start Editing the Export Definition

The Export Module uses a programming language called XSLT 1.0 to allow you to transform data into the file structure you require.

There are 4 main sections of the editor:

Code Editor
The area in on the left of the screen, this code editor will allow you to write your definition. The Code Editor should feel and behave like other coding environments, and supports tabbing multiple lines in both directions, collapsable sections, and syntax highlighting.

Elements Panel
The Elements Panel displays the data contained in the datasource. The "Quick Insert" buttons on the right of this panel will allow you to add common XSLT code with the correct elementIds already inserted.

The Quick Inserts buttons are:

  1. #: Inserts the Element ID only, with an e appended.
  2. Value: This will insert a "xsl:value-of" tag, which is required to output the value of an element.
  3. If: This will insert an "xsl:if" tag, which can be used to conditionally show a section based on the if condition.
  4. For Each: This will insert an "xsl:for-each" tag, which allows you to loop through each instance of a tag. This is most useful for items like repeaters.

Data Source Panel
The Data Source Panel displays the source data being used to generate the preview. This can be helpful for debugging and review purposes.

The source data contains extra bits of information not exposed by the Elements Panel, such as element type, date that a value was entered, and description. This data can be used in the definition to allow for complex rules.

Action Bar
The Action Bar is the full-width area at the top of the page. It displays the export name and contains the buttons to control the editor.




Step 5: Building using a Preset (XML Only)

If you do no have specific format requirements, or would like to see examples of how to develop using XSLT 1.0, you can use our "Presets" feature. To use a Preset, click on the button in the Action Bar.

Using the Presets feature will overwrite the existing definition. If you overwrite your definition with a preset, please discard changes and reopen the editor to avoid overwriting your work.

When creating a Preset, you are presented with the following options:

Build With Form Hierarchy
When this option is enabled, the tabs will be nested based on the hierarchy of the form.
When this option is disabled, the tabs will be all be placed at the same nested level.

Exclude Nodes With Blank Data
When this option is enabled, the generated preset will include conditional tags that will not include an elements tag if the value is blank. Otherwise, all element nodes will always be included.

When using software to read the export, it may prefer to always have all blank nodes. If a human is going to be reading 

Node Name
This option will determine how each node will be named. The naming options are:
  1. Element Id: This option will name nodes using the Element ID, with an "e" appended to the ID.
  2. Element with Id Attribute: This option will name all nodes "element", but will add an attribute that contains the Element ID.
  3. Description: This option will clean the element description and use that description as the name. This option can produce unwieldy node names and should be used with caution.
Group Records By
This option will add code to the preset that will automatically group records by the persons Location, Grade, or Role.

Step 6: Editing the Definition

Developing the export definition uses XSLT 1.0 as a processor to generate the text out.

As you are developing, we encourage you to frequently preview the result to understand how your code is working. The source of the preview data is displayed in the "Data Source" panel, as described in Step 6. This data source is populated with the most recent updated 25 records that you also have access to.

We have included a custom function that you can use to help with data formatting. Certain formats such as CSV and JSON require some characters to be handled differently. This can include quotes and commas. The function is called str:sanitize(), and an example of using it is:

<xsl:value-of select="str:sanitize('e123456789')"/>

Step 7: Saving, Publishing, Discarding

There are 4 actions that control the state of your export: Save, Publish, Discard, and Exit.

Clevr stores 2 versions of every export, the published version and the draft version.

When you click "Save", you are saving the opened version as the draft. If the draft and published version are different, you can use "Discard" to remove the draft and return to the last published version of the export.

When you click "Publish", the published version will be updated and the draft version will be cleared.

When you click "Exit", you will leave the Editor. If you have made changes that have not been saved, exiting will cause those changes to be lost.



Step 8: Adding Triggers

Please note that Triggers are disabled until an export has been published for the first time. If  "Add Trigger" is disabled, please ensure that the export has been published.

Triggers allow you to define an export process that will use an export. There are 3 part to every trigger:
  1. The trigger event
  2. The output
  3. The filters
After adding a meaningful name and setting status to "Active", you need to decide if the triggering event will be an API call to Clevr or run on a schedule.

Next, you can define the output. We support API Response (for API trigger events), saving the file to the Clevr SFTP site, or sending the data to another server via a webhook.

Lastly, you can define the filters that will be used to select the records for the trigger. These filters match how you select records on the Listings card.

Updates to the definition will automatically apply to all attached triggers.

By building a series of triggers, you can create segmented exports based on your own business rules. Examples of using a combination of triggers and filters include:
  1. Creating an individual SFTP file for each grade, using the same export definition. 
  2. Exporting all records via an API, but then also using a scheduled webhook to send a list of all "at-risk" students via webhook.
  3. Creating an API for each group of locations for individual regional leaders to access data without providing cross group access.


Step 9: Run Now and Auditing

Please note that Run Now is disabled until an export has been published for the first time. If this button is disabled, please ensure that the export has been published.

Run Now
Run Now allows you to define a Listings filter search, and use the current export that can be viewed, copied, and downloaded in the interface. This type of export respects the user's form access, so the results can different between two users.

Before configuring triggers, we recommend that you try running an export manually to ensure no errors are encountered with the complete dataset.

Auditing
The Audit feature will allow you to see every execution of an export. Each entry will list the following information about each execution:
  1. The trigger that executed the export.
  2. The trigger type.
  3. The time of execution
  4. The resulting status
  5. The message from the export. If successful, it will also list the number of records exported.
Additional information is logged by the server, should more details be required.

The Audit log can be filtered based on trigger, time, or status.

Step 10: Run your Export


Using a scheduled, API trigger, or Run Now to execute your export and access your Clevr form data!



    • Related Articles

    • Bulk Printing

      This page will walk you through how you can bulk print reports in Clevr. Reports can bulk printed in one of two ways: A single PDF file that contains all the printouts grouped together – Download All as a Single PDF Via zip file with all the PDFs ...