OBM Bridge Documentation

Default Openbravo does not enable to assign one product to the more categories. OB Bridge brings this well know feature from Magento so one product could be placed into several categories now. Whole structure of categories and sub-categories is synchronized to Magento.

Configurable product is a known term from Magento. OB Bridge brings same functionality into Openbravo. User can make more products with the same attribute set, define for each one an attribute value and create one configurable product based on the same attribute set. As a result you get only one product in your web store that wraps all child-products with unique attribute values.

Related products works the same way as in Magento now. There is one product for example LCD monitor and there are two products DVI and HDMI cable as its related products that can be bought with monitor. The same relations and minimum quantity of related product to main product can be defined in Openbravo.

This functionality allows to add to product additional files like images, pdfs, docs etc. These files are synchronized to Magento as well.

OB Bridge provides API for other modules to be notified about the paid sales orders. Sales orders are checked periodically using background process and for every paid sales order all the registered listeners from other modules are called.

It brings core functionality of Magento into Openbravo as well. User can define speecial product associated to category (probably coupon category), product has its rules (discount amount, counts of usage, etc.). When that product is bougth, the coupon code is generated, sent to the customer via email and sent to Magento as well for synchronization.

Provides a WYSIWYG editor for input fields in Openbravo.

Provides API for other modules to be notified about the Recalculate Promotions button in Sales Order window. There's a custom Java process that must be assigned to the Recalculate Promotions button in order to work properly and be notified.

Shipping price is defined as another order line with name of shipping company and price that is set for the order. You can set it by click on "Set Shipping Price" and put in required price.

Figure 2.1. Setting the shipping price

Before installing ARTIO OB Bridge, you need to have:

Make sure that all the needed directories (as requested by Openbravo or Magento) are writable. And database users have all granted permissions.

Please, watch for any error messages generated during installation. If any error appears, the installation might not have been completed correctly.

The main point of communication between Openbravo and Magento is calling Magento web services API from Openbravo. All requests are secured on Magento site by username and password, that must be assigned to our connection. To create our XML-RPC User just follow these steps:

In Admin mode go to System -> Web Services -> SOAP-XML-RPC-Roles and create a role with all permisions. Next go to System -> Web Services -> SOAP-XML-RPC-Users and create an user with assignation of registered role.

Figure 4.1. Creating Magento Xml-rpc user

As a next step, we need to configure a web store in our Openbravo installation. Web store is nothig else, just record contains URL of Magento API and username and password for secured connection.

To set Web store just open window "Web store", create a new record and fill all required fields:

Figure 4.2. Web store configuration

When Openbravo is able to connect to Magento via API, it is possible to define synchronization rules. It means to set value how often must synchronization for particular object occurs. For instance, lets take a customer entity. It can sychronized quite often, regularely about every ten minutes. Other entity, for example customer categories, can be synchronized just in time of created or updated some. :

To create new synchronization process, is needed to open "Process Request" window and fill these fields:

Figure 4.3. Process Request registration

In case of using some constants with defined values that needs to be the same in both systems, you can set them here. In Openbravo, there is a database table AS_Settings handled from window IS Settings. Synchronization is supported by ISSettingsProcess, that takes needed attributes and their values to save them in magento. Only these two are now important to know:

4.4.1. Related products discount

OB Bridge contains support for related products and this is a place where you can define a special discount for all related producs. This feature supports to set a discount for specific amount of child-products, which are related to the main product, if child-producs are bough at one with main product in one order. If the discount is set to zero, there is no discount applied.

Figure 4.4. Related product discount

 

4.4.2. Shipping product

This is very important part of handling shipping price to each order. If you create an order at Magento site, the shipping price is adjustable by settings. Openbravo has an option to define a shipping price as was written in chapter 2. To allow this functionality, is needed to create a simple product, name it as you wish, with no attrbutes and no prices and in the window IS Settings assign it as a shipping product. Thanks to this, it will be assigned to each order as another order line that will define a shipping price.

Figure 4.5. Shipping product

 

4.4.3. Coupon discount product

Customer can buy voucher as virtual product. It means that voucher with uniqe code is generated and could be used as gift. Checkout page of Magneto has a field for enter voucher code. Magento validate if voucher code is corrent and apply discount. Order contains one more line with discount value. Discounted order is synchronized into Openbravo.

Figure 4.6. Coupon code settings

 

