Create and Edit Topic Maps

Topics allow you to categorize catalogue items in a hierarchical fashion (ex. materials, country of origin, genres). You can then leverage this multi-dimensional categorization within your frontend(s). For instance, you could allow users to view all your wines from Italy, or all vegetarian recipes. You could separate different types of blog posts for enhanced browsing (article, recipe, release announcement).

A tenant's topic maps can be managed via the PIM API or the Crystallize App. To do so, you'll first need the requisite permissions for Topics (read, create, etc). Refer to our documentation on roles and permissions for more information.

Within the Crystallize App, you can click the Topic Maps button on the left-hand side of the screen. You can also bring up the command palette with [CTRL or ⌘] + K and type or select “Topics.” From here, you can either click the plus sign button (+) or the + Create topic map button. Type in a name for the topic map, then hit Enter or click Create.

The root node of the topic map has several buttons:

• Clicking the button at the top of the card collapses and expands the entire topic map.
• The Developer view button switches to the internal GraphQL explorer, showing you the GraphQL query that can be used to retrieve topics and paths. You can return to the topic map by accessing the View drop-down menu at the top of the screen and choosing Pretty.
• The Items button tells you what items (products, folders, and documents) in your tenant are using the topic map.
• The plus sign button (+) creates new topics at the next level down in the map. Once created, you can type in names for these topics. Clicking the plus sign button (+) on lower-level topics provides most of the same options described above, and also allows you to delete the topic.

As the topic map gets bigger, you can click and drag to move it around, or scroll with your mouse to zoom in and out on it. Use the Reset zoom button in the bottom-right corner to recenter the view on the base-level topic.

Changes made to the topic map are automatically saved, but won’t be made publicly available until you click the Publish Changes button at the top of the screen.

If you wish to delete the topic map, click the action button (...) at the top of the screen and choose Delete.

If you’ve defined multiple languages in your tenant, there will be a translation of your topic map for each of these languages. You can switch between different translations using the Language drop-down at the top of the screen. Refer to our Configuring Languages page for more information.

You can add any number of topics to products, documents, and folders within the catalogue. There are a couple of ways to do this. First, when editing an item, scroll down to the Topics section, click the plus sign button (+), then start typing the name of the topic you want to assign.The search tool will return all existing topics that match your input. Left-click on the one you want to select, or use the arrow keys to scroll down and press Enter on the desired topic. To remove a topic, click the X on the right-hand side of its corresponding label.

Another way to assign topics is by browsing to a folder full of items, hovering over its name, and clicking on the glasses button to open the folder in Nerdy View. Click on either the All or Products tab, then select one or more items by clicking on their row numbers. You can Shift+click or click and drag to select multiple items in a row, or CTRL+click/⌘+click to select more than one that aren’t adjacent. Once the items have been selected, click the plus sign button (+) next to the Add topics label that appears. Type the name(s) or click on the topic(s) you want to assign, then click the Add topics button. To preserve your changes without making them publicly available yet, click the Save Changes button in the top right of the screen. To save changes and immediately make them public, click the Save and Publish button.

You can (optionally) set up webhooks to subscribe to topic map-related events. In Crystallize, events are fired whenever topic maps are

• Created
• Updated
• Deleted

You can set up a webhook, then come up with your own way of responding to events. For more information, read about defining webhooks here.

Once created, topic maps are accessible via the Catalogue API. Refer to our sample queries for fetching topics and fetching topics by path, available at our example repository. You can also refer to the API docs at https://api.crystallize.com/your-tenant-identifier/catalogue for more information.