Install and connect magnews to Magento

To use the Magento Connector you need to complete the setup first in the Magento backend and then in the connector settings in magnews. This guide covers the whole path: plugin installation, integration creation, connection configuration and testing. If you already have an active connection with the 1.5.x plugin, go to Upgrading to the 2.x plugin.

Before you start

Get these three things ready, so you don't have to interrupt the procedure halfway through:

• access to Magento Admin with administrator permissions, and the cooperation of whoever manages the Magento instance for the shell commands;
• an Access key on repo.magento.com, and, only if you install through composer, a GitHub account with access to the plugin repository, which is private: it must be requested through the Helpdesk and is not immediate, so request it first. If you install through the zip downloaded from magnews it is not needed;
• a maintenance window, if you are upgrading a connection that is already active: during the switch, synchronisation with Magento is not operational.

Which plugin version?

The connector communicates with Magento through a PHP plugin and automatically detects the version installed on your instance. The version to use is 2.x: it is the one distributed by the app and the only one the steps in this guide refer to.

Compared to the previous generation, 2.x protects the communication with Magento through a dedicated encryption key, authenticates with the token of a Magento integration instead of a username and password, and handles subscriptions and unsubscriptions through dedicated plugin services.

The steps to connect with the Magento Connector are:

1. Plugin installation
2. Creating the integration in Magento Admin
3. Retrieving the encryption key
4. Configuring the connection in magnews

1. Installing the PHP plugin

The PHP plugin is a module to be installed on your Magento instance and it enables the communication between magnews and Magento. Ask whoever manages the Magento instance to follow the instructions on the Magento plugin installation page, reachable from the connector's Global configuration, and in the README file included in the plugin.

Two installation modes are available. In both cases you need an Access key on repo.magento.com and you have to refer to the plugin's README file for the complete commands.

• Through composer (recommended): configure the authentication tokens for repo.magento.com and GitHub, add the plugin repository and install with composer require magnews/magento-query-service. Follow the Install using composer section of the README. You need a GitHub Personal Access Token with the repo scope: if your account does not have access to the plugin repository, write to the Helpdesk to request it before you start.
• Through zip: download the plugin zip, install the composer require greenlion/php-sql-parser dependency and unpack the archive under app/code/MagNews/QueryService. Follow the Install with zip file section of the README. The zip is available in two places:
  • from magnews, on the Magento plugin installation page reachable from the connector's Global configuration, which always distributes the most recent version of the plugin;
  • from the Releases page of the plugin's GitHub repository.

Once the installation is complete, enable the module on your Magento instance:

bin/magento module:enable MagNews_QueryService
bin/magento setup:upgrade
bin/magento cache:clean
bin/magento setup:di:compile

During the installation the plugin automatically generates the encryption key you will need at step 3.

2. Creating the integration in Magento Admin

The recommended way to authenticate magnews on Magento is an access token generated by a Magento Integration: there is no need to create a user or a role, and the permissions stay limited to the plugin's services.

a) Enable Bearer tokens (only Magento 2.4.4 or later):
Stores > Configuration > Services > OAuth > Consumer Settings → Allow OAuth Access Tokens to be used as standalone Bearer tokens = Yes.

b) Create the integration:

1. Go to System > Extensions > Integrations and click Add New Integration.
2. Give it a name (for example "magnews").
3. In the API tab assign the permissions:
   • magnews > Read: query execution and configuration reading;
   • magnews > Newsletter: newsletter subscription and unsubscription;
   • magnews > Configuration: access to the configuration.
4. Save and activate the integration.
5. Copy the Access Token: you will need it in the connection configuration in magnews (step 4).

3. Retrieving the encryption key

The communication with Magento is protected by an encryption key, generated automatically during the module installation, which will have to be pasted into the connection configuration in magnews (Query encryption key field).

To retrieve it in Magento:

1. Go to Stores > Configuration > magnews > Query Service > Encryption Settings.
2. Copy the value of the Encryption Key field.
3. Paste it into the Query encryption key field of the connection configuration in magnews (step 4).

If needed you can generate a new key with the Regenerate Key button.

4. Configuring the connection in magnews

Once the module is configured in Magento, move to the connector's Global configuration section, following the path:
Management > Magento Connector > Global configuration.

