README

Integrate Zaius directly into your Magento instance using the Zaius Magento 1 Connector.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

Magento 1 "^1.9.x"
PHP 5 >= 5.5.0, PHP 7
(OPTIONAL) Composer

Installing

Composer

By far the quickest and easiest way to install and maintain the Zaius Magento 1 Connector is to use Composer. Unfortunately, Magento 1 was built before Composer, and therefore does not support it out-of-the-box. However, it is easy to get composer and Magneto 1 working together. To install Composer, one will need access to the server command line.

cd ~
curl -sS https://getcomposer.org/installer -o composer-setup.php
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

To test the installation, run:

composer

Composer is now globally installed on your server.

To install the Zaius Magento 1 Connector with composer, you can place the file composer.json.example into your Magento 1 root directory (without the .example extension).

If you already have a composer.json file, add the required libraries from composer.json.example into it.

Once these requirements are noted, installing the Zaius Magento 1 Connector is as easy as running a simple command from the root of your Magento instance:

composer install

This will download the necessary files for Composer to work with Magento 1, as well as the Zaius Magento 1 Connector and the Zaius PHP SDK.

ZIP

Download the Zaius Magento 1 module archive from Git: https://github.com/ZaiusInc/zaius-magento-1/archive/master.zip
Extract the contents of the ZIP file to <MAGENTO_ROOT>/<extract_here>.

In a correct directory structure, you will find the Zaius Magento 1 Connector files in <MAGENTO_ROOT>/app/code/community/Zaius

Setting Up The Connector

Part 1: Setting Up A SOAP Role & User

imTLBMb8R8CmhcwZTeig_Screen%2520Shot%25202016-04-07%2520at%25208.53.34%2520AM.png

In order to use Magento with Zaius, a user with SOAP API permissions must be created.

From the System drop down menu, navigate to the Web Services -> SOAP/XML-RPC Roles child sub-menu.
Click Add New Role in the upper right. a. Enter a name for the Role, such as zaius_engage. b. Click Role Resources in the left-hand menu. c. Tick the box next to Zaius Engage. this will enable all Zaius Engage API methods for this SOAP user. d. Navigate back to Role Info in the left-hand menu, and enter the Current Admin Password in the box provided. e. Click Save Role in the upper right.
From the System drop down menu, navigate to the Web Services -> SOAP/XML-RPC Users child sub-menu.
Click Add New User in the upper right. a. Fill in the appropriate required fields. User Name: create a simple user name; e.g. zaius_engage. API KEY: create a 'password' for the user name to authenticate with; e.g. password123. b. Click User Role in the left-hand menu. c. Select the appropriate role for the new SOAP user. In our example it is zaius_engage. d. Click Save User in the upper right.

The username and API key specified will be provided to Zaius in order to enable the integration.

Part 2: Integrating with Zaius

Enter the username, API key and the URL endpoint on your server into the boxes found in the integrations screen in the Magento box. The API URL is typically of the form: "http://your-magento-server/api/v2_soap?wsdl=1"

9J9L6X4YR6WrU3Wkd4wo_Screen%2520Shot%25202016-04-12%2520at%252011.55.19%2520AM.png

Part 3: Configuring Zaius Engage

Zaius Engage

Tracking Identifier: The Zaius Tracking Identifier to send data to.
Cart Abandonment Secret Key : This is a secret value used to encode link information for cart abandonment campaigns. Once set, this should not be changed. This is a random string that you enter in and is not something Zaius provides.
Global ID Prefix
Zaius Newsletter List ID
Use Magento Customer ID
Track Product Listing Views
Track Orders On Frontend
Collect All Product Attributes
Reported Currency

Zaius Schema Update

Update Schema: Update the Magento Database Schema of three tables (catalog_product_entity_media_gallery, newsletter_subscriber, salesrule_coupon) to allow the processing of records that may not get picked up by Magento observers.

Zaius Localizations

Localizations: Enabling localizations will provide localized store_view data for events sent to Zaius.

Many Magento sites support multiple language/currency code combinations, and create each one as a separate store_view. Zaius has added support for this workflow.

The Zaius Localizations feature in the Zaius Engage module adds support for such sites. The feature automatically detects those store_views configured as localizations and sends additional, localized versions of products. These products provide all information necessary to generate dynamic product grids in your customers' preferred languages, even when the products shown are not necessarily products they have explicitly interacted with.

At this point in time this feature is in a beta phase, which means that the Zaius support team must make certain updates on the Zaius platform to fully utilize this feature. Please consult with your CSM to get those changes made prior to initializing this feature.

