Need a special offer?Find out if your project fits.
+
  1. API reference
  • Introduction
  • Connecting to Data Source
  • Browser compatibility
  • 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 MappingObject, which is a property of the DataSourceObject.

    The MappingObject 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, 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.

    This guide contains the following sections:

    Mapping properties

    See the full list of available MappingObject properties.

    Ways to define the mapping

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

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

    As an inline MappingObject

    The inline mapping can be defined as follows:

    report: {
      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:

    report: {
      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.

    Note 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.

    Creating several fields from one field

    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 create several fields, specify the mapping as follows:

    dataSource: {
      mapping: {
        "Date": [
          {
            type: "date",
            uniqueName: "DateHierarchical",
            caption: "Date (hierarchical)"
          },
          {
            type: "date string",
            uniqueName: "DateString",
            caption: "Date (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:

    report: {
      slice: {
        rows: [
          {
            uniqueName: "DateString"
          }
        ],
        ...
      } 
    }

    See a live sample on JSFiddle.

    Defining available aggregations for fields of a certain type

    In JSON and CSV

    Starting from version 2.8.33, you can define available aggregations for fields of a "number", "string", "date", or "time" type.

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

    mapping: {
      aggregations: {
        "number": [ "sum", "average" ],
        "date": [ "max", "min" ],
        "string": [ "count", "distinctcount" ]
      }
    }

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

    • For number fields: "sum" and "average".
    • For date fields: "max" and "min".
    • For string fields: "count" and "distinctcount".

    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.

    In the custom data source API

    When using the custom data source API, specify supported aggregations for a certain field type in the aggregations property of the response to the /fields request.

    Learn more about aggregations in the custom data source API here: Supporting more aggregation functions.

    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.