Introduction

This page describes steps that are needed to make any Magento extension compatible with MageFlow Extension (MFX).

Call to Collaboration

It's a public repository and an open WIKI. Please feel free to update this document whenever you see outdated or wrong information here.

Abbreviations

MageFlow Extension is called MFX

MageFlow Enterprise Extension is called MFX EE

Links

MFX Magento JSON API documentation

Step 1: Analysis

Before you can start programming you need to analyse the extension that you're going to change to make it compatible with MFX.

It's necessary to identify 2 things: 1. identify the working model 1. identify database table

The main working model here means that model that is handling your extension's data and that needs to tracked for changes by MFX. For the sake of brevity let's call this extension MyExtension under community codepool (app/code/community/My/Extension). Let's say MyModel in MyExtension handles data and it stores data in database table my_table.

Step 2: Development

Development consists of following steps: 1. create Magento REST API resource for your custom data type 1. create handler class that handles creating of Change Items and handles the data that comes in via the REST API 1. create SQL update scripts that adds required columns to the database table that stores custom extension's data

Creating of REST API resource

Look at an example under Mageflow/Connect/etc/api2.xml.

Create api2.xml into My_Extension etc folder app/code/community/My/Extension/etc.

The XML should have following structure:

<?xml version="1.0"?>
<config>
<api2>
    <resources>
        <my_resource translate="title" module="my_extension">
            <title>My Extension</title>
            <sort_order>10</sort_order>
            <group>mageflow</group> <!-- group MUST contain 'mageflow' w/o quotes -->
            <model>my_extension/api2_my_resource</model>
            <working_model>my_extension/my_model</working_model>
            <handler>my_extension/handler_my_model</handler>
            <privileges>
                <admin>
                    <create>1</create>
                    <retrieve>1</retrieve>
                    <update>1</update>
                    <delete>1</delete>
                </admin>
                <customer>
                    <retrieve>0</retrieve>
                </customer>
                <guest>
                    <retrieve>0</retrieve>
                </guest>
            </privileges>
            <attributes>
                <entity_id type="integer">Entity ID</entity_id>
            </attributes>
            <entity_only_attributes />
            <exclude_attributes />
            <routes>
                <info>
                    <route>/my_resource/my_model/info</route>
                    <action_type>info</action_type>
                </info>
                <entity>
                    <route>/my_resource/my_model/:id</route>
                    <action_type>entity</action_type>
                </entity>
                <entity_with_store>
                    <route>/my_resource/my_model/:id/store/:store</route>
                    <action_type>entity</action_type>
                </entity_with_store>
                <collection>
                    <route>/my_resource/my_model</route>
                    <action_type>collection</action_type>
                </collection>
                <collection_with_store>
                    <route>/my_resource/my_model/store/:store</route>
                    <action_type>collection</action_type>
                </collection_with_store>
            </routes>
            <versions>1</versions>
        </my_resource>
    </resources>
<api2>
</config>

Description of all the nodes under <my_resource />

• <title /> - the title of this API resource. Will be displayed by /api/rest/help resource and in Magento backend under REST Consumer resources.

• <sort_order /> - display order of this resource in listings

• <group /> - API resource group where it belongs to. Must be mageflow.

• <model /> - class that implements API resources

• <working_model /> - model that your API resource is working on. I.e this is the model that you want to manipulate thru API

• <handler /> - class that implements Mageflow_Connect_Model_Interfaces_Dataprocessor and that will do data processing and data packing.

• <privileges /> - this element holds list of privileges of API consumer roles. In this example an authenticated user with "admin" role can create (HTTP verb POST), retrieve (GET), update (PUT) and delete (DELETE) API resources. An authenticated user with "customer" role cannot do anything and also "guest" (anonymous, unauthenticated) access is prohibited.

