Magento 2 Setup for Unific and HubSpot

Before we get started, let's make sure you are on the correct guide.
If your store is on Magento 2 or above, then you are on the correct page. Read on!

Table of contents for setting up Magento 2

  1. Install the Magento 2 Extension 
  2. Set API 'Resource Access' to 'Custom Resources'
  3. Whitelist Unific IP Addresses
  4. Authenticate Magento 2 with Unific OAUTH 
  5. Confirm that the integration works
  6. What to do if you have multiple environments.
  7. Troubleshooting


Let's get started!
_________________________________________________________________________________________

1. Install the Magento 2 Extension

There are two options to install the extension. You only need to follow ONE of options:

Option A: Install using Composer

Option B: Install manually with source code (Only for very advanced users)

Option A: Install using Composer

Do this option only if you are a developer, or send it to your developers:

  1. SSH to your sever: ssh <user>@<ip-addresss-of-server>
  2. Go to the public_html directory of the store
  3. Open composer.json and add below section under repositories:
  4. Visit https://magento2connector.unific.com
  5. as the above link says, copy paste the JSON snippet in composer.json

    "repositories": [{
        "type": "composer",
        "url": "https://magento2connector.unific.com"
      }],
  6. Save composer.json file 
  7. Next, we need to update composer so that the new changes are picked up by Magento.
    Run this command:

    composer update
  8. Then we need to tell composer which version to require. The command below will require any version greater than 1.4 of the Unific Connector:

    composer require "unific/connector:^1.4.0"
  9. Now we need to run these two commands to upgrade Magento database schema, and also to clear the cache

    bin/magento setup:upgrade
    bin/magento cache:clean
  10. Finally, we need to install cron support for Magento 2. This is required because Unific Connector sends Webhooks in an asynchronous fashion to control the load on Magento 2 installation. The following command will install cron for the www-data user.

    sudo -u www-data bin/magento cron:install

Option B: Install manually using the source code

Sometimes store administrators are not allowed to install extensions from Composer OR the Magento Marketplace. In that case we also offer the option to install from the source code. This is not recommended for the novice user! 

  1. Navigate to: https://magento2connector.unific.com/
  2. On that page, in the "Release" section click the link with the largest release number.
  3. That will trigger a download. Save that to a location on your computer that you can find. the file name will start with "unific-connector" and end with ".tar"
  4. Upload this file to the server where Magento 2 store is hosted
  5. Then navigate to the root folder of your Magento 2 store installation 
  6. Change the  "/path/to/connector.tar" portion of the command below to where the tar file was uploaded on that server. Then run the command:

    mkdir -p app/code/Unific/Connector && tar -xvf /path/to/connector.tar /app/code/Unific/Connector

If you are having trouble with installation, please contact us at support@unific.com.

_______________________________________________________________________________________________

2. Set API 'Resource Access' to 'Custom Resources' and select resources mentioned below

Log in to the Magento Admin
  a. Click on "System" in the main menu
  b. Click "Integrations" on the "System" menu
  c. Click the pencil icon next to the "Unific-Integration" row
  d. Click API
  e. Set API 'Resource Access' to 'Custom' and select the 6 Custom Resources as shown in below image (Note: The Unific Reports and Unific Historical resources are available for Unific Connector Versions higher than 1.4.15):

_______________________________________________________________________________________________

3. Whitelist Unific IP Addresses

If your store has a firewall that may block Unific from connecting to the extension please contact support@unific.com and we will send you the necessary ip addresses.

_______________________________________________________________________________________________

4. Authenticate Magento 2 with Unific OAUTH 

All done with the installation? Great! If not, please contact support@unific.com.

The next step is to sign up for a Unific account. 

  1. Go to https://app.unific.com/ 
  2. Enter the credentials you want
  3. Fill in the Company Information step 
  4. Next, select Magento 2 as your shopping cart 

5. A pop up will appear. If it doesn't appear you might have a popup blocker. Please disable it for app.unific.com.

6. You should already have the Unific extension installed if you are following this guide. If you don't, scroll to the top of this page to see the instructions.

7. Click "Continue" if you already have the Unific extension installed.
8. Next you will see this page where you need to enter certain details.

9. We will have to look inside of Magento 2 admin to find the details this page asks for.

(if you are installing Unific on a non-production environment for testing, see the "What to do if you have multiple environments" section below.)

8.  Where to find these details:

Enter the Magento 2 store's URL: This is the production URL of your Magento 2 instance. Use the URL you send to your customers.

The details below are in the Magento 2 admin:

Consumer Key
Consumer Secret
Access Token 

Here's how to find them:
  a. Log in to the Magento Admin
  b. Click on "System" in the main menu
  c. Click "Integrations" on the "System" menu
  d. Click the pencil icon next to the "Unific-Integration" row
  e. Here you'll find the details you are looking for at the bottom inside of Magento 2 

9. Enter the details from Magento and click "Connect"

10. If everything worked well, you should see a "Success" message.

*** If you have multiple environments, you will need to repeat this process for ALL environments ***  

11. Continue with the Unific signup process to connect HubSpot (follow the prompts). 

 

_______________________________________________________________________________________________

5. Confirm that the integration works 

The easiest way to confirm that there is a valid connection between Magento 2 and HubSpot is to open up your online store and register a new account. 

Unific's extension will send a webhook to Unific and Unific will sync it to HubSpot in a few minutes.

