UI workflow guide

UI workflow guide

This guide walks you through the complete workflow of using GEM via the web interface, from uploading data to downloading your matching results.

Workflow overview

1. Access GEM dashboard — Log in at my.tomtom.com → Select project → Open GEM
2. Upload data — Prepare data → Authorize → Upload via Azure CLI
3. Trigger matching — Configure job parameters → Submit
4. Monitor progress — Track job status in dashboard
5. Download results — View details → Download via Azure CLI

Step 1: Access GEM dashboard

1. Navigate to my.tomtom.com
2. Log in using your Microsoft Entra ID credentials
3. In the left navigation panel, select the appropriate Project from the dropdown menu
4. In the sidebar, expand Maps and click Global Entity Matcher

What you’ll see:

• List of previous matching jobs (empty for new users)
• Prepare Data + button for uploading new data
• Trigger matching button to start new jobs
• Search and filter capabilities for job history

Step 2: Prepare and upload data

2.1 Initiate upload process

1. Click the Prepare Data + button on the dashboard
2. The “Upload Data” modal window will appear

2.2 Select storage

In the “Select Storage” step:

1. Storage Name: Select your target storage from the dropdown

   • If you have access to only one storage, it will be pre-selected
   • Multiple storages: choose the appropriate one for your project

2. Click Next to proceed

2.3 Authorize storage access

The authorization step provides credentials for Azure CLI access.

1. Click the Unwrap button when prompted
2. Read the Attention! message about displaying sensitive credentials
3. Click Unwrap again to confirm
4. The command will auto-populate with your credentials
5. Copy the complete az login command
6. Open your terminal and execute the command

Command example:

1
az login --service-principal \
2
  --username <client_id> \
3
  --password <client_secret> \
4
  --tenant <tenant_id>

Security Best Practices:

• Never share credentials with unauthorized parties
• Credentials are temporary and scoped to specific operations

2.4 Upload your data file

1. In the Local input file path field, type or paste the full path to your input file (.parquet, or .csv for Lane Level Matching)
   • Windows Example: C:\Users\username\data\my_map_data.parquet
   • macOS/Linux Example: /Users/username/data/my_map_data.parquet
2. The UI will automatically extract the filename and update the upload command
3. Copy the generated az storage blob upload command
4. Execute the command in your terminal:

1
az storage blob upload --account-name "<STORAGE_ACCOUNT_NAME>" \
2
                     --container-name "default" \
3
                     --name "<YOUR_FILE_NAME>" \
4
                     --file "/path/to/<YOUR_FILE_NAME>" \
5
                     --auth-mode login

5. Wait for upload completion - Progress will display in your terminal
6. Click Finish to close the modal

Upload Tips:

• Larger files take longer - be patient
• Azure CLI supports files of any size
• Ensure stable network connection
• Keep the filename simple (no special characters)
• Verify upload success before proceeding

Step 3: Trigger matching job

3.1 Open matching form

1. Return to the GEM dashboard
2. Click the Trigger matching button
3. The Run TomTom GEM Matching form appears

3.2 Complete the form

Fill in all required fields:

Input file dropdown behavior:

• Select a Storage Name first — the input file dropdown is disabled until a storage is chosen
• The dropdown lists only files compatible with the selected matching type:
  • Road Matching: .parquet files only
  • Lane Level Matching: .parquet and .csv files
• Files are sorted newest first, with file size and last-modified date shown as tags on each option
• If no compatible files are found in the storage, the dropdown shows “No applicable files found in the storage” and remains disabled
• Changing the storage or switching to an incompatible matching type clears the current file selection

3.3 Submit the job

1. Review all entries for accuracy
2. Verify you selected the correct storage and file
3. Click Submit

3.4 Job submission confirmation

Upon successful submission:

• The form closes automatically
• The message Matching job with id <id> triggered successfully appears
• A new entry appears in the job list, with the status Requested

If GEM rejects the job, the message explains why, for example when an identical job is still running.

Step 4: Monitor job progress

4.1 Job status dashboard

The main dashboard displays all your matching jobs with real-time status updates.

Job Status Types:

4.2 Using dashboard features

Search by Job ID:

• Use the Search by id field to find specific jobs
• Enter partial or complete job ID
• Results filter in real-time

