ArticleProperties
Synopsis
struct ArticleProperties {
string* catalogId;
string* manufacturerId;
DisplayText? manufacturerName;
string* seriesId;
DisplayText? seriesName;
string* manufacturer;
string* program;
string* distributionRegion;
string* baseArticleNumber;
string* finalArticleNumber;
string* variantCode;
string* ofmlVariantCode;
boolean* useFinalArticleNumber;
string* shortText;
string* longText;
string* featureText;
ArticleDescriptionMode* descriptionMode;
ArticleDescription productDescription,
ArticleDescription userDescription,
string currency,
string purchaseCurrency,
string salesCurrency,
decimal purchasePrice,
decimal salesPrice,
boolean priceDateSupported,
boolean priceDateEditable,
date priceDate,
decimal quantity,
boolean alternativePosition,
string[] excludedCalculations,
InactivePositionState[] inactivePositionState
boolean inconsistencyFlag,
DisplayText[] inconsistencyReason,
PriceInfo priceInfo,
PackagingInfo packagingInfo,
boolean pseudoArticle,
boolean? nonOfferArticle,
boolean nonOrderArticle,
ArticleClassification[] articleClassifications,
OFMLUpdateState ofmlUpdateState,
string geometryId,
ArticleProperties[] subArticles,
AddStateCode[] addStateCodes,
boolean? Discountable,
boolean? HasGLDFInfoHint,
PreConfigurationData? preConfigurationData; // optional element
}
See also: DisplayText, ArticleDescriptionMode, ArticleDescription, date (unresolved source reference), InactivePositionState, PriceInfo, PackagingInfo, ArticleClassification, OFMLUpdateState, ArticleProperties, AddStateCode
The ArticleProperties structure is referenced by the ItemProperties (§ItemProperties) structure. The fields of this structure correspond to basket item properties specific to article items. The fields are as follows:
catalogId
If the article is an OFML or OCD article, then this field contains the identifier of the catalog containing the product data of the article if the catalog is represented by a catalog profile (as opposed to an old-style manufacturer profile). See §CatalogItem for more information about catalog identifiers.
manufacturerId
This field contains the commercial identifier of the article’s manufacturer. When used with the setItemProperties (§setItemProperties) operation to set the properties of a user article or set article, this field should contain either a null reference, an empty string or a valid manufacturer ID (see below).
manufacturerName
This field contains the name of the manufacturer. The manufacturer name depends on the manufacturer ID.
It is of type DisplayText to allow future versions of EAIWS to add support for formatted manufacturer names without the need to add another text format option to GetItemPropertiesOption. If and when such support is added, option textFormat will control the format of the returned manufacturer names. Until then, these names will always be returned as plain text with no format being set. However, for this to work as intended, clients which pass the textFormat option to operation getItemProperties (with a value other than Plain) should be prepared to receive formatted manufacturer names.
As of now, field lang of returned manufacturer names is always unset. Whilst unlikely, this may change in future versions of EAIWS if operation getItemProperties is invoked with option textFormat being set.
seriesId
This field contains the identifier for the article’s series. When used with the setItemProperties (§setItemProperties) operation to set the properties of an user article or set article, this field should contain either a null reference, an empty string or a valid series ID (see below).
seriesName
This field contains the name of the article’s series. The series name depends on the manufacturer ID and series ID.
It is of type DisplayText to allow future versions of EAIWS to add support for formatted series names without the need to add another text format option to GetItemPropertiesOption. If and when such support is added, option textFormat will control the format of the returned series names. Until then, these names will always be returned as plain text with no format being set. However, for this to work as intended, clients which pass the textFormat option to operation getItemProperties (with a value other than Plain) should be prepared to receive formatted series names.
As of now, field lang of returned series names is always unset. Whilst unlikely, this may change in future versions of EAIWS if operation getItemProperties is invoked with option textFormat being set.
Manufacturer, program, distributionRegion
The elements contain the OFML manufacturer, OFML program and OFML distribution region of the package containing the OFML article data last used to insert or configure the OFML article.
Fields manufacturer and program should always be present in return value of operation getItemProperties for items of type Article, Aggregate and PartialPlanning. Field distributionRegion is usually present for items of these types unless the OFML article item has been read from a BSK/OBX stream and the corresponding <pdInfo> element did not have attribute region.
baseArticleNumber
This field contains the base article number.
finalArticleNumber
This field contains the final article number.
variantCode
This field contains the variant code.
ofmlVariantCode
This field contains the OFML variant code of the OFML article. Other than the ordinary variant code, the OFML variant code always uses a key-value encoding, allowing it to be reliably parsed. This element is returned for OFML articles only.
useFinalArticleNumber
If true, the client should display the final article number. If false, the client should display the base article number. This element is returned for OFML articles only.
shortText
This field contains the short description of the article. While not enforced by the Online Configurator, the short description should consist of a single line of text only. The short description describes the article and is supposed not to depend on the current configuration of the article.1 It returns the text as plain text, even if the text is stored as formatted text.
longText
This field contains the long description of the article, possibly consisting of multiple lines of text. The long description may describes the article in more detail than the short description, but, like the short description, should not depend on the current configuration of the article. It returns the text as plain text, even if the text is stored as formatted text.
featureText
The feature description describes the configuration-dependent features of the article. It returns the text as plain text, even if the text is stored as formatted text.
DescriptionMode
The field will always be present in instances of ArticleProperties returned from the server to the client. It is optional because the client does not need to set this field when it passes an instance of ArticleProperties to the server. In fact, setting this field has no effect2.
currency
If the article position has a price, then this field contains the ISO 4217 currency code of the price (pseudo-currency codes are not supported).
PurchasePrice
This field contains the purchase price as read from the product database, possibly adjusted by an OFML price profile. If no purchase price could be determined, the field is not available. The field will not be provided if the currencies of purchase price and sales price are different and the value of the purchase price is non-zero.
SalesPrice
This field contains the sales price as read from the product database, possibly adjusted by an OFML price profile. If no sales price could be determined, the field is not available.
priceInfo
This field is used to return price information if option priceInfo in type GetItemPropertiesOptions is true, return of price information is enabled3 and valid price information could be determined. No valid price information can be determined if the sales unit size and/or quantity of the calculation do not have finite values or, in merge mode Compact, the article properties are returned for a sub-article item and the quantity of the main article item is zero4.
quantity
This field contains the position’s quantity. The exact meaning depends on the article’s order unit. The Online Configurator does not limit the quantity to a certain range or step size.
alternativePosition
This field indicates whether or not the position is an alternative position. Alternative positions are supposed to be ignored when the total value of an order (or sub-totals for folders) are computed.
The alternativePosition element of complex type articleProperties has been deprecated, but is still supported for backward compatibility. With the new implementation, the value is true if the excluded calculation set is either the universal set or contains the names of all calculations (pricing procedures) used by the basket.
excludedCalculations
This field indicates the names of all price calculations which consider the item an alternative position (the name of a price calculation is equal to the name of the pricing procedure used by this calculation). As a special case, this set may be the universal set, containing all possible price calculation names. The universal set is represented by a set containing only the empty string.
Note that the excludedCalculations elements are used by the getItemProperties operation only. The setItemProperties operation ignores these elements, if present.
inconsistencyFlag
The value of this field indicates whether or not the Online Configurator detected an inconsistency in the article’s current configuration.5 If this field is true, an inconsistency has been detected, and the article’s price and/or the position’s value are probably invalid.
inconsistencyReason
If the value of field inconsistencyFlag is true, then this field should contain a description of the inconsistency’s reason or reasons.
It is of type DisplayText to allow future versions of EAIWS to add support for formatted inconsistencyReasons without the need to add another text format option to GetItemPropertiesOption. If and when such support is added, option textFormat will control the format of the returned series names. Until then, these information will always be returned as plain text with no format being set. However, for this to work as intended, clients which pass the textFormat option to operation getItemProperties (with a value other than Plain) should be prepared to receive formatted texts.
As of now, field lang of returned inconsistencyReasons is always unset. Whilst unlikely, this may change in future versions of EAIWS if operation getItemProperties is invoked with option textFormat being set.
packagingInfo
When used with the getArticleProperties operation, this field contains a reference to an instance of the PackingInfo (§PackagingInfo) structure. When used with the setArticleProperties operation, the value of this field is ignored if the item is not an UserArticle (§BasketItemType). If the item is an UserArticle, the field should contain a reference to an instance of PackingInfo.
ofmlUpdateState
If the getItemProperties operation is used to get the properties of an OFML article item, this element will be present and contains the update state of the article.
See also: getItemProperties
The update state returned here is always with respect to the full set of registered OFML catalogs. Furthermore, since computation of the update state may be a somewhat expensive operation, the update state is returned if and only if it is already known. If not, the returned update state is Unknown.
geometryId
The element occurs in result of operation ‘getItemProperties’ if and only if the necessary set of geometry checksums is stored in the corresponding basket article item (i.e. no attempt is made to get them from the OFML article item, even if the OFML article item has already been instantiated). This should always be the case unless the article item has been loaded from old BSK/OBX data, or from BSK/OBX data written by another application.
In case of main article items the geometry ID consists of the geometry checksum for the whole (composite) article. For sub-article items it consists of the geometry checksum for the whole sub-article plus a checksum computed for the transformation of the sub-article relative to the main article.
subArticles
This field is used to return data about sub-articles if operation getItemProperties has been called for a view item of type PartialPlanning or Aggregate, the view uses display mode Sorted and merge mode Compact, and the item has sub-articles.
inactivePositionState
This field is a possibly empty array of instances of InactivePositionState, one for each pricing procedure that treats the position as an inactive position, or with a wildcard element whose ppName is empty. View items may additionally return explicit overrides; see InactivePositionState.
discountable
reflects the value of OFML article attribute Discountable. It’s default value (i.e. the value a client should assume if the field is not present) is true.
hasGLDFInfoHint
The field, if present, hints at the availability of GLDF information for the article, and thus the possibility to perform a GLDF or L3D export.
The field may be present in the article properties of basket items of type Article, Aggregate, and PartialPlanning, and view items referencing basket items of these types if the view uses merge mode None, assuming the information is available at all. (It may not be available if the article has been inserted or last updated by an older version of EAIWS or by an application using the C++ EAI.) Even if the field is present, its value is not authoritative unless the value of field ofmlUpdateState is UpToDate.
Valid manufacturer and series IDs consist of a non-empty sequence of graphical ASCII characters except quotation mark ("), asterisk (*), slash (/), colon (:), less-than sign (<), greater-than sign (>), question mark (?), backslash (\) and vertical line (|)6.
The purchase price and sales price are the prices of one order unit. They need to be multiplied by the quantity to obtain the position’s value. They are not set to zero if the position is an alternative position.
Fields pseudoArticle and nonOrderArticle are returned for all article items, even though they are, as of now, only meaningful for OFML article items.
Field articleClassifications is returned for all article items except set-article items, and only if option articleClassifications in GetItemPropertiesOptions is set to true.
All three new fields are ignored by operation setItemProperties.
preConfigurationData
Returned for basket main article items while they are in pre-configuration. Contains the dialog’s actionId; see PreConfigurationData and oapFinishPreConfiguration.
Footnotes
-
This does not mean that the (short) description of an article position does not change if a property of the position is changed. For instance, in the case of meta types, a property change may select another article, and thus result in another (short) description. ↩
-
Operation
setItemPropertiesignores an article description mode specified by the client. ↩ -
application feature
egr.eai.ws.basket.ReturnPriceInfois available ↩ -
To determine the quantity of the sub-article item it is necessary to divide the total quantity of the sub-article item, as returned by the corresponding item property, by the quantity of the main article item, thus resulting in division of zero by zero if the main article item’s quantity is zero. While this problem could be circumvented with a new property that contains the sub-article item’s quantity relative to the main article item, this would not help much as the net value returned by the calculation would be zero too, and thus there would be no (easy) way to compute a net price. ↩
-
The fields
inconsistencyFlagandinconsistencyReasonmay also be used to report other problems preventing the Online Configurator from the computation of a valid price or value for this position. ↩ -
While there seems to exist no official definition of valid manufacturer and series IDs, the Online Configurator restricts them to a set of characters that are not known to cause problems in certain contexts. For instance, Microsoft Windows prohibits the use of certain characters in file names. These characters should not be used in manufacturer IDs either, as manufacturer IDs are used as the base name of manufacturer registration files (
<data>/registry/<manufacturer_id>.cfg). ↩