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:

3.3 Submit the job

1. Review all entries for accuracy
2. Ensure the filename matches exactly (case-sensitive)
3. Verify you selected the correct storage
4. 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

If submission fails, see the Troubleshooting page.

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

Monitoring Tips:

• Processing time varies based on data size
• Average: ~100,000 road segments per hour
• Small datasets (< 10K roads): Minutes
• Large datasets (> 1M roads): Hours
• No email notifications yet (planned feature)

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:

Job Run Details Section:

• Job ID (unique identifier)
• Input filename used
• 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:

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