REST Field Qualification

Several services need fully qualified fields in one way or the other. The syntax to qualify fields is documented on this page

Product Manager defines many business objects which are described in the Product Manager repository. The repository can be seen as a storage for all meta-data regarding the business models. All objects and all attributes of those objects are described in there. Additionally to that, also the relation between an object and it's child objects is described in the repository. You can find a detailed description about the Repository here.

An example would be the object "Article" and it's child object "ArticleLang". An Article can have multiple "ArticleLang" records, one for each language. Therefore, the language is the attribute which makes the "ArticleLang" records unique for a single item.

images/download/attachments/124131882/FieldQualificationExample.png

To "fully qualify" a field means, that you not only must define which field (by the field's identifier), but also all values for all attributes which identify the children uniquely. In this example, just the language.

Syntax

Fully qualified field: <Field Identifier>[(<first logical key value>,..,<n-logical key value>)]

Multiple Field Qualification: <Fully qualified field>[, <Fully qualified field>]

Element

Definition

Field Identifier

Basically the unique field identifier as given in the custom section of the repository. These identifiers typically but not necessarily start with the entity identifier separated by a "." from the filed's name. This makes the field unique in case of the same field supported by different data entities. Samples are:

  • Article.SupplierAID

  • Article.EAN

  • Article.ManufacturerName

Logical Key Value

The qualification value for the first, second, third and so on logical key. Which logical key is on which position is defined by the hierarchy and the order attribute of the repository logical key type. In case no order attribute is defined in the repository, the order is defined by the relative location in the repository xml file.
<Parent LK 1, ParentLK 2, Own LK 1, Own LK 2>

Logical Key Value Definition

The definition of the logical key value depends on the datatype of the logical key (or it's respective field) and whether the logical key has an enumeration or not.

With Enumeration

You can define everything which can be interpreted by the enumeration as a synonym to one of it's keys. This can be done either as a constant value, or as a string (constants are not allowed to have spaces in it, use strings in this case!)

For example: ArticleLang.DescriptionShort(en), ArticleLang.DescriptionShort(eng), ArticleLang.DescriptionShort(English) would be just the same.

Furthermore the key of an enumeration can be used if it's data type is not an entity item, like buyers, suppliers, units etc.

For example: ArticleLang.DescriptionShort(9)

A special situation would be a logical key which has an enumeration and it's data type is entity item. In this case you can either specify the actual entity item with the entity item syntax, as well as

a string or constant which is then parsed with the enumerations synonyms.

Some enumerations are case sensitive regarding their synonyms. Which one those are is defined in the enumeration itself. You're always on the safe side if you treat all of them as case-sensitive.

Without Enumeration

Logical keys without enumeration must be defined depending on their datatype. Please see the REST Datatypes overview for details.

Datatype

Format

Example

Date (without time!)

YYYY-MM-DD

2012-06-22 which is the 22nd of June in 2012

Time (without date!)

HH:mm:SS

13:15:05 which is quarter past one, pm and five seconds

Date and Time

YYYY-MM-DD HH:mm:SS

2012-06-22 13:15:05

Integer

+#* or -#*

+1247 or -1247

Decimal

+#*.#* or -#*.#*

+1.45 or -1.45 (no thousand seperator, use dot as comma seperator!)

Boolean

true or false

true or false

String

"any string" or "any \"important\" string"

"My Attribute Name" escape the quotation marks by a backslash! E.g. "Size in \"" (meaning: size in inch)

Constant

any string a-Z followed by zero or more 0-9

eng, de, public

ENTITY_ITEM

Entity Item without a container item:

'<external_identifier>'|<internal_id>

Entity Item with a container item:

'<external_identifier>'|<internal_id>@'<container_external_identifier>'|<container_internal_id>

Please don't forget use single quotes when you want
to specify the external identifier of the entity item!

'SomeItem'@'SupplierCat1'

12345@5

'SomeSupplier'

42

Dynamic Value

A dynamic value is a placeholder which will be resolved while parsing the field qualification
Syntax: ${Identifier}

Note: additional named values can be contributed to the PIM server
using the extension point: com.heiler.ppm.value.core.namedValues

Currently available named values:

  • ${CurrentDate} = the current date (without time)

  • ${CurrentTime} = the current time (without date)

  • ${CurrentTimestamp} = the current date and time

Examples

The short description of an article in english: ArticleLang.DescriptionShort(eng)

The public customer price value, in Euro for Germany, Valid on the 06/22/2012, when I order one: ArticlePriceValueSales.Amount(public,net_customer,eur,de,2012-06-22,1.00)

Using default values

If the repository defines a default value for the logical key then the default value can be referenced in the field qualification using the following notation:

${Default}

Note that the resulting fully qualified field may change when the definitions in the repository change.

Using wildcard matching

If no value can be defined as qualification, it is possible to use the

  ${Empty}

qualifier.