Navigate to the Zaius Engage configuration page.
In the Zaius Localizations panel, switch the Enable/Disable dropdown to "Enable".

Zaius Batch Updating

Recurring Batch Updating: With Batch Updating enabled, missed events are sent to Zaius on a scheduled cron interval.

Many Magento sites have a variety of backend processes which run direct SQL inserts and updates, especially ERPs. When the Magento database is modified via direct SQL, Magento's Observers don't know that there are updates to inform other technologies (like Zaius) about. This can cause those technologies to desynchronize from the Magento dataset.

To account for this, Zaius has built a Batch Update module which lives in Magento. This feature causes Magento to regularly look through the database to find those products, customers, and orders which have been updated since the last time it scanned through.

Navigate to the Zaius Engage configuration page.
In the Zaius Schema Update panel, click "Run It!" to make necessary modifications so that the batch process can know which entries need to be synced. This adds two columns to the database tables which Zaius syncs, zaius_created_at and zaius_updated_at.
In the Zaius Batch Updating panel, change the Crontab line to indicate how frequently you would like the updates to be run. More frequent updates mean that each update takes less time to process, but each time we're scheduled to update a small query will be run against the database to determine if there is anything which needs to be synced. Zaius recommends either a high frequency update (eg "*/5 * * * *" meaning every 5 minutes) or a daily batch at a low-traffic time (eg "0 1 * * *" meaning at 1 AM as indicated by your Magento server's clock).
Make sure to set the "Enable/Disable" option to "Enable".

Zaius Double Opt-in

Zaius Engage has a new option to support double opt-in workflows. To enable this, make sure to set the "Submit Event For Status Not Active" option in the Zaius Engage Configuration.
With the "Submit Event For Status Not Active" option enabled, new users with subscription status 2 ("Not Active") will trigger a "newsletter" event with action "email_submitted"
Users can configure an Event Triggered campaign to allow the user to opt-in, and use engagement with that campaign as a filter for their regularly-occurring sends. Your Zaius CSM can help set this up.

Part 4: Run the Bulk Import in Zaius

Zaius supports the bulk import of customers and product data via CSV files.

CSV's can be uploaded directly from the app. To upload a CSV, navigate to Cog (Administration) -> (Data Management) -> Integrations -> Upload CSV.

File Naming File Format Fields and Data Types Orders

Part 5: Using the Event Inspector

Once events are being sent to Zaius' APIs, you can confirm Zaius is receiving your data and see what data Zaius is receiving. This is done via the Event Inspector in the Zaius UI.

To access the Event Inspector, navigate to Cog (Administration) -> Event Inspector.

Click "Start Inspector". Your API calls will now be recorded and made visible in the UI by clicking "Refresh".

Client Testing Routine

In order to test the connector, clients are encouraged to try the following after the steps above are finished and the connector is set up.

Frontend testing:

Create (or login to) a customer account in your Magento store.
In your account settings, update your address.
In your account settings, subscribe (or unsubscribe) to a newsletter.
While still logged in, navigate to a product in your store, and add it to the cart.
Add as many products as you'd like to the cart.
Add a product to your wishlist.
Navigate to your cart. If you have multiple items in your cart, remove one item.
Make a test purchase of the item(s) in your cart.

Backend testing:

Create a new product.
Update an existing product.
Create an order.
Refund an order.
Cancel an order.

Every listed event above will trigger an update to Zaius

Zaius Engage Events

Global Events

Frontend Events

Adminhtml Events

API Methods & Options

All API methods accept limit & offset options:

Limit: Allows you to limit the number of results in the returned payload.

Offset: Allows you to offset the results in the returned payload. If we wanted to only return records over 16, set "offset" => 15.

$jsonOpts   = array(
    "sessionId" => $sessionId,
    "jsonOpts"  => json_encode(array(
        "limit"                     => 5,
        "offset"                   => 0
    ))
);

locales

Request:

Method:

zaiusEngageLocales();

Request:

No Special Parameters

Response:

array(1) {
  ["locales"]=>
  array(2) {
    ["french"]=>
    array(5) {
      ["label"]=>
      string(15) "French (France)"
      ["code"]=>
      string(5) "fr_FR"
      ["currency_symbol"]=>
      string(3) "€"
      ["currency_code"]=>
      string(3) "EUR"
      ["base_url"]=>
      string(18) "http://zaius.mage/"
    }
    ["german"]=>
    array(5) {
      ["label"]=>
      string(16) "German (Germany)"
      ["code"]=>
      string(5) "de_DE"
      ["currency_symbol"]=>
      string(3) "€"
      ["currency_code"]=>
      string(3) "EUR"
      ["base_url"]=>
      string(18) "http://zaius.mage/"
    }
  }
}