In default, this process handles the synchronization of customer categories from Openbravo to Magento. If category is named "Supplier Services" or "Supplier", could be changed in the configuration, the process will assign no tax to them.

Name:Customer Category Synchronization

Way:One way, from Openbravo to Magento

Tables:

This process reflects all updates on customer entity, include its addresses and contact information on both sites of communication.

Name:Customer Synchronisation

Way: Two way, from Openbravo to Magento and vice versa.

Tables:

Notice: Two way synchronization can cause conflicts. That means the situatition when on both sites a newly updated record appears and it's ready to synchronize. This case is solved in this way: updated record from Magento will replace the changes in Openbravo. Message about the potential conflict is written into log file.

*includes all derivated tables by attribute types (_int, _date, _text, _varchar)

Product categories, its names, descriptions, places in a category tree are moved from Openbravo to Magento by this process. It can reflect also changes in category tree by moving categories on Magento site.

Name: Product Category Synchronization

Way: One way, from Openbravo to Magento.

Tables:

*includes all derivated tables by attribute types (_int, _date, _text, _varchar)

Product can be more specificaly defined by its attributes wapped in attribute set. They can be created and managed on Openbravo and Magento. This process allows user to define them only in Openbravo with effects on Magento side.

Name: ARTIO AttributeSet Synchronization

Way: One way, from Openbravo to Magento.

Tables:

Notice: This process creates only attribute sets and attributes. All attributes are created as type "select" and values for them are sending by product process directly to the saved product.

Product itself is moved from Openbravo to Magento by this process. Synchronization includes information about prices, descriptions, meta-information, added attributes by attribute set, tax category and visibility.

Name: Product Synchronization

Way: One way, from Openbravo to Magento.

Tables:

*includes all derivated tables by attribute types (_int, _date, _text, _varchar)

Product Relations is a binding between two products that gives one to position of related to second. This relation is moved to Magento by this process on already synchronized products.

Name: Product Relations Synchronization

Way: One way, from Openbravo to Magento.

Tables:

Process ensures synchronization images for products from Openbravo to Magento.

Name: Product Image Synchronization

Way: One way, from Openbravo to Magento.

Tables:

Notice: This process moves only information about picture (name, address, type), not picture itself. This means that user have to physicaly move his images to required directory and information like name, type, address are moved by this process into Magento database. It is possible to use rsync to sychronize product images.

Products stock data, information about avalable counts of each product in warehouse is by this process moved into Magento. It's very simple process that moves just a little data so it doesn't take a lot of system resources. By this way it can be scheduled in shorter iterations.

Name: Stock Data Synchronisation

Way: One way, from Openbravo to Magento.

Tables:

Coupon rule defines conditions for getting discount at the cart/checkout. Scenario how this whole process wiht synchronization works is described in chapter 2.6. This process has as a task to move Openbravo coupon products as coupon rules to Magento.

Name: Coupon Rules Synchronization

Way: One way, from Openbravo to Magento.

Tables:

Notice: This process creates products too. It is purchasable product that generates coupon code to customer.

After coupon product is bought and paid, on Openbravo site is created coupon code that is synchronized to Magento by this process. It allowes customer to use his coupon on eshop.

Name: Coupon Code Synchronization

Way: One way, from Openbravo to Magento.

Tables:

Notice: After using coupon on order, discount is show and moved back with code to Openbravo, so there is no option to use code more than once.

Ther is this process that handles moving records from Magento eshop to Openbravo ERP and back to synchronize new or updated order. Customer can see on Magento website own orders and made changes. The order entity record in our terminilogy means an order with all order items, customer with his billing and shipping address and shipping price and discounts too.

Name: Order Synchronization

Way: Two way, from Openbravo to Magento and back.

Tables:

Notice 1: Order can not be updated at Magento site, so when update happens on Openbravo site, process will reorder (cancel old and create new) the order on Magento site.

Notice 2: Order has its specific order number, it is created defaultly in Magento and Openbravo too. As option to show to the customer the right order number, there is in Magento created table order_number where are stored all that number during synchronization.

Payment of order is a little more complicated issue, and by this way is handled by two processes. There is to solve creating only one invoice, synchronize payments both ways and booking orders too. So let's split this chapter to make it simple.

To synchronize record that point on order what is and what is not shipped, there is this process. A part of that is sending tracking numbers of packages to order on Magento site, to notice his future owner.

