Manage your connections

Summary

Wondering what Connections are? Let's discover what this concept is together right here.

 

See at a glance all your connections

From Akeneo PIM, you can easily see all the connections to third parties, such as ERPs, DAMs, e-commerce platforms, syndication tools, etc...

To do so, click on Connect, then on Connection settings.
The following screen should be displayed.

As an example, here, we have 3 connections around this PIM:

  • 2 source connections: an ERP and a retail collaboration platform,
  • and one destination connection: an e-commerce platform.

Those 3 third parties send or receive information to/from the PIM.

No connection declared here yet? Discover what a connection is here, and don't hesitate to create a new one! 😉

 

 

Create a connection

You must create a connection to connect your PIM to a third-party solution.

You can connect up to 50 third parties through connections and connected Apps. 🚀

 

Here are the simple steps to create a connection:

  1. Click on Connect.
  2. Then, on Connection settings.
  3. Click on Create.
  4. In the Label field, enter the name of your connector. For example, write Magento or Magento connector if you wish to connect your PIM to Magento.
    Sidenote: the code of the connection is automatically generated based on the label. You can keep it as is or change it. It's up to you!
  5. Choose the flow type of your connection. To choose wisely, see the section below.

You're done! 🎉

Once your connection is created, you can assign it a visual to quickly see which connection it refers to. For example, if your connection represents your connection to Magento, you may want to put a picture of the Magento logo, exactly like in the screenshot below.

After creating the connection, you'll also be given a set of credentials to authenticate your connector. See this section to know more.

 

Choose your flow type

You must define a "flow type" when creating or updating a connection. But what does it mean?

The flow type is a central concept in the connection notion. It allows you to characterize the data flows that will interact with your PIM. More precisely, it allows indicating the direction of a given flow.

It will determine how your connection flows are monitored in the data flows dashboard.

This flow type has three available options you'll have to choose from. The followingOther sections describe each of them. It will help you make your decision.

 

The Source connection flow type

Choose this option for your connection whenever it represents a data flow entering the PIM. For example, your data flow mainly creates or updates PIM data, such as products, product models, assets, and reference entities,...

With this flow type, you can connect your ERP, DAM, MDM, etc.

 

If you choose this option, the Data flows dashboard will focus on the data pushed inside the PIM via this connection.

 

The Destination connection flow type

Choose this option for your connection whenever it represents a data flow that mainly extracts product information from your PIM.

With this flow type, you can connect e-commerce platforms, publishing, and syndication tools...

 

If you choose this option, the Data flows dashboard will focus on the data pushed outside the PIM via this connection.

 

The Other flow type

Choose this option whenever you can opt for none of the options above.

Try avoiding choosing this option. Indeed, you won't have any connection monitoring for your Other connections, as we can't know the direction of your flows in this connection.

 

You may be tempted to declare the connections connecting to translation tools as Other. Indeed, in this case, product information in one language is being retrieved from the PIM to be translated. Then, once the translation is done, the translated product information is pushed back into the PIM. So, it is both a Source and a Destination connection. 
That said, even in this case, we advise you to choose between the two options instead of Other. The question you should ask yourself here is, "Do I wish to have a monitoring of the flows that are going out or the flows that are going in?".

 

 

Enable the monitoring

You can choose whether you want to monitor each connection in Data flows. 
To do so, check Track in the Data flows dashboard and the connection settings screen of the connection you want to track.

Other connections can't be tracked. Indeed, we wouldn't know what to track about them. 
Change your connection flow type to Source to track the data entering your PIM. 
If you want to track the data pulled out of the PIM by your connector, change your connection flow type to Destination.

 

You can disable the monitoring whenever you want. 
We will stop monitoring the connection immediately, and you won't be able to select it in the filters of the Data flows dashboard. However, note that all the data collected up to that point for this connection will still appear in some KPIs.

 

 

Grab your credentials

Whenever you create a connection, the PIM automatically generates a set of credentials for you. These credentials are necessary if you want to make any API calls to the PIM. Don't hesitate to learn more about the authentication over the API on our dedicated API website.

These credentials consist of 4 different strings:

  • the client id,
  • the secret,
  • the connection username,
  • the connection password.

To access the client ID, the secret, and the username, go to Connect > Connection settings and click on the connection you want to see the credentials. They are displayed on the right side of the screen in the Credentials column.

You can easily copy/paste the credentials by clicking the button next to them.

The secret and password fields are only shown once after the connection creation. Make sure you save it somewhere. 
When the password is visible, a copy icon is next to it for easy copy-paste. 😉

 

You forgot your password? Don't worry. You can regenerate a new one. Take a look at the Regenerate your connection password section.

 

Use these credentials to authenticate the API calls in the Connector that match your connection. For this step, take a look at this guide.

 

Why should you use the connection username?

You may have noticed nothing prevents you from using another username than the one generated for you when your connection is created. It's totally possible, but it's, in fact, not recommended at all!

Instead, we highly recommend using the connection username to authenticate all the API calls from the Connector linked to your connection.

Here are the 2 main reasons why:

  • First, all the permissions set on your connection are based on the connection username. So if you don't use it, your permission connection won't be enforced.
  • The connection monitoring in the dashboard is also based on the connection username. So if you want to benefit from this feature, use this username to authenticate your API calls.

 

