In SDM, fields of type  "select"  refer to option collections to determine their available options. 

Example of a type “select” field definition:

{
.   "name": "my_select_field",
.   "groups": ["my_family"],
.   "requirement_level": "optional",
.   "type": "select",
.   "options_collection_name": "my_option_collection",
	"multiple": false
}

Option collections represent list of options, and have a name used to identify it in field definitions. See options_collection_name property in the example above.

The options in an option collection can be modified if needed, through 2 different methods.

Options collection not depending on external source of truth

This method should be used only if the configuration of your SDM project does not directly depend on an external source of truth via any connector.

In particular if your project is maintained through the Akeneo PIM connector, do not use this method as your modifications will be overwritten the next time the connector synchronizes the SDM configuration with the PIM catalogue structure.

Example request

PATCH https://sdm.akeneo.cloud/api/v1/options_collections/{id}/update-options/ 
{
.   "upsert_options": [
		{
			"name": "my-new-option-name",
			"label": {
				"en-US": "My new option",
				"fr-FR": "Ma nouvelle option"
			}
		}
	],
	"delete_options": ["my-old-option-name"],
	"delete_all": false
}

Example success response

{
	"id": 6,
	"name": "my-option-collection",
	"project": 67	
}

Derived from from an Akeneo PIM attribute definition

When using an Akeneo connector, the following attributes will give rise to the creation of a type “select”  field with an associated options collection:

• single / multi select attributes
• reference entities
• for prices, the currency will be defined as a select field in SDM, with an associated option collection
• for measurements, the unit will be defined as a select field in SDM, with an associated option collection

Currently depending on the PIM connector configuration used for your project, it may be possible to add new options / reference entities directly to the PIM and SDM at the same time for select and reference entities attributes. For this, the flag allowed_options_for_pim_attribute_addition should be set to be the list of attribute codes for which you want to allow this behaviour.

How to setup and use the PIM connector

Identifying option collections

The option collection name is generated from the PIM attribute name, thus allowing unique identification. For single/multi select attributes and reference entities attributes from the PIM, the name of the options collection in SDM will be derived from:

• the PIM attribute code
• the PIM locale code if the attribute is localizable
• the PIM channel code if the attribute is scopable 

hence the value will be:

• if the attribute is not localizable nor scopable: {attribute_code}
• if the attribute is localizable, but not scopable: {attribute_code}-{locale_code}
• if the attribute is scopable, but not localizable: {attribute_code}-{channel_code}
• if the attribute is scopable and localizable: {attribute_code}-{locale_code}-{channel_code}

In order to access existing attribute collections for the project, you can use the corresponding endpoint (the endpoint is paginated; page numbers start at 1):

GET https://sdm.akeneo.cloud/api/v1/options_collections/options_collections?page=1&limit=25

Response example:

{
  "count": 125,
  "previous": null,
  "next": "https://sdm.akeneo.cloud/api/v1/options_collections/options_collections?page=2&limit=25",
  "results": [
    {
      "id": 5,
      "name": "my_first_pim_select_attribute",
      "project": 67
    },
    {
      "id": 6,
      "name": "my_second_pim_select_attribute-en_US",
      "project": 67
    },
    {
      "id": 7,
      "name": "my_third_pim_select_attribute-en_US-ecommerce",
      "project": 67
    },
    ...
  ]
}

This will allow you to retrieve the id of the option collections you're looking for, which you'll need to add new options.

Adding options to SDM and the PIM at the same time

Example request:

PATCH https://sdm.akeneo.cloud/api/v1/options_collections/{id}/add-options/
{
.   "upsert_options": [
		{
			"name": "my-new-option-code",
			"label": {
				"en-US": "My new option",
				"fr-FR": "Ma nouvelle option"
			}
		}
    ]
}

Example success response:

{
	"id": 6,
	"name": "my_second_pim_select_attribute-en_US",
	"project": 67
}

Note that you cannot update existing options through this endpoint.