> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.metalocator.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Importing from Azure Blob Storage

MetaLocator supports importing location data directly from Microsoft Azure Blob Storage. This allows you to store your CSV data files in an Azure Storage container and import them into MetaLocator either on-demand or on a recurring schedule.

[![](https://storage.crisp.chat/users/helpdesk/website/-/2/6/2/4/2624cde7c4170200/e76274a6-162f-410e-8def-ad7d1c_1gctuwr.png)](https://downloads.intercomcdn.com/i/o/yn1vvwtq/2271245324/baad2e1087e466fcb37c25f29217/image.png?expires=1794511800&signature=a56e69e9403c4b8927363788a000a1fc50d6f4fef705a036cee849b82afb06a6&req=diIgF8t6mIJdXfMW1HO4zQfZGSUFgqxNjuHspefYBnDGAAVtmxxaC8zlpZ%2FN%0A8hbWstm49Ci5hNeKr%2FY%3D%0A)

## Getting Your Azure Credentials

## Option A: SAS Token (Recommended)

A SAS token provides scoped, time-limited access to your storage container without exposing your full account key.

1. Sign in to the [Azure Portal](https://portal.azure.com/)
2. Navigate to your **Storage Account**
3. In the left menu, select **Shared access signature** (under Security + networking)
4. Configure the SAS settings:

* **Allowed services:** Blob
* **Allowed resource types:** Container, Object
* **Allowed permissions:** Read, List
* Set an appropriate **expiry date**
5. Click **Generate SAS and connection string**
6. Copy the **SAS token** value (it starts with `?sv=`)

## Option B: Account Key

The account key provides full access to all containers in your storage account.

1. Sign in to the [Azure Portal](https://portal.azure.com/)
2. Navigate to your **Storage Account**
3. In the left menu, select **Access keys** (under Security + networking)
4. Click **Show** next to one of the keys
5. Copy the **Key** value (a Base64-encoded string)

**Security Note:** SAS tokens are recommended over account keys because they can be scoped to specific containers, limited to read-only access, and set to expire after a defined period.

## Step-by-Step Import Guide

## Step 1: Start the Import

1. Log in to your MetaLocator admin panel
2. Navigate to the **Import** section
3. Click the **MS Azure Blob Storage** button

## Step 2: Enter Connection Details

Fill in the following fields on the Azure Blob Storage configuration form:

| Field | Description | Example |
| --- | --- | --- |
| Storage Account Name | The name of your Azure storage account (not the full URL) | mystorageaccount |
| Container Name | The name of the blob container holding your files | my-container |
| Authentication Method | Choose between SAS Token or Account Key | — |
| SAS Token | Your SAS token (if using SAS authentication) | ?sv=2023-01-03&ss=b&srt=sco&sp=rl... |
| Account Key | Your account key (if using Account Key authentication) | (Base64-encoded string) |

## Step 3: Choose a File Selection Mode

MetaLocator provides two ways to select which Azure Blob Storage file or files should be imported.  
​

### Select File Mode

Use this mode when you want to select a specific file from the container.

1. Select **Select File** as the file selection mode.
2. Optionally enter a **Path Prefix** to limit the file list to a specific folder.
3. Click **Test Connection & Load Files**.
4. Select the desired CSV file from the resulting list.

A Path Prefix represents an Azure Blob Storage virtual folder. Enter it without a leading slash.

For example:

* `data/` selects files located directly inside the `data` folder.
* `/data/` should not be used.
* Files in `data/archive/` are not considered to be directly inside `data/`.

### File Mask Mode

Use File Mask mode when uploaded files follow a predictable naming convention.

Enter a filename pattern in the **File Mask** field. File masks apply to the filename only and support the following wildcard characters:

* `*` matches any number of characters.
* `?` matches exactly one character.

Examples:

* `partnerlocator*.csv` matches `partnerlocator.csv`, `partnerlocator-2026.csv`, and similar filenames.
* `locations-2026-07-??.csv` matches filenames such as `locations-2026-07-01.csv`.

The optional **Path Prefix** determines the exact virtual folder in which MetaLocator searches. The file mask should not include the folder path.

For example:

* Path Prefix: `incoming/`
* File Mask: `locations-*.csv`

This configuration considers files such as `incoming/locations-2026-07-27.csv`. It does not consider matching files in the container root or in a nested folder such as `incoming/archive/`.  
​

After entering the Path Prefix and File Mask, click **Test Connection & Load Files** to preview the matching files.  
​

MetaLocator evaluates up to 5,000 blobs returned by Azure for the configured prefix. Use a sufficiently specific Path Prefix and File Mask so that the candidate set remains below this limit.

## Recommended File Naming Convention

Use a unique, timestamped filename for each file uploaded for Queue mode. A recommended format is `locatorYYYY_MM_DD_HH_MM_SS.csv`, such as `locator2026_07_27_17_52_13.csv`. Placing the date and time in year-to-second order keeps filenames naturally sortable and prevents a newly uploaded file from reusing the name of a file that MetaLocator has already processed. Generate timestamps using a consistent timezone, preferably UTC, and use zero-padded values so every filename follows the same structure.  
​

## Selecting the Most Recent Matching File

When **Process as a Queue** is _not_ enabled, File Mask mode selects the most recently modified matching file.  
​

The same most recent file is selected each time the job runs, including recurring scheduled runs. This mode is appropriate when your integration continually replaces or updates a current source file, or when only the newest dated file should represent the complete current dataset.  
​

The matching-file preview displays up to 10 of the most recent matching files. The file marked **Will be imported** is the file MetaLocator will select.  
​

## Processing Matching Files as a Queue

Enable **Process as a Queue** when each matching file represents a separate batch that must be imported once and in chronological order.  
​

In Queue mode, MetaLocator:

* Sorts matching files by their Azure last-modified date.
* Selects the oldest file that has not already been handled by this import job.
* Imports files from oldest to newest.
* Processes a maximum of 10 files during a single job run.
* Continues with any remaining files during the next scheduled run.

When all matching files have already been processed, the job completes successfully without importing another file. It checks for new files the next time the job runs.

The matching-file preview displays the first 10 files that Queue mode will consider. The oldest file is marked **Will be processed first**.  
​

Queue mode is intended for controlled inbound queues. Do not allow the number of candidate blobs for the configured Path Prefix and File Mask to reach 5,000. If Azure returns the 5,000-file limit while Queue mode is active, MetaLocator stops the import and sends a background-import failure notification because it cannot safely determine whether additional files exist beyond the returned results.  
​

## Step 4: Test the Connection

After entering your credentials and file selection settings, click **Test Connection & Load Files** to verify:

* Your credentials are valid
* The container is accessible
* CSV files are available at the specified location

If the connection is successful, you will see a confirmation message indicating how many file(s) were found. If there is an error, a message will describe the issue (e.g., invalid credentials, container not found).

## Step 5: Start the Import

1. Once your file is selected and the connection is verified, click **Next**
2. The import will begin as a background job
3. A progress indicator will show the status of your import
4. When complete, you will see a confirmation message

## Keeping Data in Sync (Recurring Imports)

If your plan supports background processing, you will see a **Keep Azure Blob Data In Sync?** checkbox on the configuration form.

Enabling this option will:

* Create a recurring background job that runs automatically every 24 hours
* Download the latest file from your Azure container using the same connection settings and file selection criteria
* Import the data into MetaLocator, keeping your location data up to date with changes in your source file

This is particularly useful when combined with **File Mask** mode, as it will always pick up the most recently modified file matching your pattern.

## Troubleshooting

## Connection Errors

| Error | Cause | Solution |
| --- | --- | --- |
| Authentication failed (HTTP 403) | Invalid or expired credentials | Verify your SAS token has not expired and has read+list permissions, or verify your account key is correct |
| Container not found (HTTP 404) | Incorrect container name or storage account name | Double-check the storage account name and container name for typos |
| Connection error | Network or DNS issue | Verify the storage account name is correct and the account is accessible |

## No Files Found

* Ensure your CSV files have a `.csv` file extension
* If using a path prefix, confirm the prefix matches the folder structure in your container (e.g., `data/` not `/data/`)
* If using file mask mode, verify your wildcard pattern matches the file naming convention

## Import Fails After Download

* Verify that your CSV file is [properly formatted](https://support.metalocator.com/en/articles/1655854-introduction-to-importing-data) with column headers in the first row
* Check that the file is not empty or corrupted
* Review the import job status in the **Jobs** section of the admin panel for detailed error messages

## SAS Token Expiration

SAS tokens have an expiry date. If your recurring import stops working, check whether your SAS token has expired and generate a new one if needed. When updating the SAS token:

1. Navigate to the Import section
2. Select Azure Blob Storage
3. Enter the new SAS token
4. Click **Test Connection & Load Files** to verify
5. Proceed with the import to update the saved credentials

## Supported File Format

Azure Blob Storage import supports **CSV files** only. Your CSV file should:

* Have column headers in the first row
* Use standard CSV formatting (comma-separated values)
* Have a `.csv` file extension

## Best Practices

1. **Use SAS tokens** instead of account keys for better security
2. **Set SAS token expiry dates** that are reasonable for your use case and renew them before they expire
3. **Create a container** specifically for MetaLocator
4. **Use file masks** for recurring imports to automatically pick up the latest file
5. **Organize files with path prefixes** to keep your container organized and make file selection easier
6. **Test the connection** before starting each import to catch credential or access issues early  
​