About custom configurations

Custom configurations are a powerful tool for customization in Mapeo, allowing users to define specific categories, icons, and questionnaires for their projects. Custom category and questionnaire text can be written in any language that can be typed, ensuring that key parts of the Mapeo data collection interface can appear in the native language of the groups using it.

In the current version of Mapeo, configurations also contain a project key that allows participants of the same Mapeo project to synchronize data with each other and prevents synchronization with other devices. ​

Creating custom configurations

If you have determined that Mapeo's Default configuration will not suit the needs of your project, you have the option of authoring a custom configuration.

The customization process, detailed in Creating custom configurations, requires comfort editing JSON files, generating SVG image files, and using GitHub Actions or installing and using node packages via the command line.

Overview of the process

There are several steps to creating a custom configuration that will require different skills and the involvement of different actors within a project. You should leave plenty of time prior to the intended start of data collection to allow for community consultation, testing, and iterations of your configuration.

While data structures in Mapeo can be modified during the course of a project, many changes over time can result in messy data outputs. It is worthwhile to test and refine your configuration to the extent possible before putting it into use for data collection.

Once you have completed this process, you will have a Mapeo configuration file (.mapeosettings) that can be imported and used in Mapeo Mobile and Destop.

The pages that follow will walk you through the key steps for authoring a custom configuration:

• Planning configuration & data structure This section will outline the key customizable elements in a configuration and some considerations when mapping out each area. *No technical knowledge is required.

• Coding configuration This section will guide you through translating the planned data structure into the required format and compiling the Mapeo configuration file. *Editing JSON files, generating .svg files and working with command line or GitHub is required.

Though some key steps of coding configurations require technical skills, initial planning and consultation with project participants is essential to designing effective data structures and does not require coding skills.

To start the customization process, project participants should reflect on the project goals, what kind of data will be needed, and what properties might be required for data outputs.

If you have not already done so, work through the What information to collect? section of this guide as a first step.

Data structure

When planning your configuration, you will need to think through what to include for each of the key customizable areas of Mapeo. The pages that follow will walk you through some considerations when determining content for each area:

• Categories When collecting or creating data with Mapeo, users assign a top-level category to each observation or element on the map.

• Icons Each category you include must have an icon, or a small graphic to display to users when selecting a category.

• Details fields (optional) For each category in your configuration, you can include one or more structured data fields (like a mini form or questionnaire) that users can optionally fill out when creating a new observation or map element with that category.

Documenting data structure

In order to create a Mapeo configuration file, the information you map out for the above areas will need to be translated into JSON files and .svg image files and then compiled. The details of this process will be covered in Coding configuration.

If you do not have the technical skills required to code the configuration yourself, the information you define in the following pages for for Categories, Icons and Details fields can be documented and passed off to a developer or individual with technical skills to code and compile the configuration file.

What are categories?

When collecting or creating data with Mapeo, each observation or element on the map is assigned a category. Users must select a single category when creating a new observation or map element. Categories can be broad or specific, depending on your context and project needs.

How categories are viewed in Mapeo

Categories list in Mapeo Mobile (using the default configuration):

Categories list in the Filters panel of Mapeo Desktop (using the default configuration):

Considerations when defining categories

For each category you choose to include in your configuration, you'll need to determine the following:

• Name The label users will see in Mapeo when viewing or selecting the category

• Geometry Each element on the map will be marked as a point, line (eg. a path), or area (eg. a zone or lake). You will need to determine which of these geometries users will be able to use for each category.

  • All data collected with Mapeo Mobile will be points. If you are using Mapeo Mobile, you should include point as a geometry for every category.

  • If you are using Mapeo Desktop Territory mode as part of your project, you can also include line or area for categories where relevant.

• Color (optional) You have the option of setting a custom color for the map dots or markers for each category in Mapeo Mobile and Mapeo Desktop Observations mode.

• Sort order (optional) You have the option of determining the order in which you would like categories to appear on the Mapeo Mobile Categories screen (pictured above). If no order is added, categories will appear alphabetically by name.