Connection to Magento

The parameters in this section configure the connection between the platform and Magento in detail. Enter the following values:

• Web Services URL:
  the address of the REST service, for example: https://www.mystore.com/index.php/rest
• Authentication mode:
  Fixed key (recommended): paste into the relevant field the Access Token of the integration created at step 2.
  Username and Password/API Key: enter the User Name and Password of a Magento administrator user, whose role has the magnews Read, Newsletter and Configuration permissions. The token is requested by magnews at every session.
• Query encryption key:
  paste the key retrieved from Magento at step 3. It is mandatory: without a valid key the connection test fails.
• HTTP connection timeout:
  if the Magento server is too slow to respond, increase the value, otherwise leave the default.
• Disable certificate validity check:
  disables the validity check of the security certificates.
• The web server requires authentication:
  if the web server requires authentication, enable the option and enter a username and a password.
• The web server requires authentication for the images of the Magento frontend:
  if the web server requires authentication to show the frontend images, enable the option and enter a username and a password.

The Status field indicates whether magnews is actually connected to Magento.
The Platform plugin field shows the version of the plugin installed on Magento, detected automatically by the connector, and warns you if a more recent version is available.
The Magento plugin installation link stays available after the installation as well, to download the plugin again or to read the instructions once more.

Connection test

Once the basic parameters are configured, run a test by clicking the Connection test button. The test verifies that magnews and Magento are actually connected. If the outcome is positive, click Save at the top right and confirm or customise the further settings shown on the page.

Technical parameters

The technical parameters let you optimise the performance of some aspects of the synchronisation between the connector and the platform.

• Page size: number of contacts per page processed by the contact synchronisation. The higher the number, the faster the operation, but it requires a Magento server with more resources.
• Timezone: changing the timezone (UTC by default) could cause problems with dates. Change this value only if you are sure you are operating in a region with a different timezone.
• Images cache time-to-live (minutes): for how many minutes the platform keeps in memory the images downloaded from Magento (0 = caching disabled).

After checking that the technical parameters are correct, connect the connector to the Magento platform by clicking the Update definitions button.

Upgrading to the 2.x plugin

If you have a working connection with the 1.5.x plugin and you want to move to 2.x, follow these steps. The connector detects the new version automatically, but authentication and encryption have to be reconfigured.

1. Remove the 1.5.x plugin from app/code/MagNews/QueryService before installing the new module, then install and enable 2.x as described at step 1.
2. Create the integration in Magento and copy the Access Token, as described at step 2.
3. Retrieve the encryption key generated during the installation, as described at step 3.
4. Update the connection configuration in magnews (step 4):
   • set the Authentication mode to Fixed key and paste the Access Token, in place of the User Name and Password used by 1.5.x. You can also stay on Username and Password/API Key, but moving to the integration is recommended: check that the user's role has the magnews Read, Newsletter and Configuration permissions;
   • paste the key into the Query encryption key field, which with 1.5.x was empty;
   • run the Connection test and save.

When you are done, the user and the role dedicated to the 1.5.x plugin are no longer necessary and can be removed from Magento.

Plugin 1.5.x (legacy)

This section only concerns connections that are already active with the 1.5.x plugin, which keeps working but is no longer distributed by the app. For new installations use 2.x. If you are upgrading, see Upgrading to the 2.x plugin.

User and permissions (User Role)

With 1.5.x the authentication happens with a username and password, or API key, and it requires a dedicated profile in Magento. Among the User Roles of Magento Admin create a new profile with both the Read and Write permissions and assign it to the user to be used in the connection.

The Write permission is needed to report back to Magento the contact unsubscriptions started from the magnews newsletters. This way the contacts stay unsubscribed in magnews as well after the daily imports.

Connection parameters in magnews

In the connector's Global configuration (step 4) the parameters specific to 1.5.x are:

• Authentication mode: select Username and Password/API Key and enter the User Name and Password of the user created in Magento.
• Query encryption key: leave the field empty, query encryption is introduced by 2.x.

All the other parameters and the technical parameters are identical to those of step 4.

Next steps

Once the connection is complete, carry on with:

• Store configuration
• Workflow