customers

Request:

Method:

zaiusEngageCustomers();

Request:

$jsonOpts   = array(
    "sessionId" => $sessionId,
    "jsonOpts"  => json_encode(array(
        "updated_at"                => "2018-01-01",
        "created_at"                => "2018-01-01",
        "id"                        => 1,
        "email"                     => "email@example.com",
        "limit"                     => 5,
        "offset"                    => 0
    ))
);

Response:

array(1) {
  [0]=>
  array(2) {
    ["type"]=>
    string(8) "customer"
    ["data"]=>
    array(13) {
      ["email"]=>
      string(16) "jack@example.com"
      ["first_name"]=>
      string(4) "Jack"
      ["last_name"]=>
      string(4) "Fitz"
      ["subscribed"]=>
      bool(false)
      ["customer_id"]=>
      string(2) "24"
      ["street1"]=>
      string(13) "7 N Willow St"
      ["street2"]=>
      string(0) ""
      ["city"]=>
      string(9) "Montclair"
      ["state"]=>
      string(10) "New Jersey"
      ["zip"]=>
      string(5) "07042"
      ["country"]=>
      string(2) "US"
      ["phone"]=>
      string(12) "222-555-4190"
      ["zaius_engage_version"]=>
      array(1) {
        [0]=>
        string(6) "0.13.1"
      }
    }
  }

products

Request:

Method:

zaiusEngageProducts();

Request:

$jsonOpts   = array(
    "sessionId" => $sessionId,
    "jsonOpts"  => json_encode(array(
        "updated_at"                => "2018-01-01",
        "created_at"                => "2018-01-01",
        "type_id"                   => "simple",
        "store_view_code"           => "french",
        "synthetic_upsert_default"  => true,
        "append_store_view_code"    => true,
        "product_id"                => 240,
        "sku"                       => "mtk000",
        "limit"                     => 5,
        "offset"                    => 0
    ))
);

append_store_view_code must be included and set to true if synthetic_upsert_default is included and set to true.

Response:

array(1) {
  [0]=>
  array(2) {
    ["type"]=>
    string(7) "product"
    ["data"]=>
    array(12) {
      ["product_id"]=>
      string(3) "231"
      ["product_url"]=>
      string(56) "http://zaius.mage/index.php/catalog/product/view/id/231/"
      ["name"]=>
      string(31) "French Cuff Cotton Twill Oxford"
      ["sku"]=>
      string(6) "msj000"
      ["description"]=>
      string(126) "Made with wrinkle resistant cotton twill, this French-cuffed luxury dress shirt is perfect for Business Class frequent flyers."
      ["image_url"]=>
      string(52) "http://zaius.mage/media/catalog/product/no_selection"
      ["category"]=>
      string(31) "Default Category > Men > Shirts"
      ["price"]=>
      string(8) "190.0000"
      ["qty"]=>
      string(7) "15.0000"
      ["is_in_stock"]=>
      string(1) "1"
      ["parent_product_id"]=>
      string(3) "402"
      ["zaius_engage_version"]=>
      array(1) {
        [0]=>
        string(6) "0.13.1"
      }
    }
  }

orders

Request:

Method:

zaiusEngageOrders();

Request:

$jsonOpts   = array(
	"sessionId" => $sessionId,
	"jsonOpts"  => json_encode(array(
		"updated_at"    => "2018-01-01",
		"created_at"    => "2018-01-01",
		"refund"        => true,
		"cancel"        => true,
		"id"            => 123,
		"entity_id"     => 123,
		"customer_id"   => 123,
		"email"         => "example@email.com"					
	))
);

Response:

array(1) {
  [0]=>
  array(2) {
    ["type"]=>
    string(5) "order"
    ["data"]=>
    array(11) {
      ["action"]=>
      string(8) "purchase"
      ["ts"]=>
      int(1363287694)
      ["ip"]=>
      string(15) "216.113.168.131"
      ["ua"]=>
      string(0) ""
      ["order"]=>
      array(21) {
        ["order_id"]=>
        string(9) "100000049"
        ["total"]=>
        string(8) "823.4500"
        ["subtotal"]=>
        string(8) "750.0000"
        ["coupon_code"]=>
        NULL
        ["discount"]=>
        int(0)
        ["tax"]=>
        string(7) "61.8800"
        ["shipping"]=>
        string(7) "11.5700"
        ["currency"]=>
        string(3) "USD"
        ["native_total"]=>
        string(8) "823.4500"
        ["native_subtotal"]=>
        string(8) "750.0000"
        ["native_discount"]=>
        int(0)
        ["native_tax"]=>
        string(7) "61.8800"
        ["native_shipping"]=>
        string(7) "11.5700"
        ["native_currency"]=>
        NULL
        ["bill_address"]=>
        string(68) "10441 Jefferson Blvd., Suite 200, Culver City, California, 90232, US"
        ["email"]=>
        string(15) "mosses@ebay.com"
        ["phone"]=>
        string(10) "3105551212"
        ["first_name"]=>
        string(6) "Mosses"
        ["last_name"]=>
        string(7) "Akizian"
        ["ship_address"]=>
        string(68) "10441 Jefferson Blvd., Suite 200, Culver City, California, 90232, US"
        ["items"]=>
        array(1) {
          [0]=>
          array(9) {
            ["product_id"]=>
            string(3) "377"
            ["subtotal"]=>
            string(8) "750.0000"
            ["sku"]=>
            string(6) "abl007"
            ["quantity"]=>
            string(6) "1.0000"
            ["price"]=>
            string(8) "750.0000"
            ["discount"]=>
            int(0)
            ["native_subtotal"]=>
            string(8) "750.0000"
            ["native_price"]=>
            string(8) "750.0000"
            ["native_discount"]=>
            int(0)
          }
        }
      }
      ["magento_website"]=>
      string(12) "Main Website"
      ["magento_store"]=>
      string(14) "Madison Island"
      ["magento_store_view"]=>
      string(7) "English"
      ["store_view_code"]=>
      string(7) "default"
      ["email"]=>
      string(15) "mosses@ebay.com"
      ["zaius_engage_version"]=>
      array(1) {
        [0]=>
        string(6) "0.13.1"
      }
    }
  }

createCoupons

Request:

Method:

zaiusEngageCreateCoupons();

Request:

$jsonOpts   = array(
	"sessionId" => $sessionId,
	"jsonOpts"  => json_encode(array(
		"rule_id"       => 1,
		"format"        => "alphanum",
		"qty"           => 12,
		"length"        => 12,
		"delimiter"     => "",
		"dash"          => "",
		"prefix"        => "prefix",
		"suffix"        => "suffix"					
	))
);

Response:

array(2) {
  ["type"]=>
  string(6) "coupon"
  ["data"]=>
  array(2) {
    ["zaius_engage_version"]=>
    string(6) "0.13.1"
    ["codes"]=>
    array(1) {
      [0]=>
      string(12) "DSTXKP2I567N"
    }
  }
}

subscribers

Request:

Method:

zaiusEngageSubscribers();

Request:

$jsonOpts   = array(
    "sessionId" => $sessionId,
    "jsonOpts"  => json_encode(array(
        "updated_at"  => "2018-01-01",
        "created_at"  => "2018-01-01"
    ))
);

Response:

array(1) {
  [0]=>
  array(2) {
    ["type"]=>
    string(10) "subscriber"
    ["data"]=>
    array(5) {
      ["email"]=>
      string(18) "mickey@example.com"
      ["list_id"]=>
      string(18) "default_newsletter"
      ["subscribed"]=>
      bool(true)
      ["ts"]=>
      string(19) "2018-05-21 09:48:23"
      ["zaius_engage_version"]=>
      array(1) {
        [0]=>
        string(6) "0.13.1"
      }
    }
  }

configuration

Request:

Method:

zaiusEngageConfiguration();

Request:

$jsonOpts   = array(
  "jsonOpts"  => json_encode(array(
    "zaius_tracking_id" => "RanDOmZaIus-tRAcKinGiD"
  ))
);

Response:

array(3) {
  ["default"]=>
  array(7) {
    ["wsi_enabled"]=>
    bool(true)
    ["magento_fpc_enabled"]=>
    bool(false)
    ["magento_edition"]=>
    string(9) "Community"
    ["magento_version"]=>
    string(7) "1.9.3.9"
    ["zaius_engage_version"]=>
    string(6) "0.13.1"
    ["zaius_engage_enabled"]=>
    bool(true)
    ["config"]=>
    array(3) {
      ["zaius_config"]=>
      array(8) {
        ["zaius_newsletter_list_id"]=>
        string(10) "newsletter"
        ["track_orders_on_frontend"]=>
        string(1) "1"
        ["track_product_listings"]=>
        string(1) "0"
        ["use_magento_customer_id"]=>
        string(1) "1"
        ["tracking_id"]=>
        string(22) "piUzfdlpdHM-rtbS6OpeCQ"
        ["global_id_prefix"]=>
        string(0) ""
        ["collect_all_product_attributes"]=>
        string(1) "0"
        ["reported_currency"]=>
        string(1) "0"
      }
      ["zaius_cron"]=>
      array(2) {
        ["active"]=>
        string(1) "0"
        ["cron_settings"]=>
        string(11) "*/5 * * * *"
      }
      ["zaius_localizations"]=>
      array(1) {
        ["locale_toggle"]=>
        string(1) "0"
      }
    }
  }
  ["french"]=>
  array(7) {
    ["magento_fpc_enabled"]=>
    bool(false)
    ["magento_edition"]=>
    string(9) "Community"
    ["wsi_enabled"]=>
    bool(true)
    ["magento_version"]=>
    string(7) "1.9.3.9"
    ["zaius_engage_version"]=>
    string(6) "0.13.1"
    ["zaius_engage_enabled"]=>
    bool(true)
    ["config"]=>
    array(3) {
      ["zaius_config"]=>
      array(8) {
        ["zaius_newsletter_list_id"]=>
        string(10) "newsletter"
        ["track_orders_on_frontend"]=>
        string(1) "1"
        ["track_product_listings"]=>
        string(1) "0"
        ["use_magento_customer_id"]=>
        string(1) "1"
        ["tracking_id"]=>
        string(22) "piUzfdlpdHM-rtbS6OpeCQ"
        ["global_id_prefix"]=>
        string(0) ""
        ["collect_all_product_attributes"]=>
        string(1) "0"
        ["reported_currency"]=>
        string(1) "0"
      }
      ["zaius_cron"]=>
      array(2) {
        ["active"]=>
        string(1) "0"
        ["cron_settings"]=>
        string(11) "*/5 * * * *"
      }
      ["zaius_localizations"]=>
      array(1) {
        ["locale_toggle"]=>
        string(1) "0"
      }
    }
  }
  ["german"]=>
  array(7) {
    ["magento_fpc_enabled"]=>
    bool(false)
    ["magento_edition"]=>
    string(9) "Community"
    ["wsi_enabled"]=>
    bool(true)
    ["magento_version"]=>
    string(7) "1.9.3.9"
    ["zaius_engage_version"]=>
    string(6) "0.13.1"
    ["zaius_engage_enabled"]=>
    bool(true)
    ["config"]=>
    array(3) {
      ["zaius_config"]=>
      array(8) {
        ["zaius_newsletter_list_id"]=>
        string(10) "newsletter"
        ["track_orders_on_frontend"]=>
        string(1) "1"
        ["track_product_listings"]=>
        string(1) "0"
        ["use_magento_customer_id"]=>
        string(1) "1"
        ["tracking_id"]=>
        string(22) "piUzfdlpdHM-rtbS6OpeCQ"
        ["global_id_prefix"]=>
        string(0) ""
        ["collect_all_product_attributes"]=>
        string(1) "0"
        ["reported_currency"]=>
        string(1) "0"
      }
      ["zaius_cron"]=>
      array(2) {
        ["active"]=>
        string(1) "0"
        ["cron_settings"]=>
        string(11) "*/5 * * * *"
      }
      ["zaius_localizations"]=>
      array(1) {
        ["locale_toggle"]=>
        string(1) "0"
      }
    }
  }
}

zaius / zaius-magento-1

Maintainers

Details

README

Getting Started

Prerequisites

Installing

Composer

ZIP

Setting Up The Connector

Part 1: Setting Up A SOAP Role & User

Part 2: Integrating with Zaius

Part 3: Configuring Zaius Engage

Part 4: Run the Bulk Import in Zaius

Part 5: Using the Event Inspector

Client Testing Routine

Frontend testing:

Backend testing:

Zaius Engage Events

Global Events

Frontend Events

Adminhtml Events

API Methods & Options

locales

Method:

Request:

customers

Method:

Request:

products

Method:

Request:

orders

Method:

Request:

createCoupons

Method:

Request:

subscribers

Method:

Request:

configuration

Method:

Request:

Changelog