🍉 Meet Flexmonster Pivot Table & Charts 2.9.Check out all hot features!
Get Free Trial
  1. API reference
  2. Welcome
    1. Getting started
    2. Get Flexmonster
    3. Quick start
    4. System requirements
    5. Troubleshooting
    6. Managing license keys
    7. Migrating from WebDataRocks to Flexmonster
  3. Integration with frameworks
    1. Available tutorials
    2. Integration with Angular
    3. Integration with React
    4. Integration with Vue
    5. Other integrations
      1. Integration with Python
        1. Integration with Django
        2. Integration with Jupyter Notebook
      2. Integration with React Native
      3. Integration with AngularJS (v1.x)
      4. Integration with TypeScript
      5. Integration with R Shiny
      6. Integration with jQuery
      7. Integration with Ionic
      8. Integration with Electron.js
      9. Integration with Webpack
      10. Integration with RequireJS
  4. Connecting to Data Source
    1. Supported data sources
    2. JSON
      1. Connecting to JSON
      2. Connecting to JSON using Flexmonster Data Server
      3. Data types in JSON
    3. CSV
      1. Connecting to CSV
      2. Connecting to CSV using Flexmonster Data Server
      3. Data types in CSV
    4. Database
      1. Connecting to SQL databases
      2. Connecting to a MySQL database
      3. Connecting to a Microsoft SQL Server database
      4. Connecting to a PostgreSQL database
      5. Connecting to an Oracle database
    5. Flexmonster Data Server
      1. Introduction to Flexmonster Data Server
      2. Getting started with Flexmonster Data Server
      3. Flexmonster Admin Panel Guide
      4. Data sources guide
      5. Security and authorization guide
      6. The Data Server as a DLL
        1. Getting started with the Data Server as a DLL
        2. Referencing the Data Server as a DLL
        3. Implementing the API controller
        4. Implementing the server filter
        5. Implementing the custom parser
        6. DLL configurations reference
        7. The controller's methods for request handling
      7. The Data Server as a console application
        1. Installing the Data Server as a console application
        2. Configurations reference
        3. Data sources guide
        4. Security and authorization guide
      8. Troubleshooting the Data Server
    6. MongoDB
      1. Introduction to Flexmonster MongoDB Connector
      2. Getting started with the MongoDB Connector
      3. Embedding the MongoDB Connector into the server
      4. Configuring the MongoDB Connector
    7. Microsoft Analysis Services
      1. Connecting to Microsoft Analysis Services
      2. Getting started with Flexmonster Accelerator
      3. Referencing the Accelerator as a DLL
      4. Configuring the authentication process
      5. Configuring a secure HTTPS connection
      6. Troubleshooting
    8. Custom data source API
      1. Introduction to the custom data source API
      2. A quick overview of a sample Node.js server
      3. A quick overview of a sample .NET Core server
      4. Implement your own server
        1. Implementing the custom data source API server
        2. Implementing filters
        3. Supporting more aggregation functions
        4. Supporting multilevel hierarchies
        5. Returning data for the drill-through view
        6. Testing your custom data source API server
    9. Elasticsearch
      1. Connecting to Elasticsearch
      2. Configuring the mapping
    10. Pentaho Mondrian
      1. Connecting to Pentaho Mondrian
      2. Getting started with the Accelerator
      3. Configuring Mondrian roles
      4. Configuring username/password protection
      5. Configuring a secure HTTPS connection
      6. Troubleshooting
    11. Connecting to other data sources
  5. Accessibility
    1. Accessibility overview
    2. Keyboard navigation
  6. Configuring report
    1. What is a report
    2. Data source
    3. Slice
    4. Options
    5. Mapping
    6. Number formatting
    7. Conditional formatting
    8. Set the report for the component
    9. Get the report from the component
    10. Share the report
    11. Date and time formatting
    12. Configuring global options
    13. Export and print
    14. Calculated values
    15. Custom sorting
  7. Charts
    1. Available tutorials
    2. Flexmonster Pivot Charts
    3. Integration with Highcharts
    4. Integration with amCharts
    5. Integration with Google Charts
    6. Integration with FusionCharts
    7. Integration with any charting library
  8. Customizing
    1. Available tutorials
    2. Customizing the Toolbar
    3. Customizing appearance
    4. Customizing the context menu
    5. Customizing the grid
    6. Customizing the pivot charts
    7. Localizing the component
  9. Security
    1. Security in Flexmonster
    2. Security aspects of connecting to an OLAP cube
      1. Ways of connecting to an OLAP cube
      2. The data transfer process
      3. Data security
      4. Data access management
  10. Updating to the latest version
    1. Updating to the latest version
    2. Release notes
    3. Migration guide from 2.8 to 2.9
    4. Migration guide from 2.7 to 2.8
    5. Migration guide from 2.6 to 2.7
    6. Migration guide from 2.5 to 2.6
    7. Migration guide from 2.4 to 2.5
    8. Migration guide from 2.3 to 2.4
    9. Migration guide from 2.2 to 2.3
  11. Flexmonster CLI Reference
    1. Overview
    2. Troubleshooting the CLI
    3. flexmonster create
    4. flexmonster add
    5. flexmonster update
    6. flexmonster version
    7. flexmonster help
  12. Documentation for older versions