When defining categories, keep in mind the following:

• Categories are one of the key ways data can be filtered in Mapeo. Thinking through how you will view and use data once it has been created offers useful perspective when defining categories.

• As a general rule, categories should not overlap - users should see only one option that fits when making a selection.

• Categories and what would fall within them should be clear to those who will be collecting data. Training and information sessions may be critical for ensuring that project participants know how to gather data in consistent ways, but clarity and simplicity in configuration authoring goes a long way.

• The space available to display category names is limited, especially in Mapeo Mobile, so names should be generally be brief.

Generating category files

All information you define for categories will be formatted in JSON in the Coding configuration process, detailed in the following section.

What is an icon?

Each of the categories you include in your configuration needs to be assigned an icon, or a small graphic to display to users when selecting a category. You can assign the same icon to various cateogries, or each category can have it's own icon.

How icons are viewed in Mapeo

Categories list with icons in Mapeo Mobile (using the default configuration):

Examples of the icon files from our default configuration can be found here.

Considerations when designing icons

Though creating the .svg icon files requires some knowledge of image editing tools, sketching and brainstorming ideas for icons can be a great way to involve community members and project participants who may not have technical skills. With paper and pencils, groups can come up with ideas for icons to represent each category in your project.

If you're not up for designing your own icon images, there are libraries of images online with Creative Commons licenses that you can draw from.

When designing icons, keep in mind the following:

• Icons are displayed as very small images in Mapeo Mobile (24x24px) and Mapeo Desktop (100x100px). Very simple designs with minimal detail will render more clearly to users.

  • When thinking about size and scale, imagine drawing your icons with a marker on a dime.

• Bold and solid-color lines and shapes will be most clearly visible.

Generating icon files

Once you've settled on the design or concept for your icons, you'll need to generate .svg files required to include as part of the Coding configuration process.

To do so, you can use our online Mapeo Icons Generator, here.

Or, jump to Creating and exporting SVG files using Adobe Illustrator or Creating and exporting SVG files using Inkscape for technical guidelines in generating your own suitable SVG files.

What are details fields?

For each category in your configuration, you can include one or more structured data fields (like a mini form or questionnaire) that users can optionally fill out when creating a new observation or map element with that category. Details fields can be text fields (type in your own answer) or multiple choice (select one or select many from a set of pre-defined answers).

How details fields are viewed in Mapeo

Details field screen displayed during data collection with Mapeo Mobile:

Considerations when defining details fields

When planning your data structure, you should think through which (if any) details fields you would like to include for each category. The same details field can be used for many categories.

For each details field you would like to include, you'll need to define the following:

• Label The primary text to be displayed to users ("Name" in the above image).

• Placeholder A hint or subtext that can clarify the field to users or provide guidance on how to use it ("Common name of this place" in the above image).

• Field type How users will be able to enter information for the field or question.

  • Text or type in your own answer (Pictured in the image above)

  • Select one from a list of options

  • Select multiple from a list of options

  • Options For Select one and Select multiple fields, you will need to define a list of possible answers to display.

When defining details fields, keep in mind the following:

• It can be very challenging for users to type in detailed information when collecting data in the field. Users may be under significant stress, in risky situations, or interacting with the Mapeo screen in bright sun or rain. When creating Text fields, keep in mind the conditions users will be facing and have reasonable expectations for the amount of detail and work required to fill out your details fields.

• If there are a consistent set of answers you can anticipate for a field or question, it can be much faster or easier for users to select from a list as part of a Select one or Select multiple field. Please note that there is no automatic option for typing in information for "Other" or an option not included in the list.

• It may be very clear to you when authoring your configuration what each details field means or intends to communicate. Keep in mind, however, who will be collecting data as part of your project and how they might read or interpret each field. Very clear and explicit language can go a long way towards ensuring your configuration is used as intended.

• Mapeo Desktop currently allows you to filter observations by options in Select one fields. To filter by options in Select multiple or Text fields, you will need to export your data and view it in another software tool.

Generating details field files

All information you define for details fields will be formatted in JSON in the Coding configuration process, detailed in the following section.

