> For the complete documentation index, see [llms.txt](https://support.gamoshi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.gamoshi.com/gamoshi-wiki/general-information/mapping-rules.md).
# Mapping rules
Mapping rules ensure that configurations from external platforms or systems are correctly reflected in the requests sent to the advertiser.
## Availability
* **PE Enterprise accounts:** Full mapping rules functionality.
* **PE Pro accounts:** Limited mapping rules functionality.
* **DSP accounts:** Available on the Pro tier and above for advertisers using external inventory.
***
## Overview
Mapping rules enable you to set or change values in an incoming request, support setups made in other systems, and enrich the original data being sent.
### Mapping rule levels
* **Inventory-level:** Affects all relevant requests for a specific inventory, or, by selecting **All Partners**, all inventories.
* **Advertiser-level:** Affects all requests sent to the advertiser from all of the advertiser's associated inventories, or, by selecting **All Partners**, all advertisers.
### When to use each
**Inventory mapping rules** are a good choice when you need to change, enrich, or update values for all requests coming from a specific inventory, or from all inventories, for example, adding missing values, content categories, or blocked categories.
**Advertiser mapping rules** are a good choice when the advertiser requires you to send requests with certain values specific to that advertiser.
### Incoming and target properties
A mapping rule connects an **Incoming Property** (the dimension of the incoming request that needs to be matched to a value) to a **Target Property** (the request property that will hold the mapped value).
**Example:** You can map domains/bundles (incoming) to placements (target). Each domain/bundle value will have a corresponding placement value; when the request is sent, the matching placement value is included.
{% hint style="warning" %}
When you create a mapping rule for a Domain or Bundle without associating data records to it, you effectively pause the related advertiser/inventory activity. Always add data records to your mapping rules.
{% endhint %}
***
## Processing workflow
When an incoming request reaches your account, it is processed in the following order:
{% stepper %}
{% step %}
### Account/Inventory-level validation
Checking the validity of the requests and executing Allow Lists and Block Lists defined at the account level or Inventory level.
{% endstep %}
{% step %}
### Inventory mapping rules (allowlist type)
Inventory mapping rules defined as an allowlist are processed.
{% endstep %}
{% step %}
### Inventory mapping rules (regular)
Regular Inventory mapping rules are processed: first the rules defined for **All Inventories**, then rules specific to that Inventory.
{% endstep %}
{% step %}
### Advertiser mapping rules
For all advertisers, after filtering the advertiser and campaign lists, mapping rules are processed: first the rules defined for **All Advertisers**, then the rules specific to that advertiser.
{% endstep %}
{% endstepper %}
***
## Accessing Mapping Rules
### Advertiser-Level
When creating or editing an advertiser (edit icon in the Actions column), define mapping rules from the **Mapping Rules** tab in the advertiser's details form. This utility lets you customize the mapping per advertiser or, by switching on **"All Partners"** in a rule, apply it to all advertisers.
You can also manage mapping rules for an advertiser centrally via the **Advertisers Module → Mapping Rules screen**.
### Inventory-Level
* **For a new inventory:** Create and save the inventory's General tab, then go to the **Mapping Rules** tab in the inventory's details form.
* **For an existing inventory:** Go to **Inventories Module → Inventories List**, click the edit icon in the Actions column, then go to the **Mapping Rules** tab.
* **Alternative access:** Manage all mapping rules across inventories in **Inventory Module → Mapping Rules**, which allows searching, filtering, bulk editing, and data records management.
***
## Creating and Managing Mapping Rules
### Defining Rules
Each rule connects an **Incoming Property** to a **Target Property**. After defining the incoming property, the target property, and any relevant filters, insert the mapping by pasting comma-separated values or uploading a CSV/TXT file.
### Creating a New Mapping Rule
**Navigation:**
* **For Advertiser:** Go to **Advertisers Module → Mapping Rule screen**, then click the **+** button in the top-right corner of the grid. This can also be done from **Advertisers Module → Advertisers List → Advertiser Details form → Mapping Rule tab**.
* **For Inventory:** Go to **Inventory Module → Mapping Rule screen**, then click the **+** button in the top-right corner of the grid. This can also be done from **Inventory Module → Inventory List → Inventory Details form → Mapping Rule tab**.
{% stepper %}
{% step %}
### Open the Create a Rule form
Click the **+** icon in the top-right corner of the table grid. A **"Create a Rule"** form appears.
{% endstep %}
{% step %}
### Fill in the rule details
Fill in the mandatory fields: Name, Advertiser, Incoming property, and Target property. Fill in any additional fields/filters if required.
{% endstep %}
{% step %}
### Create the rule
Click **Create**.
{% endstep %}
{% endstepper %}
### Adding Data Records
To apply a mapping rule, you must first add data records to it. Click the data record row action to open the mapping data screen.
#### Uploading a data file
{% stepper %}
{% step %}
### Upload the file
Click the **Upload File** icon at the top right of the grid, then click **Upload File**.
{% endstep %}
{% step %}
### Select the file
Choose the file and click **Open**. The file must be in CSV or TXT format, up to 10MB.
{% endstep %}
{% endstepper %}
### Adding data records manually
{% stepper %}
{% step %}
### Open the Insert a Mapping Rule Data form
Click the **+** icon at the top right of the grid. An **"Insert a Mapping Rule Data"** form appears.
{% endstep %}
{% step %}
### Insert the records
Insert records manually in the mapping rule data text box — one record per line. Each line should contain the From and Target properties (mandatory) and a description (optional), separated by a comma.
{% endstep %}
{% step %}
### Save
Click **Save**.
{% endstep %}
{% step %}
### Edit existing records
You can edit existing data records via the row's edit action; all fields are editable.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
**Special catch-all value:** You can add a value of $\_other\_$ to a data record (via upload or manually). This special property catches all values not explicitly specified.
{% endhint %}
{% hint style="warning" %}
Using $\_other\_$ means the rule will no longer act as an allowlist.
{% endhint %}
***
## Bulk Replacement
Use bulk replacement when you need to replace a specific TO value across all data records of a mapping rule.
{% stepper %}
{% step %}
### Open bulk replacement
Click the **Bulk Replacement** icon at the top right of the grid. A **"Bulk Replace 'TO' Value"** form appears.
{% endstep %}
{% step %}
### Insert replacement values
Insert the TO values to replace in the format existing value=new value, one per line (e.g., google.com=yahoo.com).
{% endstep %}
{% step %}
### Replace all values
Click **Replace All**, then confirm.
{% endstep %}
{% endstepper %}
***
## Editing a Mapping Rule
{% stepper %}
{% step %}
### Open the Update a Rule form
Click the edit row action for the chosen mapping rule in the Mapping Rules grid. An **"Update a Rule"** form appears.
{% endstep %}
{% step %}
### Edit the fields
All fields are editable except the Advertiser name and the From/Target properties.
{% endstep %}
{% step %}
### Update the rule
Click **Update** when done.
{% endstep %}
{% endstepper %}
***
## Automatic Mapping Rules (Custom Integration Types)
Advertisers using certain custom integration types have automatic mapping rules, found in the advertiser's form under the **Integration** tab. You can also perform all data record actions described above from that tab.
### Applying Rules Across Multiple Entities
When creating or editing a mapping rule, you can apply it to multiple advertisers/inventories, or to **All Partners**, with one switch.
{% hint style="warning" %}
Applying rules globally may cause conflicts if other entities already have their own mapping rules. All-Partners mapping rules are executed before entity-specific rules.
{% endhint %}
***
## Activating a Mapping Rule as an Allow List
If your mapping rule should also act as an allow list for the advertiser, for example, a list of domains or bundles, you can activate the **Allow List** switch on the mapping rule. It will then also function as a targeting list for the advertiser.
***
## Understanding Incoming Properties
The incoming property is the dimension of the incoming request that needs to be matched to a value.
**Commonly used:** Bundle, Domain
### Full list of available incoming properties
| **Incoming Property** |
| --------------------------------------------------------------------------------- |
| ALL\_REQUESTS *(matches all incoming requests; can contain only one data record)* |
| APP\_ID |
| APP\_NAME |
| BUNDLE |
| BID\_FLOOR |
| COUNTRY |
| DOMAIN |
| DEAL\_ID |
| DISPLAY\_MANAGER |
| DISPLAY\_MANAGER\_VERSION |
| MEDIA\_TYPE |
| PLACEMENT |
| PRICE |
| PUBLISHER\_ID |
| SITE\_ID |
| SITE\_URL |
| SOURCE |
| STORE\_URL |
| SUPPLY\_PARTNER\_ID |
| VIDEO\_PLACEMENT\_TYPE⁴ |
| VIDEO\_PLCMT⁵ |
| WSEAT |
{% hint style="info" %}
To add incoming or target properties beyond the default set to your account's mapping rules, contact support.
{% endhint %}
***
## Understanding Target Properties
The target property is the request property that will hold the mapped value.
**Commonly used:** Placement
### Full list of available target properties
| **Target Property** |
| ------------------------------------- |
| APP\_ID |
| APP\_NAME |
| AUDIO\_FEED\_TYPE |
| BID\_FLOOR |
| BLOCKED\_ADVERTISERS¹ |
| BLOCKED\_APPS¹ |
| BLOCKED\_ATTRIBUTES¹ |
| BLOCKED\_CATEGORIES¹ |
| BUNDLE |
| CONTENT\_CAT |
| CONTENT\_CONTEXT² |
| CONTENT\_GENRE |
| CONTENT\_LANG |
| CONTENT\_LENGTH² |
| CONTENT\_RATING |
| COUNTRY |
| CUSTOM\_IMP\_XX (XX = 01–03) |
| CUSTOM\_REQ\_XX (XX = 01–03) |
| DOMAIN |
| DEAL\_ID *(see Deal ID Rules, below)* |
| DISPLAY\_MANAGER |
| DISPLAY\_MANAGER\_VERSION |
| EXCLUDE\_MRAID³ |
| HEIGHT |
| INCLUDE\_MRAID |
| INVENTORY\_PARTNER\_DOMAIN |
| MEDIA\_TYPE |
| NATIVE\_AD\_UNIT |
| NATIVE\_CONTEXT |
| NATIVE\_CONTEXT\_SUB\_TYPE |
| NATIVE\_LAYOUT\_ID |
| NATIVE\_PLACEMENT\_TYPE |
| OS |
| OS\_VERSION |
| PLACEMENT |
| PRICE |
| PUBLISHER\_ID |
| SCHAIN |
| SITE\_ID |
| SITE\_URL |
| SOURCE |
| STORE\_URL |
| VIDEO\_PLACEMENT\_TYPE⁴ |
| VIDEO\_PLCMT⁵ |
| WIDTH |
| WSEAT |
{% hint style="info" %}
For all BLOCKED\_xxx properties, enclose values within double quotes, separated by commas. Example: "value1, value2, value3, value4, value5"
{% endhint %}
***
## Deal ID Rules
The format for the Deal ID is: `id|price|seat`
* If you need more than one seat: `id|price|seat1,seat2,seat3`
* If you need to set more than one deal, use the $ sign to separate the deals.
**Example:** `my_sp_deal|3.3|234$my_sp_deal_2|0|34,23`
Per this example, Gamoshi will create two private deals:
**First deal**
* Name: my\_sp\_deal
* Price: 3.3
* Seat: 234
**Second deal**
* Name: my\_sp\_deal\_2
* Price: auction price
* Seat: 34, 23
{% hint style="info" %}
Price and Seat are not mandatory.
{% endhint %}
***
## Pricing Rules
| **Price Value** | **Behavior** |
| --------------- | -------------------------- |
| 0 / nothing | Use the bid request price. |
| > 0 | Use the defined price. |
| < 0 (= -1) | Use the bid floor price. |
***
## Video Placement Types
For your video placement mapping, use the ID number only (x) from the lists below.
### VIDEO\_PLACEMENT\_TYPE
1. In-Stream
2. In-Banner
3. In-Article
4. In-Feed
5. Interstitial / Slider / Floating
### VIDEO\_PLCMT
1. Instream
2. Accompanying Content
3. Interstitial
4. No Content / Standalone
***
## Filters
Mapping rules can be filtered by:
* Ad Sizes
* Ad Type
* Device Type
* Countries
* Source
* Operating System
***
## Troubleshooting
Advertiser paused unexpectedly?
Check whether a domain/bundle mapping rule exists without associated data records.
Conflicting behavior?
Verify whether rules are being applied to multiple advertisers/inventories via "All Partners."
Not seeing expected mapping results?
* Confirm correct Incoming/Target property pairing.
* Validate CSV/TXT file formatting and size.
* Ensure BLOCKED\_xxx record values are enclosed in quotes and comma-separated.
¹ For all BLOCKED\_xxx properties, enclose values within double quotes, separated by commas. ² For the advertiser's mapping rules only. ³ For the inventory's mapping rule only. ⁴ For your Video Placement Type mapping, use the ID number only; see Video Placement Types, above. ⁵ For your Video Placement (VIDEO\_PLCMT) mapping, use the ID number only — see Video Placement Types, above.