Table of contents

Mapping

Mapping is the process of defining how fields contained in the data source are treated and presented within the component. For mapping in Flexmonster, you can use the Mapping object, which is a property of the Data Source.

The Mapping object is available for all data sources but with some differences.

For JSON, CSV, and the custom data source API, it’s possible to define field data types and captions, group fields under separate dimensions, create multilevel hierarchies, and more. For SSAS and Mondrian data sources, it’s possible to set captions for dimensions and measures. For data from Elasticsearch, it’s possible to customize hierarchy captions, formats, time zones, control field visibility, and more.

We recommend using mapping instead of defining a meta-object for JSON or adding prefixes for CSV data since the former presents a powerful way to neatly separate a data source from its representation. Moreover, mapping provides more options than using prefixes for CSV data.

This guide contains the following sections:

Mapping properties

The Mapping object has the following properties:

  • (uniqueName) – Object | Array of objects. Allows setting the mapping for a specific field from the dataset. (uniqueName)is the field’s unique name.
    Specify the mapping as an object to set it for a certain field. See an example on JSFiddle.
    For "json" and "csv" data source types, it is possible to create several fields from a certain field. It can be done by specifying the mapping as an array of objects, where each object is a new field. Learn more in our guide.
    Each object can have the following properties:
    • caption (optional) – String. The hierarchy’s caption.
    • type (optional) – String. The field’s data type. Only for "json", "csv", and "api" data source types. type can be:
      • "string" – The field stores string data.
      • "number" – The field stores numerical data. It can be aggregated with all available aggregations.
      • "month" – The field stores months. Note that if the field stores month names only (in either short or full form), the field will be recognized by Flexmonster as a field of the "month" type automatically. If the field contains custom month names, specify its type as "month" explicitly.
      • "weekday" – The field stores days of the week.
      • "date" – The field stores a date. Fields of this type are split into 3 different fields: Year, Month, Day. Only for "json" and "csv" data source types.
      • "year/month/day" – The field stores a date. It’s displayed as a multilevel hierarchy with the following levels: Year > Month > Day. Only for "json" and "csv" data source types.
      • "year/quarter/month/day" – The field is a date. It’s displayed as a multilevel hierarchy with the following levels: Year > Quarter > Month > Day. Only for "json" and "csv" data source types.
      • "date string" – The field stores a date. Fields of this type are represented as strings and can be used in rows, columns, or report filters. The component sorts members of such a field as dates.
        Fields of the "date string" type can be formatted using the datePattern option (the default pattern is "dd/MM/yyyy").
      • "datetime" – The field stores a date. You can select fields of this type for values and apply min, max, count, and distinctcount aggregations to them.
        Fields of the "datetime" type can be formatted using the dateTimePattern option (the default pattern is "dd/MM/yyyy HH:mm:ss").
      • "time" – The field stores time. Fields of this type can be formatted using the timePattern option (the default pattern is "HH:mm:ss").
      • "id" – The field is an id. This field is not shown in the Field List. Fields of this type can be used for editing data.
      • "property" – The field for setting member properties. This field is not shown in the Field List. For example, it can be used to associate a productID with a product. See an example here.
    • hierarchy (optional) – String. The hierarchy’s name. When configuring hierarchies, specify this property to mark the field as a level of a hierarchy or as a member property of a hierarchy (in this case, the type parameter should be set to "property"). Only for "json", "csv", and "api" data source types.
      See how to configure multilevel hierarchies.
    • parent (optional) – String. The unique name of the parent level. This property is necessary if the field is a level of a hierarchy and has a parent level. Only for "json", "csv", and "api" data source types.
      See how to configure multilevel hierarchies.
    • folder (optional) – String. The field’s folder. Folders are used to group several fields in the Field List. folder supports nesting via / (e.g., "Folder/Subfolder/"). Only for "json", "csv", and "api" data source types.
    • aggregations (optional) — Array of strings. This property represents the list of aggregation functions that can be applied to the current measure.
    • filters (optional) – Boolean. This property allows enabling and disabling the UI filters for a specific hierarchy. When set to false, the UI filters are disabled. Default value: true.
    • visible (optional) – Boolean. When set to false, hides the field from the Field List. Only for "elasticsearch", "json", "csv", and "api" data source types.
    • interval (optional) – String. Allows rounding down dates by the given interval. For example, if the interval is "1d", 2021-05-25T21:30:00 will be rounded to 2021-05-25T00:00:00. See an example on JSFiddle.
      The interval property can be used in the following ways:
      • For the date histogram in Elasticsearch. Check out supported time units. Only for the "elasticsearch" data source type.
      • For the "date string" and "datetime" field types. Supported date intervals are the following:
        • "y" for one year (e.g., "y").
        • "q" for one quarter (e.g., "q").
        • "M" for one month (e.g., "M").
        • "w" for one week (e.g., "w").
        • "d" for days (e.g., "1d"). Note that rounding by days starts from 1 January 1970.
        • "h" for hours (e.g., "7h").
        • "m" for minutes (e.g., "20m").
        • "s" for seconds (e.g., "30s").
        Note that "y", "q", "M", and "w" intervals should be used without numbers. Only for "csv" and "json" data source types.
    • isMeasure (optional) – Boolean. When set to true, the field can be selected only as a measure. The isMeasure property should be used only with the strictDataTypes option (see an example on JSFiddle). Only for the "json" data source type. Default value: false.
    • time_zone (optional) – String. Used for the date histogram. You can specify time zones as either an ISO 8601 UTC offset (e.g., +01:00 or -08:00) or as a time zone ID as specified in the IANA time zone database, such as America/Los_Angeles. Only for the "elasticsearch" data source type. Check out an example here.
    • format (optional) – String. Used to format different types of date fields. format can be used in the following ways:
      • For the date histogram in Elasticsearch. The date format/pattern is described in the Elasticsearch documentation. Try a live sample on JSFiddle.
        If the datePattern option is defined, format will override its value for the field.
        Only for the "elasticsearch" data source type.
      • For a field of the "date string" type, it allows overriding the datePattern set in the Options Object. The pattern string for the format is the same as in the datePattern option (i.e., "dd/MM/yyyy"). Only for "json", "csv", and "api" data source types. Learn more about date and time formatting.
      • For a field of the "datetime" type, it allows overriding the dateTimePattern set in the Options Object. The pattern string for the format is the same as in the dateTimePattern option (i.e., "dd/MM/yyyy HH:mm:ss"). Only for "json", "csv", and "api" data source types. Learn more about date and time formatting.
      • For a field of the "time" type, it allows overriding the timePattern set in the Options Object. The pattern string for the format is the same as in the timePattern option (i.e., "HH:mm:ss"). Only for "json", "csv", and "api" data source types. Learn more about date and time formatting.
    • min_doc_count (optional) – Number. Only for the "elasticsearch" data source type. Used for the date histogram. Can be used to show intervals with empty values (min_doc_count: 0). Default value: 1 (empty intervals are hidden).
  • aggregations (optional) – Object. Supported aggregation functions for all fields of a certain type. See an example on JSFiddle. Only for "json" and "csv" data source types.
    Supported aggregations for a certain field can be defined in the [field_name].aggregations property.
    The aggregations object can have the following properties:
    • date (optional) – Array of strings. Supported aggregation functions for the "date string" field type.
    • number (optional) – Array of strings. Supported aggregation functions for the "number" field type.
    • string (optional) – Array of strings. Supported aggregation functions for the "string" field type.
    • time (optional) – Array of strings. Supported aggregation functions for the "time" field type.
    See a list of supported aggregations in Flexmonster’s technical specifications.