Mapeo configuration files (.mapeosettings) are compiled from a set of files and folders that contain all the information Mapeo needs to display the categories, icons and details fields you want users to see when collecting and viewing data. This section will walk you through translating all of the information you've defined in Planning configuration & data structure into a Mapeo configuration file.

Configuration folder structure

To begin preparing your files, you can download or clone our default configuration repository or this empty configuration repository from GitHub. These repositories contain the core files and folders you will need for editing.

When authoring custom configurations, you will edit files within the following configuration folders:

• icons

• fields

• presets (categories)

And the following configuration files:

• metadata.json

• defaults.json

• package.json

Prepare folder structure

Using the file explorer

1. Download the default configuration repository or empty configuration repository.

2. Unzip the contents to a new folder using a program like 7zip.

3. Rename the folder from "mapeo-default-settings" to use your own project name, "mapeo-config-projectname".

Using the terminal (linux and mac)

wget https://github.com/digidem/mapeo-default-settings/archive/v2.1.0.zip 
unzip v2.1.0.zip 
mv mapeo-default-settings-v2.1.0 mapeo-settings-myprojectname

Once you've settled on the design or concept for your icons, you'll need to generate .svg files for each one to be saved in the icons directory. Icons should be created as 100x100 pixel graphics that are clear when viewing at 100%.

To generate .svg icons for Mapeo, there is an online Mapeo Icons Generator tool accessible here.

We have also documented two workflows to generate Mapeo-compatible .svg files using software, one using a commercial product (Adobe Illustrator) and another using a open-source product (Inkscape).

• Creating and exporting SVG files using Adobe Illustrator

• Creating and exporting SVG files using Inkscape

Naming icon files

Icons need to be read by MAPEO in two sizes: 100 pixels and 24 pixels. For that reason there is a specific file naming convention:

• icon-name-100px.svg

• icon-name-24px.svg

Each icon can be duplicated and renamed so that there is one of each size. They are opened and read by the .json files in the presets folder. Verify that name is correctly entered where needed (more on this in the next section). The build script will process the pixel size suffix.

Additional resources

• Troubleshooting SVG image errors in Mapbox Studio

Adobe Illustrator is a vector graphics editor and design program developed by Adobe Inc. Although it is a commercial, licensed product, it is very commonly used to put together vector graphics, and many users utilize this tool for creating icons for Mapeo as well.

Exporting .svg files with the right properties

When you're ready to export a vector graphic file into a Mapeo-compatible .svg file format, the process is as follows:

• On the Adobe Illustrator top menu, click on File and then select Export, followed by Export As.

• Ensure that Use Artboards is checked.

• Save your .svg file in the correct directory (icons for Mapeo configurations) and with your desired filename, and click Export.

• In the following window, ensure that the following properties are set, and then click OK:

Your .svg file should now be ready to be used by Mapeo. See Naming icon files for more information on how to name the files and where to place them in the configuration directory.

Inkscape is a free and open-source vector graphics editor used to create vector images, primarily in Scalable Vector Graphics (.svg) format. Inkscape is an alternative to the commercial software Adobe Illustrator, and can be used to generate .svg files that work in Mapeo.

Using Inkscape to vectorize images

A common workflow for generating Mapeo icons is to find photos or other raster images, and turn them into vector images, simplifying them until they will render well at a small size. In Adobe Illustrator, this can be done using the Image Trace tool.

In Inkscape, this can be done using the Trace Bitmap tool found in the Path menu. There are some options to manipulate like Smoothing corners, Optimizing corners, and setting the number of colors.

Saving .svg files with the right size and Viewbox in Document Properties

Once you have a vector image that is to your satisfaction (and in a square format), you need to set the correct width & height and Viewbox size before saving the .svg file. You can do this in Document Properties (File menu).

First, set the Display units to pixels (px). This dropdown is located at the very top of the Document Properties menu.

Locate the "Custom Size" and "Scale" boxes in Document Properties.

First, you may need to set the unit of measurement for the Custom size, if it is not in pixels. If Units is in a format like milimeters (mm), change this to px.

