Discussion about the respective role of the UUID and document-style identifier

[patricekrakow]

1/ The idea is to keep the UUID "in the lead" (according to API design) but to make it mandatory to always have a document-style identifier companion to make the link with a document or an e-document.

2/ To reference a "concept" (e.g. order) within another "concept" (e.g. shipment) we should use UUID, but we should also allow such references using a document-style identifier in some cases, e.g. when a shipment refers to an order?

3/ The document-style identifier should not use a generic otherIdentifier structure, but should be individually named, e.g. orderNumber.

4/ The document-style identifier(s) should be MANDATORY.

[patricekrakow]

We will update the API endpoints of the Catalogue use case accordingly with productSellerNumber and customerArticleNumber as document-style identifiers, but we will not allow point 2, a customer-article can only refer to a seller-product using the UUID. It is different when a shipment refers to an order.

[patricekrakow]

The API endpoints of the Catalogue use case should be updated as follow:

[ ] Within ListSellerProducts change otherIdentifier into sellerProductNumber [ ] Within ListSellerProducts make the sellerProductNumber required [ ] Within ListSellerProducts make the status required [ ] Within GetSellerProductById change otherIdentifier into sellerProductNumber and GetSellerProductById [ ] Within GetSellerProductById make the sellerProductNumber required [ ] Within GetSellerProductById make the status required

[ ] Within CreateCustomerArticle change otherIdentifier into customerArticleNumber [ ] Within CreateCustomerArticle make customerArticleNumber required [ ] Within CreateCustomerArticle remove sellerProductOtherIdentifier [ ] Within CreateCustomerArticle remove sellerProductStatus [ ] Within CreateCustomerArticle make status required

[ ] Within ListCustomerArticles change otherIdentifier into customerArticleNumber [ ] Within ListCustomerArticles make customerArticleNumber required [ ] Within ListCustomerArticles remove sellerProductOtherIdentifier [ ] Within ListCustomerArticles make status required

[ ] Within GetCustomerArticleById change otherIdentifier into customerArticleNumber [ ] Within GetCustomerArticleById make customerArticleNumber required [ ] Within GetCustomerArticleById remove sellerProductOtherIdentifier [ ] Within GetCustomerArticleById make status required

[patricekrakow]

OK, we will always have a document-style identifier companion with each UUID and it will be mandatory. Ready to propose a PR.

[patricekrakow]

@patricekrakow is questioning the fact that the sellerProductNumber and the customerArticleNumber properties should be required. We can start by not having them required. These properties are there to support the legacy document-style identifiers, so we should not make them required in order to push people to an API way of thinking. On the other hand, these sellerProductNumber and the customerArticleNumber properties remain available to be used. For now, we have decided to keep them as not required. @patricekrakow can prepared a PR for it.

[patricekrakow]

ADDITIONAL QUESTION: Should the sellerProductNumber and the customerArticleNumber be a simple string or should they be a more complex structure, like the ProductIdentifier in the papiNet XSD?

<xs:element name="ProductIdentifier">
  <xs:complexType>
    <xs:simpleContent>
      <xs:extension base="s60">
        <xs:attributeGroup ref="AgencyInfo"/>
        <xs:attribute name="ProductIdentifierType" type="productIdentifierType" use="required"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
</xs:element>

<xs:attributeGroup name="AgencyInfo">
  <xs:attribute name="Agency" type="agencyCode" use="required"/>
</xs:attributeGroup>

<xs:simpleType name="agencyCode">
  <xs:restriction base="xs:string">
    <xs:enumeration value="AFNOR"/>
    <xs:enumeration value="AFPA"/>
    ...
    <xs:enumeration value="Other"/>
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="productIdentifierType">
  <xs:restriction base="xs:string">
    <xs:enumeration value="BrandName"/>
    <xs:enumeration value="CASNumber"/>
    ...
    <xs:enumeration value="Other"/>
  </xs:restriction>
</xs:simpleType>

In order to have a better compatibility with the XML messages, we could define sellerProductIdentifier and customerArticleIdentifier as follow:

"sellerProductIdentifier": {
  "agengyCode": "...",
  "type": "...",
  "value": "..."
}

"customerArticleIdentifier": {
  "agengyCode": "...",
  "type": "...",
  "value": "..."
}

REMARK: In papiNet XML, we do not make an explicit distinction between seller-product and customer-articles. The distinction is made implicitly via the combination of Agency and ProductIdentifierType.

[patricekrakow]

I will close this issue as we have re-created an issue #125 to continue the discussion. I will refer to this issue within the issue #125.