Extensions

#Getting Started

The UI extension feature enables you to extend your PIM by integrating custom views and actions from external systems. This framework provides the flexibility to modify and adapt your PIM experience to meet specific business requirements. By leveraging this functionality, you can integrate custom solutions while maintaining the reliability and ease the use of our SaaS platform, offering a balance between flexibility and stability.

The extension framework is designed to help you customize the standard behavior of your PIM system by integrating with externally hosted solutions. This documentation provides an overview of the framework's capabilities and the various customization options available, enabling you to extend and tailor your PIM to meet your specific business needs.

This guide provides a step-by-step walkthrough for setting up and managing UI extensions.

#Prerequisites

Before proceeding, ensure that you have an active App (it can be a Custom App or an active connection) to an Akeneo PIM.

To learn how to create a Connection, see the Authentication Guide. If you're setting up a Custom App, follow the steps in this tutorial to obtain an App token.

#Authentication and authorization

#Authentication

Having a valid Akeneo PIM API token provided by either a Connection or an App to be authenticated to use the UI extension API endpoints.

#Authorization

To manage your extension, ensure that your Connection or App has the necessary permissions.

For Connections: The user associated with the Connection must have the permission UI extensions > Manage your extensions using the API enabled.
For Apps: You need to request the scope manage_extensions.

A UI extension is owned by a user, meaning that a Connection can only manage UI extensions created by itself or by Connections associated with the same user. Similarly, an App can only manage its own UI extensions.

Granting these permissions before setup helps prevent unnecessary errors.

#Using Postman

The quickest way to get started with UI extensions is by using our Postman collection.

#1. Import the Postman Collection

Download our Postman collection
Download our Postman environment variable template
Import those files into Postman (follow this guide if you're not familiar with how Postman collections work)

#2. Fill the environment variables

The collection includes a pre-script for handling PIM Connection authentication.

Before making API requests, ensure your environment variables are filled with your Akeneo PIM Connection credentials: a valid pim_access_token will be generated automatically on your first request. If you don't receive a token, or you don't see it within the environment variable list, double-check your credentials.

#3. Create a UI extension

Select the Postman environment you've just created
Click on the Add an extension POST request
Customize the data to send as you want before click on Send
Copy the newly created extension UUID. It will be asked to modify or delete the UI extension.

#4. Update a UI extension

Make sure that the right environment is selected
Click on the Update an extension POST request
Fill the ui_extension_uuid parameter with the UUID of the concerned UI extension
Customize the data according to your needs before clicking on Send

#5. Delete a UI extension

Make sure that the right environment is selected
Click on the Delete an extension POST request
Fill the ui_extension_uuid parameter with the UUID of the concerned UI extension
Click on Send

#Using Curl

#1. Retrieve your credentials from your targeted PIM

🛠 For every call to the API, you need X-PIM-TOKEN & X-PIM-CLIENT-ID.

In this example, we will create a new connection in the PIM and use it to generate an API token.

1. Create a Connection in Akeneo PIM:

Navigate to Connect > Connection settings > Create.
Fill out the form to create the Connection.
Note the generated client ID, secret, username, and password.

2. Set your environment variables:

Define the client ID, secret, username, password, and Akeneo host URL as environment variables:

Shell

     export CLIENT_ID="your-client-id"
     export CLIENT_SECRET="your-client-secret"
     export API_USERNAME="your-API-username"
     export API_PASSWORD="your-API-password"
     export TARGET_PIM_URL="https://your-pim.cloud.akeneo.com"

Replace the placeholders with your actual credentials and host URL.

3. Encode your credentials:

Encode the client ID and secret in base64 format, separated by a colon ::

Shell

     export BASE64_ENCODED_CLIENTID_AND_SECRET=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64 -w 0)
    // For Mac OS user remove the -w 0 option

4. Your API token:

Make the API call to retrieve your API token using the environment variables:

Shell

     curl --request POST "$TARGET_PIM_URL/api/oauth/v1/token" \
     --header "Content-Type: application/json" \
     --header "Authorization: Basic $BASE64_ENCODED_CLIENTID_AND_SECRET" \
     --data-raw '{
     "grant_type": "password",
     "username": "'"$API_USERNAME"'",
     "password": "'"$API_PASSWORD"'"
     }'

After retrieving the API token, store the access_token from the response in an environment variable:

Shell

     export PIM_API_TOKEN="..."
     // Replace with the actual token from the response

Note that the token has a lifespan of one hour.

🛠 Custom Apps are also supported. To use one, add a variable app_access_token with your API token.

#2. Create a UI extension

You can create a UI extension once you have a valid PIM API token.

Shell

    curl --request POST "$TARGET_PIM_URL/api/rest/v1/ui-extensions" \
    --header "Authorization: Bearer $PIM_API_TOKEN" \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "name": "my_awesome_extension",
        "version": "V1.02",
        "type": "link",
        "position": "pim.product.header",
        "configuration": {
            "url": "https://myapp.com/product",
            "default_label": "My awesome extension",
            "labels": {
              "en_US": "My awesome extension"
            }
        }
    }'

#3. Update a UI extension

To update a UI extension, you must have a valid PIM API token and the UUID of the extension you want to update.

Shell

    curl --request PATCH "$TARGET_PIM_URL/api/rest/v1/ui-extensions/$EXTENSION_UUID" \
    --header "Authorization: Bearer $PIM_API_TOKEN" \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "version": "V1.03",
        "type": "iframe",
        "position": "pim.product.tab"
    }'

#4. Delete a UI extension

To delete a UI extension, you must have a valid PIM API token and the UUID of the extension you want to delete.

Shell

    curl --request DELETE "$TARGET_PIM_URL/api/rest/v1/ui-extensions/$EXTENSION_UUID" \
    --header "Authorization: Bearer $PIM_API_TOKEN"

#Administration of UI extensions

For a functional overview of the administration panel and permissions, see our Help Center.

#Prerequisites

To be able to list all registered extensions, you must have a role with UI extensions > View all UI extensions via Administration panel permission.

To be able to enable or disable extensions, you must have a role with UI extensions > Manage all UI extensions via Administration panel permission.

#List all UI extensions

You can open the administration panel with the menu System > System Customization > UI extensions.

On the new page, you can see all extensions registered in your PIM.

#Enable / disable a UI extension

To manage one or more UI extensions from the list, you just have to select them thanks to the checkboxes present on the left of each line, and then use one of the two commands available at the bottom of the screen.

#API reference

Several choices are offered to deep dive into our API, to discover all the endpoints, and their request/response schema:

You can consult this static documentation
Discover it thanks to the postman collection (see the Postman section)

UI extensions available positions