• <attributes /> - this element holds list of attributes (fields) of my_extension/my_model that can be manipulated via REST API. Every child elements name corresponds directly to a property name in my_model. 2 custom attributes - type and entity_field can be used also. Type is strongly recommended because it makes type mapping more precise for "typeless" JSON data. Attribute "entity_field" can be used to map an API resource attribute and the actual entity field (a model's property) name. All attributes (i.e model properties) that must be manipulated by the REST API must be specified here.

• <entity_only_attributes/> - currently not used

• <exclude_attributes /> - specify list of attributes that must be excluded from manipulations. Rarely used.

• <routes /> - API URL mappings. These are the actual URL-s that will be called by MageFlow when it manipulates data.

• <info> route is special and magic. It provides information about the resource itself. Other routes either return or accept a single entity or collections of entities.

• <versions /> - Magento REST API versions that this resource is supported by. Currently must contain 1.

For adding fields of MyExtension's "working model" to <attributes> see Deep Inside section below.

Creating API Resource Model

The resource models for Magento REST API must reside in a specific folder structure as stated by Magento coding convention.

The location for MyExtension's MyModel (which is handled by my_resource) is: app/code/community/My/Extension/Model/Api2/Myresource/Rest/Admin/V1.php

As per Magento's convention the name of the class is: My_Extension_Model_Api2_Myresource_Rest_Admin_V1

Make your resource class to extend Mageflow_Connect_Model_Api2_Abstract.

If you did everything right then this new API resource should be accessible with Postman or similar tool from the URL: http://your.magento.url/api/rest/my_resource/my_model

Check Mageflow Connector's api.xml for examples. E.g the catalog/product resource URL is: http://your.magento.url/api/rest/catalog/product

Try to send GET and POST requests to this resource URL with Postman or another API testing tool (curl).

Overloading default methods

Inside your API resource class implement methods like _retrieve(), _retrieveCollection(), _create(), _multiUpdate() etc.

These are all overloads of methods with the same name in the abstract class. So if you miss any it won't be a problem because a default exists on the higher level.

Feel free to check all the examples under Mageflow/Connect/Model/Api2/** to get the exact idea.

Creating handler class

Important note: Although it's possible to create your own REST client implementation it's strongly recommended to use the one shipped with MageFlowConnector.

Roles of handler class

A handler class implements methods that are described by the Mageflow_Connect_Model_Interfaces_Dataprocessor interface and that are required for an entity (data model) to be supported by MageFlow.

Mageflow_Connect_Model_Interfaces_Dataprocessor::packData()

Data packing occurs when an entity is saved in Magento backend. In packData you can implement custom logic, filtering or anything that should be done before a ChangeSetItem is created and saved into database.

Mageflow_Connect_Model_Interfaces_Dataprocessor::processData()

Data processing occurs when an entity is sent to Magento instance via REST API. It transforms the incoming JSON into a Magento entity that can be stored into database.

Mageflow_Connect_Model_Interfaces_Dataprocessor::getPreview()

Most ChangeSetItems can have a visual interpretation of the contents that they hold. It's used in Push and Pull grids in Magento backend for easier overview of created ChangeSetItems.

It would make sense to make your handler class to extend abstract class Mageflow_Connect_Model_Handler_Abstract. This abstract class implements Mageflow_Connect_Model_Interfaces_Dataprocessor interface and provides sample / default implementation of all required methods. You can overload all these methods in your own handler class if needed.

Update scripts

Your model's database table my_table needs 3 additional columns: 1. mf_guid 1. created_at 1. updated_at

Those column names must be written exactly as in example above. A Magento database update script can take care of adding those columns to your database table.MFX already has standard templates ready (see the SQL update scripts under Mageflow Extension folder).

Deep inside - mapping data fields

Next step is mapping data fields. You should know all the fields (class properties) already for the entity that you have created yourself. However - when adding support for an existing or 3rd party Magento extension, some research needs to be done.

Three main tools for research are debugger, reading the db table structure and reading the source code.

MFX Observer captures "before save" event for every entity that is saved in the Magento admin and logs it. You can tail the logfiles under var/log and especially the mageflow.log. You can also set a debugger breakpoint to MFX Observer around Mageflow_Connect_Model_Observer::onBeforeSave.

With debugger it's possible to see saved object's structure. As an example following fields are used:

• form_key (we'll be ignoring it)
• name
• is_active
• is_html
• stores (it's an array of store codes)
• checkbox_text
• content
• content_height

When both the model and necessary fields are known, API config (api2.xml, see above) can be created.

Step 3 - Testing

The newly created API resource and data handler can be tested mainly in 2 ways: 1. by creating data entities in Magento backend and checking if the Change Items are created properly 1. by doing GET and POST requests against the API resource and checking if the Change Items are returned and accepted by the API.

Simplest test is getting the data from the API (GET request to my_resource/my_model), deleting the entity in admin manually and then feeding that data back with POST request (POST request to my_resource/my_model). After that check in Magento admin, that the entity is created properly or just do another GET request to the API.

TBD Add more examples and information about testing.

Example payloads for API testing

TBD

Using MageFlow helpers

Mageflow Connector provides a bunch of Helper classes. Feel free to use these.

Data Helper

A lot of generic helper methods.

Oauth Helper

Provides API client instance to connect to MageFlow JSON API amongst other things.

Log Helper

Provides logger

Type Helper

Provides methods for dealing with Types and API resources.

Final word

Last but not least - one thing is not currently covered by MageFlow nor MFX API-s. This is adding a new icon type that is displayed in MageFlow web app for a data type:) In order to get a custom icon for your entity type please contact us at info@mageflow.com.