Conditionally mandatory attributes
How to make an attribute mandatory only when another attribute has a specific value.
Many channels require an attribute only in specific cases. For example, a marketplace may require the attribute cell_composition only for products that contain batteries. A conditionally mandatory attribute covers this case: it stays optional by default and becomes mandatory as soon as any of its conditions is met.
How conditions work
Every conditionally mandatory attribute has at least one condition. A condition compares the value of another attribute of the same export template, called the trigger attribute, to a value you define:
| Setting | Description |
|---|---|
| Trigger Attribute | Another attribute of the same export template whose value activates the condition. An attribute can't trigger itself |
| Operator | equals, not equals, or is present |
| Trigger Value | The value the platform compares the trigger attribute's value to. Not used with the is present operator |
| Description | An optional hint that tells users where to find or set the trigger attribute, for example, Product > Compliance > Batteries Required |
When any condition of an attribute is met, the attribute becomes mandatory. The attribute stays optional only while none of its conditions are met.
With the is present operator, the condition is met whenever the trigger attribute has any non-empty value, so you don't enter a trigger value.
Set an attribute as conditionally mandatory
To make an attribute conditionally mandatory in the Developer Portal, take these steps:
On the export template setup page, go to the section Attributes and analyzer tests, and select the name of the attribute you want to set up.
In Type, select Conditional. The Conditions Editor appears with one empty condition.
Set up the condition by choosing a Trigger Attribute and an Operator. For equals and not equals, also enter a Trigger Value (the is present operator doesn't need one). You can also enter a Description to help users find the trigger attribute.
To add another condition, select Add Condition. The attribute becomes mandatory as soon as any condition is met.
Select Save.
Your changes don't become available in the platform until you select Publish. See Publish export template changes.
Manage conditionally mandatory attributes via the API
Attributes in the Export Template Management API carry an optional type field with the values optional, mandatory, or conditionally_mandatory, plus a conditions array. The type field takes precedence over the legacy mandatory boolean when you send both.
This example makes an existing attribute conditionally mandatory:
curl -X PATCH "https://export-template-api.productsup.com/V1/export-templates/{templateId}/attributes/{attributeId}" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"type": "conditionally_mandatory",
"conditions": [
{
"triggerAttribute": "batteries_required",
"triggerValue": "true",
"operator": "equals",
"description": "Product > Compliance > Batteries Required"
}
]
}'Each condition accepts these fields:
| Field | Required | Description |
|---|---|---|
triggerAttribute | Yes | The name of another attribute of the same export template whose value activates the condition |
triggerValue | Conditional | The value the trigger attribute's value is compared to. Required for equals and not_equals; omit or leave empty for is_present |
operator | No | equals, not_equals, or is_present. Defaults to equals |
description | No | A human-readable hint that tells users where to find or set the trigger attribute |
The API validates these rules:
- An attribute with the type
conditionally_mandatoryneeds at least one condition. - Attributes with the types
optionalandmandatorycan't have conditions. - The trigger attribute must be an existing attribute of the same export template.
- An attribute can't reference itself as a trigger attribute.
- A trigger value is required unless the operator is
is_present.
The same type and conditions fields are available when you create attributes via POST /V1/export-templates/{id}/attributes, when you use the bulk endpoints, and in the attributes array of POST /V2/export-templates. All endpoints that return attributes include the type and conditions fields in their responses.
Related
How is this guide?