To make use of third-party interface codes, one needs to be familiar with the computer programming concept of enumerated types. In general, an enumerated type consists of a type name and a list of possible values. For example, we could define "StorageTemperature" as an enumerated type with three possible values: "RoomTemp", "Refrigerated", "Frozen". It is often useful to define a data field with an enumerated type in order to convey what values are supported and restrict the data to those values. A pulldown menu that allows a single selection is a user interface often used to fill a data field that has been defined with an enumerated type.

Note that the possible values that belong to an enumerated type are often called enumerated values. When defining an enumerated type, you must ordinarily give it a and a list of enumerated values which each have a name representing a value.

The POST /interfaces/thirdpartycodes endpoint allows a developer to define their own interface codes to serve as enumerated values. Each one is associated with a specified enumerated type. The developer defines the following properties:

• The interface code will belong to an enumerated type specified by the "type" property.
• A "code" property defines the enumerated value that this interface code will represent.
• A "description" property allows an explanatory comment to be attached to each interface code.
• The interface code is scoped to a store specified by the "store.id" property.

If a new interface code is defined with a "type" name that has not yet been used in the scope of the specified store, a new enumerated type will be created. Interface codes are simply enumerated values that get grouped into enumerated types where the "type" and "store.id" properties happen to match.

A software developer integrating a POS or other system with a Yellow Dog inventory database may find it necessary to annotate inventory items with their own third-party interface codes. For example, they may want to be able to associate particular items with specific menus on a POS terminal or tax categories. They may also need to a way to know which items are relevant to the integration and which items should be ignored.

The use of third-party interface codes to perform this annotation is a multi-step process:

• First, the developer designs enumerated types name-spaced to their integration for the annotations they care about.
• Second, they use the POST /interfaces/thirdpartycodes endpoint to define corresponding "type" and "code" properties.
• Third, instructions are provided to customers regarding when and how to annotate items with the specific third-party codes.
• Fourth, customers or support staff use pulldown menus in the "Interfaces" tab of various YDInv.exe to apply annotations.

Note that name-spacing need only be applied to the "type" property. If the name of the integrated product is "ACME" and the purpose of the enumerated type is a tax category, an appropriately name-spaced "type" property would be "ACME_TaxCategory" with an underscore character separating the name-space from the purpose name.

The instructions for annotating items will usually not expect items to be individually annotated with third-party interface codes. The codes will most often be applied to a level category, such as alcoholic beverages, so that all items belonging to that category will inherit a specified interface code. Default codes can also be specified for all items in a store and be overridden by individually assigning a code to an item.

When designing a list of enumerated values for a third-party code type that will be used to annotate items, it is important to ask whether all possible cases have been covered. It is often the case that some kind of none-of-the-above value needs to be included to support items where the category itself is not relevant. Consider Example A, which is used to specify a tax category. In addition to county and state tax categories, an untaxed category is defined as a catch-all for items where taxation is not relevant.

In YDInv.exe, there is an inherent option to leave a third-party code type as "unset", meaning that none of the available values is chosen for that enumerated type. This cannot be relied upon to serve as a none-of-the-above value because it does not provide a way to override a default setting inherited from a level category or store. In order to support a none-of-the-above selection, there has to be an explicit value that represents it. This is true even if it is interpreted as having the same effect as leaving the third-party code type "unset".

There is a special third-party interface code type called "ItemNumber". It serves as an enumerated type whose values are POS specific item numbers to be populated into a YDInv.exe POS item map which is scoped to a specific store. When using the POST /interfaces/thirdpartycodes endpoint to add POS items to an item map, the usual interface code properties are specified and have the following effects:

• "type" -- must be "ItemNumber".
• "code" -- specifies a number that the POS uses to uniquely identify the item on its side
• "description" -- will become the description field for the item
• "store.id" -- applies to the POS item map for the specified store

It is possible, although rarely useful, to use a wild card value when specifying the "store.id" property. Since this property is a UUID, an all zero value is used to represent a wild card that applies the enumerated type to all stores in the database. For small databases with only a couple of stores that all use the same POS, it may be reasonable to use this wild card. However, when using third-party interface codes to integrate a POS, it rarely makes sense to do things that limit the integration in this way. As soon as a larger customer comes along with separate POS systems for F&B and retail in a database with more than a couple of stores, some operations will become slower than necessary and it will be easy to for customers to make mistakes once enumerated types start showing up in stores where they are not relevant. These factors are likely to prevent an integration from being certified for larger customers.

Note that it is easy to accidentally invoke the store wild card by omitting the "store.id" property and leaving the API to imply a null value. Avoid this mistake and only specify the store wild card when faced with the rare good reason to do so.

Example A defines a new enumerated type called "ACME_TaxCategory". The "ACME_" prefix applies a name-space to associate this enumerated type with the POS integration that defines it. Three enumerated values are added to this enumerated type to represent county, state, and untaxed tax categories. Note that each of the third-party interface codes created to represent these enumerated values are scoped to the same store. It will be the only store that can annotate level data or items with this enumerated type. It may also be the only store that this ACME POS is configured to use.

Example B defines a new enumerated type called "ACME_ModifierFlag". As in Example A, the name-space prefix and descriptive name are separated by an underscore character. Since this is type is a flag, it defines "true" and "false" enumerated values in the "code" properties. In this case, "true" and "false" are just name strings with no special function other that their descriptive qualities. Alternatively, "enabled" and "disabled" would also be reasonable values for an enumerated type that is serving as a flag.

For reasons described above in the section entitled "Defining a none-of-the-above value", it is necessary for any boolean flag type to explicitly define values for both the on and off state such that the off state has the same effect as leaving the value "unset".

In Example C, there is no name-space prefix because the special "ItemNumber" type name is being used to add items to the POS item map of the specified store. This is the only time that a developer should specify an interface code type without a name-space prefix.

Note that the section entitled "Defining a none-of-the-above value" does not apply to the special "ItemNumber" type.