Ways to define the mapping

In Flexmonster, there are two ways to define the mapping: 

  1. As an inline Mapping Object.
  2. As a URL to a JSON file with the mapping.

As an inline Mapping Object

The inline mapping can be defined as follows:

{
dataSource: {
filename: "data.csv",
mapping: {
"Month": {
"type": "month"
},
"Company Name": {
"type": "string"
},
"Region": {
"type": "string",
"hierarchy": "Geography"
},
"State": {
"type": "string",
"parent": "region",
"hierarchy": "Geography"
},
"Price": {
"type": "number",
"caption": "Unit Price"
}
}

}
}

See the full code on JSFiddle.

As a URL to a JSON file with the mapping

To define the mapping as a URL to a file, complete the steps below.

Step 1. Create a new JSON file with the mapping (e.g., mapping.json). Its contents should look similar to the following:

{
"Month": {
"type": "month"
},
"Company Name": {
"type": "string"
},
"Region": {
"type": "string",
"hierarchy": "Geography"
},
"State": {
"type": "string",
"parent": "region",
"hierarchy": "Geography"
},
"Price": {
"type": "number",
"caption": "Unit Price"
}
}

Step 2. Put your mapping file where Flexmonster can access it.

Step 3. In Flexmonster, define the mapping as a URL to your file:

