Data Export Configuration

Overview

As the Fusion Data Browser talks directly to the web services of the Fusion server it is connected to (Fusion Registry / Fusion Edge Server / other) - the supported export formats are defined by the product.

Rather then presenting a long list or export formats, and lots of choices per format - the export formats included in the Fusion Data Browser are configured per installation, thereby giving control over which formats to present to the user, which parameters to fix, which parameters to allow the user to select.

Export formats and their configurations are maintained in the exportconfig.json file and is located under the properties folder. The file contents will look something like this:

{
 "Parameters" : {
   "DimAtObs" : {
     "Label": "data.export.param.dimatobs",
     "Parameter": "dimensionAtObservation",
     "DimensionOptions" : {
       "IncludeTime" : true,
       "Required" : true
     }
   },
   "Slice" : {
     "Label": "data.export.param.slice",
     "Parameter": "slice",
     "DimensionOptions" : {
       "IncludeTime" : false,
       "Required" : false
     },
   }
   "Detail" : {
     "Label": "Attributes",
     "Parameter": "detail",
     "Options" : [
       {
         "Label" : "Include",
         "Value" :  "full"
       },{
         "Label" : "Exclude",
         "SubText" : "Exclude series and observation attributes",
         "Value" :  "dataonly"
       }
     ]
   }, 
 },
 "ExportFormats" : [
   {
     "Label" : "CSV",
     "Format" : "csv",
     "FixedParameters" : {
       "labels" : "both"
     }
   },
   {
     "Label" : "Excel Series",
     "Format" : "excel-series",
     "Parameters" : ["Slice", "DimAtObs"],
     "FixedParameters" : {
       "labels" : "both"
     }
   }
 ]
}

The file is broken into two main sections: Parameters and ExportFormats.

Parameters

The parameters section enable export parameters to be defined once, and re-used by any number of exports that require them. An export parameter is always a choice which is presented to the user when they opt to export the data in any ExportFormat that makes use of the parameter.

Each parameter has:

• Alias. Used by the ExportFormat in order to reference the parameter.
• Label. Presented to the user in the export data form. This can be a Locale label in the language file, for example data.export.param.slice will resolve to the label Slice in the English language file
• Parameter. This is the REST query parameter that is used when it transmits the parameter in the data query to the server.

Example:

"Detail" : {
  "Label": "Attributes",
  "Parameter": "detail",
  "Options" : [ ... ]

In the above example Detail is the alias, Attributes is the label shown to the user on the export data form. The REST query parameter sent to the server will be detail. If, for example the user selects an option with the Value full then the server will receive the query parameter detail=full

To present the user with a list of values they can choose for the Parameter, there are 2 choices:

1. a fixed list of options
2. a dynamic list of options taken which are derived from the available Dimensions for the dataset being exported.

Fixed List Parameters

Fixed list parameters are defined in the Options array. Each Option has the following properties:

• Label - required, this is the label in the drop down
• SubText - optional property, if provided it will appear in the select option next to the label as a smaller sub-text label
• Value - the value that will be passed to the server if this option is selected, an empty string is used to indicate do not pass this parameter

Labels may be defined as properties in the language file.

"Detail" : {
  "Label": "Attributes",
  "Parameter": "detail",
  "Options" : [
     {
       "Label" : "Include",
       "Value" :  "full"
     },
     {
       "Label" : "Exclude",
       "SubText" : "Exclude series and observation attributes",
       "Value" :  "dataonly"
     }
  ]
}

Dimension Parameters

This parameter presents the user with a list of Dimensions to pick from. This is useful for formats which include parameters such as 'dimensionAtObservation' or 'slice' for example excel-ts.

The options are expressed using the DimensionOption property.

"Slice" : {
    "Label": "data.export.param.slice",
    "Parameter": "slice",
    "DimensionOptions" : {
      "IncludeTime" : false,
      "Required" : false
 }

DimensionOptions has 2 properties:

1. IncludeTime - if true, and the Data Structure Definition has a Time Dimension, this will be included in the choice of Dimensions
2. Required - if true, then the select will only include the Dimensions as a choice, defaulting to the first in the list. If false, then the first item in the list is a "-" to indicate that no Dimension was selected for this property

Attribute Parameters

This parameter presents the user with a list of Attributes to pick from. This is useful if using the attributes parameter.

The options are expressed using the AttributeOptions property.

"Slice" : {
    "Label": "data.export.param.attributes"
    "Parameter": "attributes",
    "AttributeOptions" : {
      "Relationship" : ["series"]
      "Required" : false
 }

AttributeOptions has 2 properties:

1. Relationship - if provided this array will only include attributes that have this relationship with the data. Options are 'series', 'obs', 'dataset'
2. Required - if true, then the select will only include the Dimensions as a choice, defaulting to the first in the list. If false, then the first item in the list is a "-" to indicate that no Dimension was selected for this property

Export Formats

The ExportFormats section of the configuration file contains an array of formats that will be presented to the user when they choose to export data. Each export format has the following properties:

• Label - The name given to the export format, shown to the user in the drop down selection. Like other labels, this can reference a property in the language configuration file if multilingual labels are required.
• Format - The format query parameter passed to the server. Refer to the appropriate page to lookup this value.
• Parameters - An array of references to the Parameters described in the Parameters section.
• FixedParameters - Any parameters with a single, fixed value. These used in the data query request to the server and are not presented to the user, and therefore cannot be modified by the user.

Note: An export format can contain zero to many Parameters FixedParameters as required, but each format definition should only include parameters which are supported by the chosen data format. Please refer to the appropriate Data Format to lookup valid parameters for the format.

{
     "Label" : "Excel Series",
     "Format" : "excel-series",
     "Parameters" : ["Slice", "DimAtObs"],
     "FixedParameters" : {
       "labels" : "both"
     }
   }

Excel Table Export Format

One notable export format is the Excel Table format, defined by the Format property of excel-table. This is used by the Fusion Data Browser's Pivot table, where the table rows and column headers are determined by the layout of their data table. When the user downloads from the Data Table page, the format definition is dynamically created based on their table layout. This export format may also be included in the list of formats in the export configuration file, if this is the case, the export format will be used as a template which is overlayed with the user's own pivot table properties.

For example the following export format defines the excel-table format as follows:

{
  "Label": "data.export.format.excel-table",
  "Format": "excel-table",
  "Parameters" : ["Slice"],
  "FixedParameters" : {
    "readable" : "false",
    "detail" :  "dataonly",
    "labels" : "both"
  }
}

The following format definition will present to the user a choice of Slice (in this example Slice will be the Dimensions which make up the worksheets in the Excel output). The format will also fix the properties for labels, detail, and will not be readable (i.e. the output file cannot be loaded back into the Fusion Registry as it will not contain the required metadata to do so). When the user creates a pivot table in the data browser, the values for the rows and columns are based on the user's Pivot table layout, and will be added to this definition. The user may also opt to change the column headings on some Dimensions to include Ids and Labels, or just Ids - this will override any setting for labels in the above definition.

If a definition for excel-table is not included in the export configuration file, a basic configuration will be created automatically when the user exports from the pivot table page.