Arranger Github

Adding a Project

After your Elasticsearch index mapping has been created and supplied, a project must be created in Arranger. The project will reference the mapping and allow an administrator to configure the search filters, result columns, and so on that need to be exposed to the front-end data portal.

There are several parts to this:

  1. Configuring Arranger metadata files in advance (prerequisite)
  2. Adding the project to the Arranger Admin UI
  3. Configuring the project once it is created

NOTE: Although multiple projects can be created and exist in the Arranger Admin UI, currently only ONE project can be actively in use by the front-end data portal at a time. Your UI application must specify in its interactions with Arranger (e.g. queries) which project to use.

Setup Arranger Metadata Files

When creating a new project, several JSON files need to be imported. They describe the metadata configurations for your project. These files need to be created in advance to reflect the fields in your index mapping that need to be configured within Arranger.

For reference, we provide a set of sample JSON files for the default file_centric_1.0 index here as a guide.

The required JSON files are:

FileDescription
aggs-state.jsonConfigures the search filters and aggregations in the data portal's facet panel.
columns-state.jsonConfigures the data columns in the data portal's search results table.
extended.jsonExtended (extra) configurations for your Elasticsearch index mapping.
matchbox-state.jsonConfigures the quick search settings for specified fields in the data portal.

Tip

For your own custom index mapping, you only need to replace the fields in the JSON files with the fields you wish to configure in Arranger. You do NOT need to supply the actual configuration values, since you can do that in the UI once they are imported. Just make sure the JSON files are in the correct format per the default example, but with the list of fields from your own mapping instead of the default ones.

Add Project to Admin UI

To add a new project to the Arranger Admin UI, do the following:

  1. Open your browser and go to the Arranger Admin UI hosted on localhost:8080. The Admin UI is displayed with no projects listed:

Entity

  1. From the Project versions list, click Add Project:
  1. A pop-up control appears. In the Project ID field, enter a Project ID. This must be in snake_case and dashes (-) are not allowed. If you are using the default sample index, you can simply enter file.
  1. Under Project ID, click Add Index. Additional fields appear.
  1. In the Name field, enter a cosmetic name for the index. If you are using the default sample index, you can simply enter file.
  1. In the ES Index field, enter the actual Elasticsearch Alias Name value that you specified in the index_config.json file. If you are using the default sample index, then enter file_centric_1.0.
  1. Click Choose Files, then browse for and select the four (4) JSON metadata files that define your project's default configuration in Arranger. These are the same files you setup earlier above:
  • aggs-state.json
  • columns-state.json
  • extended.json
  • matchbox-state.json
  1. The configuration pop-up should now look like this:

Entity

  1. Click the Add button in the bottom right of the pop-up. Verify that your project is now created and has an entry (row) in the Project versions list:

Entity

  1. You can click the Project ID to browse its configurations and make sure they match the metadata files you uploaded above:

Entity

Configure Project Metadata

For details on how to configure the project metadata, see the relevant sections in the User Guide:

Indexing Data

Once Arranger is completely configured, you will need to index actual data into Elasticsearch so that it can be explored in your data portal.

If you are using Arranger with the full Overture product suite, you can learn how to upload and index data with our DMS platform bundle here.

However, if you are using Arranger and Elasticsearch standalone without other Overture components, you will need to index the data into ES yourself. See the Elastic documentation for guidance.

Arranger Github
  1. Setup Arranger Metadata Files
  2. Add Project to Admin UI
  3. Configure Project Metadata
  4. Indexing Data