Set the Width and Height to 100 each.

Next, the Viewbox needs to be set to 100 as well. The easiest way to do this — once you've set the Display units and Custom size units to pixels — is to set the Scale x to 1. It should copy over the Width and Height values from the Custom Size to the Viewbox. If that didn't do the trick, manually enter 100 for both Width and Height here.

Once you've done this, you may need to resize the art to match the full size of the Viewbox:

The easiest way to do this is to use the sizing and placement parameters right above the Viewbox, as shown in the screenshot above. Set W and H to 100 (px), and make sure X and Y are set to 0 (px). The image will then fill the entire Viewbox:

You can now save the .svg file by going to File → Save / Save As / Save A Copy.

Your .svg file should now be ready to be used by Mapeo. See Naming icon files for more information on how to name the files and where to place them in the configuration directory.

Verify that your SVG file is built correctly

It should have an initial <svg> tag with width and height set to 100, and viewBox set to "0 0 100 100."

After some tags like <defs>, <sodipodi:namedview>, <metadata>, which don't matter for the purposes of creating icons for Mapeo, you should see tags like <g> with layer properties, and a series of <path> with vertices and style properties, which constitute your vectors.

If your .svg file looks like this, the Mapeo configurations builder script should process your icons just fine.

Additional resources

• Troubleshooting SVG image errors in Mapbox Studio

In fields directory customize the .json files

Each .json file in the fields directory needs a key, type, label, and placeholder.

type can be one of select_multiple, select_one, or text.

For select_one and select_multiple fields, you will need to define an array of answer options.

Example fields file (name.json):

{
    "key": "name",
    "type": "text",
    "label": "Name",
    "placeholder": "Common name of this place"
}

Example fields file (sample-type.json):

{
    "key": "sample-type",
    "type": "select_one",
    "label": "Sample type",
    "placeholder": "Select the type of testing",
    "options": [
    	"Meteorological",
    	"Air",
    	"Soil",
    	"Water",
    	"Mineral",
        "Forestry/vegetation",
    	"Other"
	]
}

In the presets directory, customize the .json files

In the presets directory, each .json file needs:

• icon must mach the name of an icon in the icons folder - use prefix only, excluding the size refernce and file extension (eg. for fishing-24px.svg/fishing-100px.svg use fishing).

• name will be the human-readable label shown to the user

• geometry must be an array of point ,area, and/or line (All categories for use in Mapeo Mobile must include point.)

• sort (optional) is an integer that will determine the order in which categories are displayed on the Categories screen of Mapeo Mobile. If no sort is included, categories will be listed alphabetically by name.

• an array of fields (optional) which should match the key created in the fields directory. Fields will be displayed to users in the order they are listed in the fields array.

• color (optional) determines the color of observation dots on the map. (Dots fall back to orange if no color is defined.) Value can be a hex code, CSS color name or any string supported by validate-color.

Example preset file (fishing-site.json):

{
    "icon": "fishing",
    "name": "Fishing Site",
    "sort": 10,
    "color": "#13D5CF",
    "fields": [
        "name"
    ],
    "geometry": [
        "point",
        "area"
    ]
}

The defaults.json file is currently used by Mapeo Desktop to determine which categories (presets) to list for each type of map geometry (point, line, area).

Before building your configuration, ensure that defaults.json includes an array of presets for each geometry that corresponds to the geometries you've listed in your preset files.

Example defaults.json file:

{
    "area": [
        "area", 
        "airstrip",
        "animal",
        "community",
        "fishing-site",
        "gathering-site",
        "hills",
        "hunting-site",
        "lake",
        "palm",
        "special-site",
        "swidden",
        "threat",
        "tree",
        "plant"
    ],
    "line": [
	"line",
	"boundary-line",
	"river",
	"path",
	"stream",
	"threat"
    ],
    "point": [
        "point",
        "airstrip",
        "animal",
        "boundary-line",
        "building",
        "camp",
        "clay",
        "community",
        "fishing-site",
        "gathering-site",
        "house",
        "hunting-site",
        "palm",
        "cave",
        "plant",
        "salt-lick",
        "waterfall",
        "special-site",
        "swidden",
        "threat",
        "tree"
    ],
    "vertex": [
    ],
    "relation": [
    ]
}

