Mapping

The mapping defines how fields from the data source are treated and presented within the component. 

The mapping is described by the MappingObject, where each key is the field’s unique name, and a value is the FieldMappingObject. The FieldMappingObject contains properties that will be applied to the field.

To see different examples of using the mapping, visit our Examples page.

Usage

You can define the mapping for all data sources but with some differences:

• For JSON, CSV, Flexmonster Data Server, MongoDB, and the custom data source API, you can define field data types and captions, group fields under separate dimensions, create multilevel hierarchies, and more.
  Note If you use Flexmonster Data Server, it is also possible to define field data types on the server.
• For SSAS, you can set captions for dimensions and measures. 
• For Elasticsearch, you can customize hierarchy captions, formats, time zones, control field visibility, and more. Read more about configuring the mapping in Elasticsearch.

Mapping properties

See the full list of available MappingObject properties.

How to define the mapping

You can define the mapping in the following ways:

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

As an inline MappingObject

The mapping can be defined as an inline MappingObject in the following way:

report: {
  dataSource: {
    filename: "data.csv",
    mapping: {
      "Month": {
        type: "month"
      },
      "Company Name": {
        type: "string"
      },
      "Region": {
        type: "string",
        hierarchy: "Geography"
      },
      // ...
    }
  }
}

Live example

As a URL to a file

To define the mapping as a URL to a file, follow the steps below:

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

{
  "Month": {
    "type": "month"
  },
  "Company Name": {
    "type": "string"
  },
  "Region": {
    "type": "string",
    "hierarchy": "Geography"
  },
  // ...
}

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

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

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

Live example

Use cases

Specify a caption for a field

By default, a caption is a field’s uniqueName. To specify the field’s custom caption, use the [field_name].caption property:

report: {
  dataSource: {
    filename: "data.csv",
    mapping: {
      "item_price": {
        caption: "Price"
      },
      // Other fields
    }
  }
}

Live example

Define the type of a field

By default, Flexmonster autodetects the field types. To set a data type for a field manually, use the [field_name].type property:

report: {
  dataSource: {
    filename: "data.csv",
    mapping: {
      "Month": {
        type: "month",
      }
    }
  }
}

Live example

Hide a field in the component

To hide a field in the component, set the [field_name].visible property to false:

report: {
  dataSource: {
    filename: "data.csv",
    mapping: {
      "Country": {
        visible: false,
      }
    }
  }
}

As a result, the "Country" field will be hidden on the grid, charts, and in the Field List Live example.

Group several fields in a folder

To group several fields in the Field List, use the [field_name].folder property:

report: {
  dataSource: {
    filename: "data.csv",
    mapping: {
      "Country": {
        folder: "Place",
      },
      "State": {
        folder: "Place",
      },
      "City": {
        folder: "Place",
      }
    }
  }
}

Live example

Format a date field

To format a specific date field, use the [field_name].format property:

report: {
  dataSource: {
    data: [
      // ...
    ],
    mapping: {
      "OrderDate": {
        type: "date string",
        format: "MM/dd/yyyy"
      }
    }
  }
}

Live example

Learn more about date and time formatting.

Define available aggregations for a field

Each field has a list of available aggregations based on the field’s type. You can limit the list to aggregations you need by specifying them in the <uniqueName>.aggregations property:

report: {
  dataSource: {
    filename: "data/data.csv",
    mapping: {
      "Price": {
        aggregations: ["max", "min"]
      }
    }
  }
}

Live example

Configure 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. See how to support multilevel hierarchies.

To configure multilevel hierarchies, specify the [field_name].hierarchy and [field_name].parent properties in the mapping.

In the example below, we create the "Geography" hierarchy with the "Country" field as the first level, the "State" field as the second level, and the "City" field as the third level:

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

Live example

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 from one field, 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 we use an array of FieldMappingObjects as a mapping value for the "Date" field. Each FieldMappingObject describes a separate field that will be created in the component.

Each created field should have a unique value for the uniqueName property. Specify other mapping properties as usual.

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

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

Live example

Defining available aggregations for fields of a certain type

report: {
  dataSource: {
    filename: "data.json",
    mapping: {
      aggregations: {
        number: [ "sum", "average" ],
        date: [ "max", "min" ],
        string: [ "count", "distinctcount" ]
      }
    }
  }
}

What’s next?

• Mapping examples
• Configuring the slice
• Number formatting
• Date and time formatting
• Manage Flexmonster’s functionality