Primary Trafficker Null Error When Pushing Orders to Google Ad Manager

Problem

When attempting to push a Programmatic Order to Google Ad Manager (GAM), the operation fails with the following error:

NotNullError.NULL @ [0].primaryTrafficker

This error indicates that GAM is receiving a null or missing value for the Primary Trafficker field, which is a required field for Order creation in GAM. The push fails and the Order cannot be delivered to the Ad Server.

Root Cause

The Primary Trafficker value is stored correctly in Salesforce on the Fulfilment record, but it is being dropped or not serialized during the hand-off from CloudSense to Google Ad Manager.

Common causes include:

1. Outdated or Customized Mapping File: The fulfilmentStrategy.json file may be missing the primaryTraffickerId mapping or has it wrapped in a conditional that evaluates to false
2. Default Trafficker Settings Enabled: The Ad Server record has "Use default trafficker when missing" options enabled, which may interfere with the mapping
3. User Inactive or Deleted in GAM: The Primary Trafficker user exists in Salesforce but is inactive or deleted in Google Ad Manager
4. Payload Serialization Issue: The CloudSense serialization logic is not correctly extracting the Primary Trafficker ID from the Fulfilment record

Resolution Steps

Step 1: Verify the Fulfilment Strategy Mapping File

1. Locate the fulfilmentStrategy.json file in your Salesforce org:
2. Navigate to Setup > Static Resources
3. Search for your GAM fulfilment strategy static resource (e.g., "FulfilmentStrategy_GAM")

4. Download and open the JSON file

5. Check the Order or Proposal mapping block for the primaryTraffickerId field:

{
  "order": {
    "enabled": true,
    "engine": "JavaScript",
    "mapExpression": "{\n  primaryTraffickerId: parseInt(fulfilment.getPrimaryTrafficker().getAdServerId()),\n  // ... other mappings\n}"
  }
}

1. Verify the mapping is present and not wrapped in a conditional:
2. The line should be: primaryTraffickerId: parseInt(fulfilment.getPrimaryTrafficker().getAdServerId())
3. If missing, add it to the mapExpression

4. If wrapped in a conditional (e.g., if (condition) { primaryTraffickerId: ... }), ensure the condition evaluates to true

5. If you made changes, redeploy the static resource:

6. Upload the updated JSON file to the Static Resource
7. Clear any caching if applicable

Step 2: Check Ad Server Settings

1. Navigate to the Ad Server record in Salesforce:
2. Go to the Ad Server object (e.g., csdf__Ad_Server__c)

3. Open the GAM Ad Server record (e.g., record ID a1p58000000P86yAAC)

4. Verify the Default Trafficker settings:

5. Locate the following checkboxes:
   • Default Trafficker
   • Force default trafficker
6. Ensure both checkboxes are UNCHECKED (OFF)

7. If either is checked, uncheck it and save the record

8. Why this matters: When these options are enabled, they may override or interfere with the Primary Trafficker mapping from the Fulfilment record

Step 3: Confirm the User Exists in Google Ad Manager

1. Log in to Google Ad Manager with administrator credentials

2. Navigate to Admin > Users

3. Search for the Primary Trafficker:

4. Search by Ad Server ID (e.g., 245089265)

5. Or search by email (e.g., valeria.benvenuto@ilsole24ore.com)

6. Verify the user status:

7. If the user is inactive or deleted, reactivate or recreate the user in GAM

8. Ensure the user has appropriate permissions for trafficking

9. Note the user's ID and confirm it matches the Ad Server ID stored in Salesforce

Step 4: Re-Push the Fulfilment

1. Open the Fulfilment record in Salesforce (e.g., F-0036202)

2. Click "Push to Ad Server" to retry the push operation

3. Monitor the Outgoing Message log:

4. Navigate to the related Outgoing Message record
5. Check the Notes & Attachments section for the JSON payload file

6. Verify that primaryTraffickerId is present and has a valid numeric value

7. If the push succeeds, verify the Order in GAM to confirm the Primary Trafficker is correctly assigned

8. If the push still fails:

9. Download the Outgoing Message JSON file
10. Check if primaryTraffickerId is present in the payload
11. Review the complete API fault string for additional clues
12. Contact CloudSense Support with the JSON file and fault details

Verification

After completing the resolution steps, verify the fix:

1. Check the Fulfilment record in Salesforce:
2. Confirm the Primary Trafficker field is populated

3. Note the Ad Server ID value

4. Review the Outgoing Message JSON:

5. Open the most recent Outgoing Message record
6. Download the JSON payload from Notes & Attachments

7. Search for "primaryTraffickerId" and confirm it has a numeric value (not null)

8. Verify in Google Ad Manager:

9. Log in to GAM
10. Navigate to the Order
11. Confirm the Primary Trafficker is correctly assigned

Temporary Workaround

If the Order is time-critical and the above steps require additional investigation:

1. Manually set a default Primary Trafficker in the Ad Server settings (as a temporary measure)
2. Push the Order to GAM
3. Manually update the Primary Trafficker in GAM after the Order is created
4. Revert the default setting and implement the proper fix to prevent future occurrences

Prevention

To prevent this issue in future implementations:

• Always include the primaryTraffickerId mapping in fulfilmentStrategy.json for GAM integrations
• Avoid conditional logic around required GAM fields unless absolutely necessary
• Test fulfilment pushes in a sandbox environment after any changes to fulfilment strategy files
• Maintain user synchronization between Salesforce and GAM to ensure all traffickers exist in both systems
• Document any customizations to the fulfilment strategy mapping for future reference

Important Notes

• The Primary Trafficker is a required field for GAM Orders and cannot be null
• This issue can occur with both Programmatic Guaranteed and Direct Orders
• Changes to the fulfilmentStrategy.json require redeploying the Static Resource
• If you have multiple Ad Server records, ensure the correct one is being used for the push
• The error may also occur if the Ad Server ID stored in Salesforce does not match the actual user ID in GAM