Step 1: Open the moduleGo 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 ExportA 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 EditorOnce 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 DefinitionThe 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:
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:
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 DefinitionDeveloping 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, DiscardingThere 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 TriggersPlease 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:
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:
| |
Step 9: Run Now and AuditingPlease 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:
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 ExportUsing a scheduled, API trigger, or Run Now to execute your export and access your Clevr form data! |