What is a Project Key?

In the metadata.json file in your Mapeo configuration, you can include a projectKey, which is a random cryptographic string of characters to prevent unwanted devices from getting access to the data.

Once a Mapeo Mobile or Mapeo Desktop device has imported a configuration with a project key, it can only sync with another Mapeo Mobile or Mapeo Desktop device that has the same project key.

You can edit the project key (for example, if you want to make first 4 characters identifiable to a project) but it can only contain letters a-f and numbers 0-9.

It can also only be 64 characters long -- no more, no less.

Creating a Project Key

To create a projectKey, first open the Terminal.

Using mapeo-settings-builder

Copy and paste the following command into the terminal

mapeo-settings-builder generate-key

You'll see something like this (but with x replaced with real characters and numbers)

'380c02d32xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx1d'

Copy this string and add it to the metadata.json file so it looks like this:

{
  "dataset_id": "mapeo-jungle",
  "projectKey": "380c02d32xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx1d"
}

Notice that there are double quotes " around each value.

The package.json file stores the name and version information users will see in Mapeo when using the configuration.

Edit the name and version properties when creating a new configuration. Additional information on incrementing versions will be covered in Building configuration file.

You can also add description, author, and license information to this file but these properties will not be rendered in the Mapeo interface.

Example package.json file:

{
  "name": "project-config",
  "version": "1.0.0",
  "description": "Mapeo configuration",
  "dependencies": {
    "mapeo-settings-builder": "^3.0.0",
    "mkdirp": "^0.5.1"
  },
  "devDependencies": {},
  "scripts": {
    "build": "basename=\"${npm_package_name}-v${npm_package_version}\"; mkdirp build/${basename}; mapeo-settings build -l 'en' -o build/${basename}.mapeosettings && tar -C \"build/${basename}\" -xf build/${basename}.mapeosettings",
    "test": "mapeo-settings lint"
  },
  "author": "Your Name",
  "license": "UNLICENSED",
  "private": true
}

Compiling your configuration into a .mapeosettings file is the final step for testing and using your configuration in Mapeo Mobile and Desktop.

Building a configuration can be done in two ways:

• Via the command line(with Node.js and mapeo-settings-builder)

• Using GitHub Actions

Prepare computer for building the configuration

Mapeo is built with JavaScript programming language. To get started, you'll need to install Node.js development environment. If you already have Node.js installed you can skip this section.

You need to be at least on Node.js version 8 (or higher) for the mapeo-settings-builder to work properly. Head over to Node.js download page and select installer for your operating system.

Alternatively you can also use NVM (Node Version Manager) to install and manage multiple versions of Node.js on your computer.

Install nvm

touch ~/.bash_profile

curl -o- <https://raw.githubusercontent.com/creationix/nvm/v0.32.1/install.sh> | bash

Then close terminal and open again

Install homebrew (macOS)

http://brew.sh/

Install puppeteer dependencies (Windows Subsystem for Linux)

If you are using Windows Subsystem for Linux (WSL) to build a configuration, you need to install some dependencies for puppeteer.

sudo apt install libgtk-3-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2

Install npm

https://docs.npmjs.com/cli/install

Install and use node 12

nvm install 12
nvm alias default 12

Install Mapeo Settings Builder

You'll see output on the terminal, but this is OK

npm install -g mapeo-settings-builder

Is your computer ready?

If your computer is ready to create configurations, type

mapeo-settings-builder

You should see output that looks something like

→ Using version x.x.x of mapeo-settings-builder
Usage: mapeo-settings-builder [options] [command]

Options:
  -h, --help                   display help for command

Commands:
  build [options] [sourceDir]  Build config from presets in current working dir
  lint [sourceDir]             Lint preset files for errors
  extract-messages [options]   Extract messages for translation
  generate-key                 Generate a random project key
  help [command]               display help for command