{
dataSource: {
filename: "data.csv",
mapping: "<URL_to_your_mapping_file>"
}
}

See a live sample on JSFiddle.

Configuring multilevel hierarchies

Using the mapping, you can create multilevel hierarchies from non-hierarchical data. This feature is supported for JSON, CSV, Flexmonster Data Server, MongoDB, and custom data source API.

In the custom data source API, multilevel hierarchies should be supported on the server side as well. Learn more in this guide: Supporting multilevel hierarchies.

To configure multilevel hierarchies in the component, specify the hierarchy and parent properties in the mapping.

The example below illustrates how to configure multilevel hierarchies. We create the "Geography" hierarchy with the "Country" field as a first level, "State" field as a second level, and "City" field as a third level:

report: {
    dataSource: {
        filename: "data.json",
        mapping: {
           "Country": {
                hierarchy: "Geography",
            },
           "State": {
                hierarchy: "Geography",
                parent: "Country"
            },
           "City": {
                hierarchy: "Geography",
                parent: "State"
            }
        }

   }
}

See a live example on JSFiddle.

Splitting one field into several fields

Starting from version 2.9, you can create multiple fields from one field and use them separately in the slice. This feature is available for JSON and CSV data sources.

To split a field, specify the mapping as follows:

{
   "mapping": {
    "Price": [
        {
            "type": "number",
            "uniqueName": "PriceNumber",
            "caption": "Price as Number"
        },
        {
            "type": "string",
            "uniqueName": "PriceString",
            "caption": "Price as String"
        }
    ],
    ...
}
}

