Skip to content

Getting started

This guide is intended as a walkthrough of the minimum steps necessary to add product data to Bizzkit PIM and enrich the products with attribute data, as well as to fetch the generated front-end views for the products.

For a more thorough walkthrough of the abstractions and principles provided by Bizzkit PIM, please refer to the concepts page.

Setup Environment

The first thing to do is set up a local Bizzkit development environment. A detailed guide for doing this can be found here.

Roles and permissions

The guide assumes that the IAM is installed and configured. By default a fresh installation will contain only a single role, 'admin', which has only the minimally required set of rights to begin setting up the system, these rights being 'Log In', 'List and View Roles' and 'Manage Application Permissions'.

In a fully running PIM system, best practice is to manage individual roles, each with a minimally sufficient set of rights. For this getting started guide however, we will start by making the admin role a superuser with all permissions.

Lock-out possible

It is possible for the admin user to remove their own rights, effectively locking themselves out of the system.

If you find yourself in this situation, the easiest way back in is by running the PIM Console command 'add-admin-role' to re-seed the admin role along with the required permissions.

  1. Go to settings by clicking the gear icon in the top right corner and selecting 'Administration'.
  2. Click 'Roles' on the left sidebar and open 'admin' by clicking 'View'.
  3. Edit the permissions by clicking on the 'Edit' button.
  4. Select the desired permission and save. Assign the admin role 'AllApplicationPermissions' to give them full access to all parts of the system.

After altering the permission structure, it is necessary to wait a few minutes for the cache to time out and permissions to be reloaded. You will know this has happened when the 'Products', 'Hierarchies' and 'Attributes' menu items appear in the top bar.

Segmentations

A freshly installed PIM will contain a default segmentation which consists of the four default segmentation dimensions (see Concepts - Segmentations) but without 'Auto Publish to Frontend' enabled.

In order for front-end views to be generated for products, hierarchies, etc. to be retrieved from the public API, at least one segmentation must be set up with 'Auto Publish to Frontend' set to 'true'.

To make this change for the default segmentation

  1. Go to settings by clicking the gear icon in the top right corner and selecting 'Administration'.
  2. Click 'Segmentations' on the left sidebar and open the default segmentation by clicking the 'Edit' button.
  3. Check the box in the Auto Publish to Frontend' column and click 'Save'.

Published views will now be available for segmentation id '1' from the public API.

Attributes

All custom metadata beyond the most basic properties, such as external IDs for products, is handled by assigning user-defined attributes to products and giving them values. To add a few attributes to the solution, navigate to the 'Attributes' tab in the top bar, then click 'Create New'.

The fresh attribute must be given a system name (which will be used to identify the attribute when interacting through the API or import/export system) and a human-readable description. System names must be upper-case and may contain numbers and underscores, but may not start with a number. Finally, the configuration type must be selected, which will govern how many fields and what field datatypes are allowed (See Concepts - Attributes), and whether the attribute is 'Single value' or 'Multi value'. For demonstration purposes we will create a 'Plain', 'Single value' attribute.

To finish configuring the attribute, click the 'View' button on the right hand side of the data row to go to the attribute configuration page.

In the 'Fields' section, configure your new attribute by selecting 'Type' from the 'Type' dropdown, followed by choosing a Pim Data Type (See Concepts - Data Types) from the second drop-down. For the sake of example, lets select the PInt32 data type.

Attribute configuration freeze

If experimenting with attribute definitions, be aware that once an attribute is fully configured the configuration is locked and cannot be changed at a later time.

This means that if an attribute is created with e.g. a single PString field, and it is later discovered that there is a requirement for segmentation and the field should have been a PTranslatedStringD, there is no way to alter the configuration of the existing attribute, and it must be dropped and recreated if the system name needs to be reused.

To avoid headache down the road, careful analysis before creating attributes in the production system is a necessity.

Product data

Having configured an auto-publishing segment, and at least one attribute, we can now move on to the core functionality of managing product data. To create the first product, navigate to the 'Products' tab in the top bar, then click the '+ product' button on the right side.

Editable unique name

Be aware that while the unique name is considered a key with regards to product data, it is currently still possible to edit the unique name of an existing product through the UI.

Doing so may have interesting consequences if e.g. the renamed product is part of an import operation, in which case it will be re-created with whatever data is in the import set.

Every product in PIM is uniquely identified by the 'unique name' of the product. This name serves as the identifier of the product when subsequently interacting with the product whether through import/export operations or when working with the product through the public API.

Enter a name for the product in the pop-up and chose 'save'.

In the dialog, click the unique name for the product to go directly to the product editor for the new product.

In the product editor, use the 'Add Attribute' drop down in the right side of the UI to select your newly created attribute which you can now assign a value. Once done editing the product, click the 'Save and publish' button to finalize the changes and save the product.

Published views

Intended use

Note: The published views are intended to be cached by the customer solution. They should not be retrieved from PIM on every customer solution request.

Once product data is created in the PIM, a background job will start generating and keeping up to date published views for the products. These can be retrieved through the public API using plain HTTP or using the PIM SDK, and will from the back-bone of the customer solution. (See full API reference)

To fetch the published view for the product just created

  1. Go to pimapi.bzk.hdk/swagger/index.html or where you might have access to the public API swagger.
  2. Authorize.

  3. Go to POST /api/resolved-views/products/_search with request body

    1
2
3
4
5
6
    {
    "uniqueNames": [
      "your product unique name"
    ],
    "segmentationId": 1
}

You should now receive a response model containing resolved values for the selected segment (in this case segment 1) for all attributes. If you get an empty response chances are the JobRunner has not yet finished updating the published views after you created the product. Wait a few minutes and retry.