Name: ARTIO Shipping Synchronisation

Way: One way, from Openbravo to Magento.

Tables:

Notice: When order is marked as "can be shipped separately", there is option to send not all order items but just available product. In this case there will be synchronized this partly shipping.

Settings presented in previous chapter (4) can be importnat in Magento too. For example the related product discount is moved as constant into Magento to the tabel core_config_data with record path "sales/related_discount/discount_in_percent".

Name: ARTIO IS Settings Synchronization

Way: One way, from Openbravo to Magento.

Tables:

When some entity record is deleted on Openbravo and we need to delete him on the Magento site, we need to use this synchronization process.

Name: ARTIO Delete Process

Way: One way, from Openbravo to Magento.

Notice: This is ready for enetities : customer, product, product category and order (not booked or paid).

In time, when you need to create your own synchronize process, you can just implement the abstract class net.artio.magento.MagentoSyncProcess.java and it will give you a set of method to implement.

Complete documentation describes implemented methods, inputs and outputs is in java doc.

To create process that will synchronize entity records one way, you do not have to implement all of this methods. In every case, the method initialize have to return true, so that's the firts thing you have to check. To implement GetName and getItemPrintName is good for logging.

After your process is ready, you need to register it into Openbravo. Log in as System Administrator, go to window Report and process and create a new process record.

Figure 7.1. Report and Process window

Triggers are one of the best and maybe the fastest way how to handle changes on entity records. How to create own trigger is described in this tutorial: http://wiki.openbravo.com/wiki/ERP_2.50:Developers_Guide/How_To_Create_a_Trigger

-- Function: amsp_m_product_trg()
-- DROP FUNCTION amsp_m_product_trg();
CREATE OR REPLACE FUNCTION amsp_m_product_trg()
  RETURNS trigger AS
$BODY$ DECLARE 
 
 BEGIN
    SELECT COUNT(*) INTO v_count FROM AMSP_Process;
    RAISE NOTICE '%',v_count;
    IF v_count > 0 THEN
    
        RETURN NEW;
    END IF;
    
    IF TG_OP = 'UPDATE' THEN 
        BEGIN
        IF(NEW.EM_AMSP_MAGENTO_KEY = OLD.EM_AMSP_MAGENTO_KEY
            AND NEW.EM_AMSP_SYNC_AT = OLD.EM_AMSP_SYNC_AT)
        THEN
            NEW.EM_AMSP_SYNC_AT := null;
            RETURN NEW;
        END IF;
    RETURN NEW;
    END;
    END IF;
    IF TG_OP = 'DELETE' THEN 
    BEGIN
        INSERT INTO AMSP_DELETE VALUES(get_uuid(), '0', '0', 'Y', TO_DATE(NOW()), '0', TO_DATE(NOW()), '0', 'product', OLD.value);
    
    RETURN OLD;
    END;
    ELSE 
    RETURN NEW; 
    END IF; 
END 
; $BODY$
  LANGUAGE plpgsql VOLATILE
  COST 100;
ALTER FUNCTION amsp_m_product_trg()
  OWNER TO tad;

Each entity where we need synchronize updated records too, have to be marked. As a main synchronization mark is used em_amsp_sync_at column in the Openbravo entity table. When it is empty, the entity record have to be synchronized. When the entity record is updated, this is a right event to clear that column. So in each entity there is a trigger ready to handle update event where is only one simple condition. When there is an update event and the new record has the same em_amsp_magento_key and em_amsp_sync_at (so it was not actualized during synchronization) as the old record, the update belongs to another entity columns and em_amsp_sync_at has to be errased (set to null). After that it will be finded by his process to synchronization.

Some triggers handles delete event too. Entities where delete have to be performed on Magento site too like customer or product just run their trigger on delete event and to table amsp_delete type of entity and its magento identifier* (em_amsp_magento_key => if is null, the entity record was not synchronized and there is no need to synchronize its delete) is stored. and of cource the scheduled Delete process will iterate all records and run Magento API methods to delete them.

*in case of product, there is sku used as identifier

Best way how to start extending API is to read some official tutorial, like this http://www.magentocommerce.com/wiki/doc/webservices-api/custom-api. In the next step is very important to know in what shape we are sending data from Openbravo and in what shape we are waiting for an answer. Let's have a look at this:

With knowledge of input and output you can create your own methods that you will call from Openbravo scheduled process.