Notice that instead of an object, we used an array of objects as a mapping value. Each object describes a separate field that will be created.

Every new field should have its own uniqueName property. As for other mapping properties, you can use any property available for your data source.

After you have defined the needed fields, you can include them in the slice as ordinary fields:

{
...
"slice": {
        "rows": [
            {
                "uniqueName": "Category"
            }
        ],
        "columns": [
            {
                "uniqueName": "Color"
            },
            {
                "uniqueName": "[Measures]"
            }
        ],
        "measures": [
            {
                "uniqueName": "PriceNumber"
            }

        ]
    }, 
   ...
}

See a live sample on JSFiddle.

Defining available aggregations for all fields of a certain type

Starting from version 2.8.33, you can define available aggregations for all fields of a "number", "string", "date", or "time" type. This feature is supported for "json" and "csv" data source types.

For the custom data source API, it is also possible to define supported aggregations for all fields of a certain type. It can be done in the aggregations property of the /fields request.

To define aggregations for a certain field type, specify an array with them in the aggregations.[field_type] property. For example:

"mapping": {
"aggregations": {
"string": [ "count" ],
"date": [ "min" ],
"time": [ "max" ],
"number": [ "max", "min" ]
}
}

See the full code on JSFiddle. As a result, the following aggregations will be available:

  • For string fields: "count".
  • For date fields: "max".
  • For time fields: "min".
  • For number fields: "max" and "min".

It’s not necessary to define aggregations for all field types. If a type is not listed in the aggregations property, a field of this type will have aggregations available by default.

Other ways to customize field presentation

Another way to define how the fields are displayed in the report is by configuring this right in the data source. Please note that this approach is available only for CSV and JSON data sources. For more details, please refer to the Data types in CSV and Data types in JSON articles. It also should be noted that there are certain limitations for the CSV data source – not all the field properties can be customized using prefixes.

For this reason, we strongly recommend using the Mapping Object to customize fields.

Examples

1) Creating multilevel hierarchies in JSON:

mapping: {
"Color": {
type: "string"
},
"Country": {
type: "string",
hierarchy: "Geography"
},
"State": {
type: "string",
hierarchy: "Geography",
parent: "Country"
},
"City": {
type: "string",
hierarchy: "Geography",
parent: "State"
},
"Price": {
type: "number"
}
}

Try the live demo on JSFiddle.

2) Setting custom captions and field data types as well as creating multilevel hierarchies in a CSV data source:

mapping: {
"Order ID": { "type": "string" },
"Month": { "type": "month" },
"Company Name": { "type": "string" },
"Customer": { "type": "string" },
"region": {
"caption": "Region",
"type": "string",
"hierarchy": "Geography"
},
"State": {
"type": "string",
"parent": "region",
"hierarchy": "Geography"
},
"City": {
"type": "string",
"parent": "State",
"hierarchy": "Geography"
},
"Salesperson": { "type": "string" },
"Payment Method": { "type": "string" },
"Category": { "type": "string" },
"Name": { "type": "string", "caption": "Product Name" },
"price": { "type": "number", "caption": "Unit Price" },
"Quantity": { "type": "number" },
"Revenue": { "type": "number" },
"Shipping Cost": { "type": "number" }
}

Try it on JSFiddle.

3) Setting custom captions and grouping fields in separate folders in a JSON data source:

mapping: {
"Color": {
caption: "color"
},
"Country": {
caption: "MyCountry",
folder: "Place"
},
"State": {
caption: "MyState",
folder: "Place"
},
"City": {
caption: "MyCity",
folder: "Place"
},
"Price": {
type: "number",
caption: "MyPrice"
},
"Quantity": {
type: "number",
caption: "MyQuantity"
}
}

See the live demo on JSFiddle.

4) Specifying custom captions for hierarchies and measures for SSAS:

mapping: {
"[Geography].[Geography]": {
caption: "My Geography"
},
"[Product].[Category]": {
caption: "My Category"
}
}

See the live demo on JSFiddle.