Directives

Directives

Directives are a powerful Propeller REST APIs concept only used in bulk endpoints. Use directives for actions that are otherwise only doable via a lot of single endpoint API requests. Directives concept is easiest to understand via use cases.

• Let's assume a large number of products is being created/ updated using the Product Bulk endpoint and Propeller's back office is used to maintain some of the data, e.g. product names. When products are created via the bulk endpoint they should not be created with an empty product name. That name can later be changed and we don't want to overwrite it. If it were a single resource endpoint, the GET endpoint could be used to check if the product exists, find the name, compare it, etc. That is not really efficient on a large scale. This is where skipIfNotEmpty directive comes handy. Use this directive when you only want to set a field with the value from the payload if it's current value is an empty string.
• Another use case is using Propeller to move resources in a different parent container that the one they were originally created in. Let's assume you have a list of products that belong in certain categories and those products are created via the Bulk endpoints. If you decide to maintain the catalogue structure from within Propeller you would typically move products around manually or via Propeller's rule engine. To avoid a Bulk endpoint would move them back to their original endpoint, use the skipMoveOnUpdate directive.
• When creating categories/ product translations you typically have a list of all the active translations you want the resource to be translated in. When using a single resource endpoint you can delete translations one by one, but in the Bulk endpoints use mergeTranslationsOnUpdate to reset i.e. delete the ones that are not in the payload.

Name	Description	Fields
skipIfNotEmpty	On update, skip updating fields of an existing resource that are not empty	array of field names, API specific e.g. for products : names, descriptions, etc.
skipMoveOnUpdate	On update, skip moving an existing resource in the parent resource provided	empty array
mergeTranslationsOnUpdate	On update, delete all translation for a resource that are not provided in the payload	empty array
skipCreate	Skip creating new, only update existing resources	empty array