If this is not working, then it may be that Unific is not getting webhooks from Magento 2.

Please contact support@unific.com for additional help.

 

_______________________________________________________________________________________________

6. What to do if you have multiple environments

It is often the case that there are multiple environments like Dev, QA, Staging, and Production for Magento 2 stores. 

If you would like to test Unific on environments other than production you may add multiple stores within a single Unific account and connect them to a single HubSpot portal.

If you do have multiple environments, you must install the extension on all environments that you want to test and go through the "Authenticate Magento 2 with Unific OAUTH " process above.

 

_______________________________________________________________________________________________

Troubleshooting:

Connection Errors:

Error while retrieving integration metadata. Error message: ’java.lang.IllegalStateException: HMAC signing parameters are not present. Integration Id: ‘com.unific.models.integrations.Integration$Id@66fe2c83[organizationId=<organization-id>,integrationId=<integration-id>]‘’.

# If you get the above error while connecting your store to Unific,
There are a few issues that lead to this error:

  • Check that the access to resources is set to "Custom Resources".

  • Refer to the section  "Set API 'Resource Access' to 'Custom Resources' and select resources mentioned below" above for details.

  • If you have a firewall on your store email support@unific.com requesting a list of IP addresses to whitelist.
  • Check that the access token entered is correctly entered (check for whitespaces).

  • Once these things are done please reconnect your Magento 2 store within Unific

1. Unific's Logging

Unific's log files are put under the directory:

Refer to these log files if the webhooks are not being sent from the extension to Unific.

connector.log - If there are issues during installation, they should be logged here
unific-audit.log - shows the webhooks that are queued up for sending to Unific


2. Problems and Solutions

Problem B:
Error appears in magento.cron.log

Solution: In your MySQL command line, unlock the tables and empty the cron schedule table, with following commands:

-------
Problem B:
this error appears in setup.cron.log

Solution:

PHP-FPM

  1. Remove unific connector from composer.json
  2. Reinstall the Unific Connector extension

-------


Problem C:

Unific Connector extension is updated, but recent changes are not reflected in the Magento 2 Admin on the extension pages.

Solution: Check the opcache.validate_timestamps setting in the PHP configuration of the server:

If enabled, OPcache will check for updated scripts every opcache.revalidate_freq seconds. When this directive is disabled, you must reset OPcache manually via opcache_reset(), opcache_invalidate() or by restarting the Web server for changes to the filesystem to take effect.

  1. If this is set this to false, opcode cache needs to be manually flushed

  2. If the opcode caching setting for php-fpm is set to never expire it will always load old code which is cached until the cache is either manually flushed or php-fpm is restarted 

-------


Problem D:
If extension changes are still not immediately reflected after the extension is updated.

Solution:
Restart PHP-FPM (if your site uses PHP-FPM)

This command might differ based on your operating system

-------


Problem E:

Error while running composer update:

Solution:
Check if the allow_url_fopen is On or Off using this command on the server (as root user):

If it's 'Off' change allow_url_fopen setting in php.ini file that's being loaded to 'On'.
So it should look like this in php.ini:

-------


Problem F:

Site issues after running composer update:

This request id is actually a log file which will have the actual error in it. That log file will be located in:

If you open that file, it might say:


Solution:
Run this command on the Magento 2 Server

Reload the site and it should work again.


Problem G:

If you are on an older version of the Unific Connector you may get the error below while running 'composer update':

In this case, you will need to update your composer.json contents to match what is shown in the "Install using Composer" section above. 

After making that change, run these commands to remove the older version of the extension and install the newest version.

 


--------------------------------------------------------------------------------------------------------

REST API Calls Unific makes to the Magento 2 Store

Listed are the REST API endpoints from default Magento 2 and the Magento Unific Connector

  1. Connection (Unific Connector):
    Method: POST, API Endpoint: /rest/V1/unific/connect
    To generate a connection between the Magento store and Unific. It exchanges the Unific Integration Id from Unific for the HMAC from the store. Unific also get the categories, products, customers, and orders count.

  2. Historical Entities Count (Unific Connector):
    Method: POST, API Endpoints:
    /rest/V1/unific/category/count
    /rest/V1/unific/product/count
    /rest/V1/unific/customer/count
    /rest/V1/unific/order/count
    To get the total entities count of each entity so that Unific can anticipate the historical process.

  3. Start Historical full/partial (Unific Connector):
    Method: POST, API Endpoints:
    /rest/V1/unific/historical
    /rest/V1/unific/historical/type/category
    /rest/V1/unific/historical/type/product
    /rest/V1/unific/historical/type/customer
    /rest/V1/unific/historical/type/order
    To start the historical process to download all/entity-wise existing data from store to Unific.

  4. Store Configs:
    Method: GET, API Endpoint: /rest/V1/store/storeConfigs
    To generate the Product URLs and Image URLs for Products Bought and Abandoned Cart product information.

  5. Download Products:
    Method: GET, API Endpoint: /rest/V1/products
    To download the missing products (order line items) of order if historical was not done or if the product does not exist with Unific for other reasons.

  6. Generate Sales Rules:
    Method: POST, API Endpoint: /rest/V1/salesRules
    To create the sales rules in the Magento store the configuration of which will be set in the Unific account's Coupon Generator section.

  7. Generate Coupon Codes:
    Method: POST, API Endpoint: /rest/V1/coupons
    To generate the coupon codes under the sales rule for each request for coupon code generation.