Filter Jobs:

• Filter by status (Requested, In Progress, Failed, Success)
• Filter by storage
• Filter by matching type
• Click Reset Filters to clear all filters

Sort and page through jobs:

• Click a column header to sort by it. By default, jobs are sorted by Requested At, newest first
• Choose 10, 20, 50, or 100 Results per page

4.3 Refresh status

• Refresh the page manually to see the latest status updates
• Click the arrow at the end of a job row to view detailed information

4.4 Run several jobs

You can submit several matching jobs at once. Each job is processed independently, and the dashboard shows all of them. GEM rejects a new job while an identical job, with the same storage, input file, matching type, and Overture release, is still Requested or In Progress.

• Use descriptive file names to tell your jobs apart
• Download the results as each job completes
• Keep a local copy of your input data

Step 5: View job details

5.1 Access details page

1. Locate your job in the dashboard list
2. Click the arrow at the end of the job row
3. The Job Run Details page opens

5.2 Details page overview

The details page contains the following sections:

Error alert (failed jobs only):

When a job has Failed status and the failure was caused by an input validation problem, a red error alert is displayed at the top of the details page — above the details table. It reads “Job run failed due to following reasons:” followed by the specific error message(s), for example Input file ‘input.parquet’ is not a valid Parquet file.

If the failure was caused by an internal system error, the message reads: An internal error occurred while processing your request. Please contact support.

See Checks GEM runs for all road matching messages and how to fix them, and Troubleshooting for other failures.

Job Run Details Section:

• Job Run ID (unique identifier)
• Status
• Requested At (submission timestamp)
• Storage
• Matching Type
• Overture Release (Road Matching)
• Input File name, with file size in parentheses (e.g. my_map_data.parquet (12.3 MB))
• Result File name, with file size in parentheses once available

5.3 Accessing Key Performance Indicators (KPIs)

For successful Road Matching jobs, the Key Performance Indicators section shows the matching statistics:

Quality Indicators:

• >85% matched: Excellent quality
• 70-85% matched: Good quality, review unmatched roads
• Less than 70% matched: May indicate data quality issues

Step 6: Download results

6.1 Initiate download

For jobs with Success status, the Download Results section appears on the Job Details page only when the result file is confirmed to be present in the storage.

1. On the Job Details page, locate the Download Results section
2. Click the Download button
3. The “Download Data” modal appears

6.2 Authorize storage

If you’re already authorized from the upload step, skip to 6.3. Otherwise:

1. Follow the same authorization process as Step 2.3
2. Unwrap credentials and execute az login command
3. Proceed once authenticated

6.3 Specify download location

1. In the Local destination directory path field, enter where you want results saved

   • Windows Example: C:\Users\username\downloads\gem_results
   • macOS/Linux Example: /Users/username/downloads/gem_results

2. The system updates the download command with:

   • Storage account name
   • Container name
   • Results filename
   • Your specified destination

3. Copy the complete az storage blob download command

6.4 Execute download

Run the command in your terminal:

1
az storage blob download --account-name "<STORAGE_ACCOUNT_NAME>" \
2
                        --container-name "default" \
3
                        --name "<YOUR_FILE_NAME>.results.parquet" \
4
                        --file "/path/to/<YOUR_FILE_NAME>.results.parquet" \
5
                        --auth-mode login

Download Process:

• Progress displays in terminal
• Download time depends on results file size
• Verify download completes successfully
• Click Finish to close the modal

Visualization data: if you enabled Generate visualization data, download the GeoJSON files with Azure CLI, see Visualization data.

6.5 Verify downloaded results

After download completes:

1. Navigate to your specified destination directory
2. Confirm the <YOUR_FILE_NAME>.results.parquet file exists
3. Check file size is reasonable (not 0 bytes)
4. Open file in Parquet viewer or analytical tool
5. Verify data structure and content: road matching results or lane-level matching results

Resources

• Troubleshooting - Check solutions in case of issues
• Data preparation - Prepare your input file
• Understanding GERS IDs - Learn about the reference system
• Use Cases - Explore practical applications
• Features & Benefits - Understand GEM capabilities
• Technical Details - Deep dive into system architecture
• FAQ - Find answers to common questions