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. Click on Global Entity Matcher in the sidebar

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. Review the security warning 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 Enter local file path field, type or paste the full path to your Parquet file
   • 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>.parquet" \
4
                     --file "/path/to/<YOUR_FILE_NAME>.parquet" \
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 GEM Matching” form will appear

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
• A new entry appears in the job list
• Initial status shows as Requested
• Job ID is generated for tracking

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 bar to find specific jobs
• Enter partial or complete job ID
• Results filter in real-time

Filter Jobs:

• Filter by status (In Progress, Success, Failed)
• Filter by storage
• Filter by Overture release version
• Filter by matching type

Sort Options:

• Sort by submission date
• Sort by completion date
• Sort by job name
• Sort by status

4.3 Refresh status

• Refresh the page manually to see the latest status updates
• Click on a job row to view detailed information

Step 5: View job details

5.1 Access details page

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

5.2 Details page overview

The details page contains two main 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). Examples:

• Input file ‘input.parquet’ was not found in the storage location.
• Input file ‘input.parquet’ is not a valid Parquet file.
• Input file ‘input.parquet’ is missing required column(s): ‘geometry’. Required columns: ‘id’, ‘geometry’.
• Column ‘id’ in input file ‘input.parquet’ contains 1 duplicated value(s). Each road must have a unique ‘id’.
• Column ‘geometry’ in input file ‘input.parquet’ contains 3 value(s) that are not valid WKT LINESTRING geometries.

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

Job Run Details Section:

• Job ID (unique identifier)
• Input filename used, with file size in parentheses (e.g. my_map_data.parquet (12.3 MB))
• Result filename, with file size in parentheses once available
• Storage location
• Matching type applied
• Overture release version
• Submission timestamp
• Job status
• Statistics (available when job is successful)

5.3 Accessing Key Performance Indicators (KPIs)

For successful jobs, review 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

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 in Output data schema

Resources

• Troubleshooting - Check solutions in case of issues
• Understanding GERS IDs - Learn about the reference system
• Use Cases - Explore practical applications
• Features & Benefits - Understand GEM capabilities
• Working with multiple jobs - Information about working with multiple matching jobs simultaneously
• Technical Details - Deep dive into system architecture
• FAQ - Find answers to common questions