|
| 1 | +# From product identifier to product UUID |
| 2 | + |
| 3 | +::: warning |
| 4 | +This guide only concerns Serenity users. |
| 5 | +::: |
| 6 | + |
| 7 | +::: info |
| 8 | +The goal of this guide is to help you to move from a product-identifier-based logic to a UUID one. |
| 9 | +::: |
| 10 | + |
| 11 | +## What will happen? |
| 12 | + |
| 13 | +Soon (summer 2022), we will deploy **6** new API endpoints, endpoints that have the same role as already-existing ones: |
| 14 | +- `GET /api/rest/v1/products-uuid`, same as [GET /api/rest/v1/products](https://api.akeneo.com/api-reference.html#get_products) |
| 15 | +- `POST /api/rest/v1/products-uuid`, same as [GET /api/rest/v1/products](https://api.akeneo.com/api-reference.html#post_products) |
| 16 | +- `PATCH /api/rest/v1/products-uuid`, same as [PATCH /api/rest/v1/products](https://api.akeneo.com/api-reference.html#patch_products) |
| 17 | +- `GET /api/rest/v1/products-uuid/{uuid}`, same as [GET /api/rest/v1/products/{code}](https://api.akeneo.com/api-reference.html#get_products__code_) |
| 18 | +- `PATCH /api/rest/v1/products-uuid/{uuid}`, same as [PATCH /api/rest/v1/products/{code}](https://api.akeneo.com/api-reference.html#patch_products__code_) |
| 19 | +- `DELETE /api/rest/v1/products-uuid/{uuid}`, same as [DELETE /api/rest/v1/products/{code}](https://api.akeneo.com/api-reference.html#delete_products__code_) |
| 20 | + |
| 21 | +And later (during the last quarter of 2022), we will make optional the product identifier value (`pim_catalog_identifier` attribute). |
| 22 | + |
| 23 | +## Why do we do that? |
| 24 | + |
| 25 | +At the time these lines are written (July 2022), a PIM product contains one and only one way of unique identification: the so-called field `identifier` (the only `pim_catalog_identifier` attribute of the whole product). |
| 26 | +In Serenity, this field value is the SKU (Stock Keeping Unit) of the product, but what if you need to identify your product with several product identifiers (SKU, EAN, GTIN,...)? |
| 27 | +Adding classic fields won't do the job: you need a kind of identifier field for each product. |
| 28 | +And how will you identify your product if its SKU has changed? |
| 29 | + |
| 30 | +That's the purpose of the brand-new product UUID feature. |
| 31 | + |
| 32 | +But before making it happen, a product must have a **unique** and **immutable** way to identify it: that's why we introduce the product UUID (for Universally Unique Identifier). |
| 33 | + |
| 34 | +## What are the impacts? |
| 35 | + |
| 36 | +Of course, [Products endpoints](https://api.akeneo.com/api-reference.html#Product) will remain available (and they be enriched with a `UUID` property), even when new API endpoints will be ready for use. |
| 37 | +Nevertheless, when the current product identifier will become optional: |
| 38 | +- [GET /api/rest/v1/products](https://api.akeneo.com/api-reference.html#get_products) won’t return products with empty product identifiers (in other words, you may miss products if you continue to use this endpoint); |
| 39 | +- `associations` property for [GET /api/rest/v1/products](https://api.akeneo.com/api-reference.html#get_products) or [GET /api/rest/v1/products/{code}](https://api.akeneo.com/api-reference.html#get_products__code_) may contain **NULL** values (product associated with a product without identifier); |
| 40 | +- [GET /api/rest/v1/products/{code}](https://api.akeneo.com/api-reference.html#get_products__code_) could result in a 404 error (if the identifier is removed from the product). |
| 41 | + ...and you could encounter some issues with your code. |
| 42 | + |
| 43 | +## What do we advise you? |
| 44 | + |
| 45 | +As soon as product UUID API endpoints are released, jump on the bandwagon right away: |
| 46 | +- Change [product-identifier-based products endpoints](https://api.akeneo.com/api-reference.html#Product) with UUID ones. |
| 47 | +- Every time you identify a product with its identifier in your application, be sure to replace it by corresponding product UUID. You will easily find the match between product identifier and UUID in both [products endpoints](https://api.akeneo.com/api-reference.html#Product) and new ones. |
| 48 | + |
| 49 | +## An example of what you may have to do? |
| 50 | + |
| 51 | +Let's imagine you developed a product-identifier-based solution that synchronizes PIM products to a random eCommerce solution. |
| 52 | + |
| 53 | +You persist the correlation between PIM products and eCommerce ones in a correlation table. |
| 54 | + |
| 55 | +```code |
| 56 | + TABLE correlation { |
| 57 | + akeneo_identifier, |
| 58 | + ecommerce_identifier |
| 59 | + } |
| 60 | + ``` |
| 61 | + |
| 62 | +Today, its running is as follows: |
| 63 | + |
| 64 | +```code |
| 65 | + Get all Akeneo products with GET /api/rest/v1/products |
| 66 | + For each retrieved products: |
| 67 | + identifier = identifier of the product |
| 68 | + Get the ecommerce_identifier matching identifier by querying the correlation table |
| 69 | + if ecommerce_identifier was not found |
| 70 | + Add the product to the eCommerce |
| 71 | + Add (identifier, ecommerce_identifier) in the correlation table |
| 72 | + else |
| 73 | + Update the product identified by ecommerce_identifier in the eCommerce |
| 74 | + ``` |
| 75 | + |
| 76 | +How do you turn your application into a product-UUID one? |
| 77 | + |
| 78 | +Firstly, replace the way of getting Akeneo products: from `GET /api/rest/v1/products` to `GET /api/rest/v1/products-uuid`. |
| 79 | +Then, add a `UUID` column to your correlation table. |
| 80 | + |
| 81 | +```code |
| 82 | + TABLE correlation { |
| 83 | + akeneo_identifier, |
| 84 | + akeneo_uuid, |
| 85 | + ecommerce_identifier |
| 86 | + } |
| 87 | + ``` |
| 88 | + |
| 89 | +And at last, step by step, replace `akeneo_identifier` in your correlation table with `uuid` |
| 90 | + |
| 91 | +```code |
| 92 | + Get all Akeneo products with GET /api/rest/v1/products-uuid |
| 93 | + For each retrieved products: |
| 94 | + identifier = identifier of the product |
| 95 | + uuid = uuid of the product |
| 96 | + Get the ecommerce_identifier matching uuid in the correlation table |
| 97 | + if ecommerce_identifier was not found |
| 98 | + Get the ecommerce_identifier matching identifier in the correlation table |
| 99 | + if ecommerce_identifier was found |
| 100 | + Add uuid in the correlation table |
| 101 | + Update the product in the eCommerce |
| 102 | + else |
| 103 | + Add the product to the eCommerce |
| 104 | + Add (identifier, uuid, ecommerce_identifier) in the correlation table |
| 105 | + else |
| 106 | + Update the product identified by ecommerce_identifier in the eCommerce |
| 107 | + ``` |
| 108 | + |
| 109 | +::: info |
| 110 | +If you need help, don't hesitate to [contact us](https://www.akeneo.com/contact/)! |
| 111 | +::: |
0 commit comments