Now you're ready to move to build your configuration!

Package Config Assets for MAPEO

Prep folder and build

Type, 'cd`, then a space, then drag and drop the folder where the prepared assets are and press enter. It will look something like this

cd /Users/jen/Documents/Dd_LOCAL_project-files/Dd-Tools/Mapeo/Presets/CREATION\\ LAB/Strathcona-KX-v1.0.0

You will then be ready to run scripts directly in the folder.

npm install

npm run -s build

This -s tells npm to be silent, so that you only see errors that are meaningful to you.

You will see something like the following output. Errors will be highlighted in RED with hopefully some helpful description so that you can remedy the issue.

→ Using version x.x.x. of mapeo-settings-builder
! Warning: no category json files found in /home/okdistribute/node_modules/mapeo-default-settings/mapeo-default-settings-2.1.0/categories
✓ Built presets and categories (37ms)
✓ Generated svg sprite for iD (544ms)
✓ Generated png sprite for Mapbox (81ms)
✓ Generated png icons for Mapeo Mobile (607ms)
✓ Successfully created file 'build/mapeo-default-settings-v2.1.0.mapeosettings' (total 1299ms)

You'll also see a .mapeosettings file inside of the build directory.

What is a .mapeosettings file?

A .mapeosettings file is a tar file, similar to a zip file. You can see the contents of the file by changing the file extension to .tar and using any application that can extract tar files (such as 7zip, mentioned above).

Troubleshooting Checklist

Type the following into the terminal

node -v

You need to be at least on Node version 8 for the mapeo-settings-builder to work properly. If you need help, review the 'Preparing Computer' section and ensure you're on the latest version of mapeo-settings-builder.

npm install -g mapeo-settings-builder@latest

You also may want to delete node_modules and install updated versions of the dependencies.

In Mac or Linux, in the terminal:

npm install

If you're having more issues, please open an issue on the GitHub repository or e-mail our support hotline.

Versioning

It's important to increment the version when releasing new changes to your configuration. When you are ready to release a new version, you can use standard-version in the command line to automatically increment your config version and update the CHANGELOG.md file in your repository.

It is possible to build a Mapeo configuration file using GitHub Actions. This requires setting up your custom configuration directory as a repository on Github.com, adding a /.github/workflows/build.yml script to your repository, and committing changes to that repository.

Setting up a configuration repository on GitHub

The first step will be to set up your configuration as a repository on github.com, with the requisite build script files that will trigger a GitHub Actions Workflow to generate your .mapeosettings file. There are a few ways to do this.

If you do not have your own custom configuration already, and are starting from scratch:

1. You can fork or upload either the Mapeo Default Configuration or the Empty Mapeo Configuration template to your own GitHub account. The choice you make will depend on how you will go about creating your own configuration, as detailed in Planning configuration & data structure.

2. Make sure that you have the .github/workflows directory in your configuration repository.

If you already have your own custom configuration:

1. Create a repository on GitHub for your custom configuration.

2. Commit your existing configuration content to the repository.

3. Download either the Mapeo Default Configuration or the Empty Mapeo Configuration, and copy over the .github directory to the root directory of your custom configuration.

4. Commit these files to your repository on Github.com. (Github may ask you for additional permissions to add these files, by confirming via the browser.)

Getting ready to build

Navigate to the Actions screen, and Click "I understand my workflows, go ahead and enable them."

This will bring you to a view of your Workflows. You should see a message "There are no workflow runs yet" if you just enabled Workflows for the first time. You are now ready to start building .mapeoconfig files.

How it works

Once you have enabled Action Workflows on your configuration repository, GitHub will generate a Workflow to build a new version of your configuration every single time that you commit a change to your repository.

Once you have committed a change to your repository, and navigate to the Actions tab, you should see your commit message listed as a workflow.

• ✅ a circular check indicates that the build has completed successfully.

• 🟡 a yellow circle indicates that the build is in process.

• 🔴 a red circle with an X indicates that the build has encountered an error.