Revoke/regenerate your connection secret

Sometimes, your connection secret may have leaked and fallen into the wrong hands. So you want to revoke this secret to avoid enabling these "wrong hands" to access your PIM via the API.

The PIM will automatically regenerate a new secret for you along with the secret revocation.

 

Here are the simple steps to go through to revoke your secret:

  1. Click on Connect.
  2. Then, on Connection settings.
  3. Click on the connection for which you want to revoke the secret.
  4. In the Credentials section, click on the regenerate icon on the right side of the Secret line. 
  5. A pop-in asks you for confirmation. Click on Regenerate.

The current secret will be revoked. It means that no one will be able to use it anymore to authenticate their API calls. 
Also, a new secret has been generated. Be sure to use this new one in your connector toimpact be able to make API calls again.

As you may have understood, revoking a secret can impact the Connector linked to your connection. Indeed, when you revoke a secret used by one of your connectors, all its API calls will automatically stop working and send 401 errors instead. You won't be authenticated anymore. 
Launch a new authentication request using the newly generated secret to be authenticated again.

 

Don't really know how authentication via API works? Don't worry. There is documentation to help you! It's right here!

 

 

Regenerate your connection password

The PIM only shows you the connection password once at the connection creation. If you have forgotten it, you can regenerate a new one.

Here's how:

  1. Click on Connect.
  2. Then, on Connection settings.
  3. Click on the connection for which you want to revoke the password.
  4. Click the regenerate icon in the Credentials section on the right side of the Password line. 
  5. A pop-in asks you for confirmation. Click on Regenerate.

The current password will be deleted, and a new one will be generated. It means that no one will be able to use it anymore to authenticate their API calls. 
Be sure to use the new password in your connector toimpact be able to make API calls again.

As you may have understood, regenerating a password can impact the Connector linked to your connection. Indeed, when you regenerate a password used by one of your connectors, all its API calls will automatically stop working and send 401 errors instead. You won't be authenticated anymore. 
Launch a new authentication request using the newly generated password to be authenticated again.

 

Don't really know how authentication via API works? Don't worry. There is documentation to help you! It's right here!

 

 

Set the permissions

For each connection, you can define a set of permissions that can restrict access to:

  • Some API endpoints. In this case, those permissions are defined thanks to your connection user role.
  • Some parts of your product catalog. In this case, those permissions are enforced thanks to the connection user group. Note that they are only available in the Enterprise Edition.

 

Configure the connection user role,

For each connection, you can define a user role. This user role should be first created in the User role screens.

By default, your connection is created with the User user role. You may want to change that as this user role is quite generic and may not assign the desired permissions to your connection.

 

We strongly recommend you create one dedicated user role for your connections, different from those you use for your UI users. It's even better if you create one user role for every connection you need, as it will allow you to fine-tune what each connection can access. 😉

Also, we don't recommend giving UI permissions to your connection user roles.

 

To create a user role and link it to your connection:

  1. Click on System.
  2. Click on Roles
  3. Click on Create role.
  4. In the form that appears, give a name to your user role, My Magento user role, for example.
  5. Click on Web API permissions and select Overall Web API access.
  6. You can also select other accesses in the list below depending on what you want your connection to be able to achieve.
  7. Save your configuration by clicking on Save.
  8. Click on Connect.
  9. Click on Connection settings.
  10. Click on the connection for which you want to set the permissions.
  11. On the right side of the screen, there is a Permissions section. Select the user role you've just created in the Role dropdown. 
  12. Don't forget to save by clicking on Save.

Configure the connection user group

For each connection, you can define a user group. This user group should be first created in the User group screens.

By default, your connection is created with the All user group. You may want to change that, as this user group is quite generic and may not assign the desired permissions to your connection.

 

We strongly recommend you create one dedicated user group for your connections, different from those you use for your UI users. It's even better to create one user group for every connection you need, as it will allow you to fine-tune what each connection can access. 😉

To create a user group and link it to your connection:

  1. Click on System.
  2. Click on User groups
  3. Click on Create user group.
  4. In the form that appears, give a name to your user group, My Magento user group, for example.
  5. Save your configuration by clicking on Save.
  6. Click on Connect.
  7. Click on Connection settings.
  8. Click on the connection for which you want to set the permissions.
  9. On the right side of the screen, there is a Permissions section. Select the user role you've just created in the Group dropdown.
  10. Don't forget to save by clicking on the Save button.

By default, the user group you've just created does not give any rights to the catalog. So it's perfectly normal if you receive no products when you ask for products via the API using the connection credentials. 
To view the catalog, you must give permission to your connection user group. Here is the documentation to help you with this task.

 

 

Delete a connection

If you created a connection you don't want to use anymore, you can delete it.

  1. Click on Connect.
  2. Click on Connection settings.
  3. Click on the connection you want to delete.
  4. Click on in the top right corner of your screen.
  5. Click on Delete.
  6. A pop-in asks you for confirmation. Again, click on Delete.

As a result, your connection will be deleted. It means that:

  • You will no longer be able to follow its data flows inside the Data flows dashboard,
  • The credentials that were generated with the connection will be revoked. The API authentication made with these credentials will be revoked as well. It means that all the API calls using a token generated based on these credentials will now send 401 errors. If this does not ring a bell for you, you might want to learn more about authentication in the API right here. 😉