You can click on your commit message to find out more about the status of your build. For example, if your build has encountered an error, there will be a log that can give you an idea of what went wrong. You can commit a change to fix the error, and return to the Actions screen to see if a new Workflow successfully bypasses the problem.

By opening the Workflow with your commit message, you can also download a .zip file of your configuration, which includes a temporary .mapeosettings file. This is helpful for testing out your configuration before building a versioned file to distribute to users, as described in Testing and iterating.

Use conventional commit messages to increment your configuration version

The Mapeo GitHub Actions Workflow is set up to dynamically bump the version of your configuration per each workflow. It does so using conventional commit messaging of adding feat:, fix:, or chore: before your commit message. For example, if you have a configuration with version 1.1.0, the specific version bumps are as follows:

• feat: this will increase your version to 1.2.0. This commit prefix could be used for major configuration updates.

• fix: this will increase your version to 1.1.1. This commit prefix could be used for small updates like changing an icon, or adding a field to a category.

• chore: this will not increase your version. This commit prefix could be used for correcting typos or fixing errors.

You can also manually update the first number in your 1.1.0 version in your package.json file, but Digital Democracy's convention is to only do so to indicate breaking changes. That said, you are free to choose a versioning convention that makes the most sense to you.

Compile a final, versioned release of your configuration

Once you are done making changes, have tested your configuration using a temporary .mapeosettings file (as described in How it works) and in accordance to the process described in Testing and iterating, you can generate a versioned release of your configuration. The way to do so is as follows:

• Navigate to the Actions tab for your GitHub repository. You should see all of your Workflows again.

• On the left sidebar, click on the Build & Release link.

• You should now see a box with the text "This workflow has a workflow_dispatch event trigger" and a button Run workflow. Click the button, and then click Run workflow again in the popup that will appear.

• Doing so will trigger another Workflow titled "Build and Release."

• When that finished with a ✅ green check mark, your versioned build release will be ready. On the top navigation bar, click on Code and your release should appear under the Releases panel in the right sidebar.

• Click on the release to download the versioned .mapeosettings file.

Once you've compiled your custom configuration, you will have a .mapeosettings file that can be imported into Mapeo Mobile and Desktop for testing and use.

What is a .mapeosettings file?

A .mapeosettings file is a tar file, similar to a zip file. For debugging purposes you can see the contents of the file by changing the file extension to .tar and using any application that can extract tar files.

Importing a configuration into Mapeo

For instructions on how to import a configuration file (.mapeosettings) into Mapeo, see:

Importing configurations into Mapeo Mobile

Importing configurations to Mapeo Desktop

Testing out your configuration

It's worthwhile to thoroughly kick the tires of your new configuration prior to introducing it into your project and beginning formal data collection.

A few things to look for when testing configurations:

• Icons Do icons render clearly? Check how icons appear, especially in Mapeo Mobile on devices with smaller screens.

• Categories Do categories appear in a logical order on the Categories screen of Mapeo Mobile? Changes can be made via the sort property in Creating categories.

• Details fields Are text labels and placeholders easy to understand? Do details fields appear in a logical order? Fields will be displayed to users in the order they are listed in the fields array in Creating categories.

• Colors If you added color to category map markers, are they distinguishable from one another and visible on your map background?

• Name and version Does the name and version of your configuration appear as desired on the Project configuration screen of Mapeo Mobile or the Synchronize screen of Mapeo Desktop?

Making changes

Changes can easily be made to your configuration via steps in the Coding configurationsection. We often test, modify, recompile and retest several times before releasing a new config version.

As noted in Planning configuration & data structure, configurations can and often will evolve over time. As you begin collecting data, you will likely find categories, details fields and options you would like to add or modify.

Unlike some other survey or data collection tools, Mapeo allows a lot of flexibility for changing configurations over time and does not require that the database be wiped when changes are made. While changes to icons or color, name, label, or placeholder fields will be minor, more significant modifications like removing a category will impact how existing data is displayed in Mapeo and data exports. Regardless of these changes, no previous data will be lost or unviewable.