Open Catalog Interface (OCI) for VirtueMart

Transcription

1 Ver Open Catalog Interface (OCI) for VirtueMart tested with Joomla 2.5 and Virtuemart b Ing. Karl Hirzberger

2 Table of Contents Term declaration... 3 OCI for VirtueMart... 4 Installation... 4 Autologin... 5 Administrator... 5 Frontend... 6 Calling kh_autologin... 6 Test mode... 6 Vmoci... 7 Administrator... 7 Frontend... 8 Test mode... 8 Customizing... 9 What means customizing within kh_vmoci... 9 The standard template... 9 Where are the templates... 9 Edit a template Which fields in the template are available Templates to users Create Custom Unit Field What s new Version Custom unit field for product unit Default template Info for developers and translators License GNU General Public License Page 2 of 18

3 Term declaration The Open Catalog Interface (OCI) is the interface between catalogs and SAP Business-to- Business Procurement. SAP s Open Catalog Interface uses standard Internet protocols. It has already been implemented between several catalog applications and SAP Business-to-Business Procurement. VirtueMart is an Open Source E-Commerce solution to be used together with a Content Management System (CMS) called Joomla!. Joomla and VirtueMart are written in PHP and can be used in typical PHP/MySQL environments. Page 3 of 18

4 OCI for VirtueMart It contains two plugins.. Kh_autologin for automatic login. Kh_vmoci for sending data. Important: Vmoci stores date in the session-object. You have to set the session timeout in Joomla-configuration long enough. Installation Install and activate the Plugins kh_autologin and kh_vmoci. Page 4 of 18

5 Autologin Administrator Parameter Description Values Url redirect Which page should be invoked Empty after login? Any page from Joomla: e.g. Index.php Password How to send the login data unencrypted encrypted SAP standard is unencrypted Debug Debug mode no yes Only for testing Page 5 of 18

6 Frontend Calling kh_autologin Parameter Description Values URL Url of the own Page index.php must be specified Username Username USER user USERNAME username SAP standard is USERNAME Password Password passw PASSW password PASSWORD Hook_Url Url to which the order data will be sent. Is passed from the calling system and stored in the session. Make sure that the session time is large enough. SAP standard is PASSWORD hook_url HOOK_URL SAP standard is HOOK_URL The parameter and parameter names have to be posted to the customer. Example: USERNAME PASSWORD HOOK_URL Name of user Password Will be created by the system Test mode If you call the catalog with HOOK_URL=test, then the OCI-data will be shown. URL: MyShop/index.php?USERNAME=xxx&PASSWORD=xxx&HOOK_URL=test Page 6 of 18

7 Vmoci Vmoci sends the order data to the Hook_url. Important: Vmoci injects Code in the thankyou-page from VirtueMart. Therefore, the ordering process has to end with the thankyou-page of VirtueMart. With basic knowledge of PHP you can determine the fields and the format for transmit. You can define for each user their own template (reformulated) Please read the section Customizing. Administrator Parameter Description Values Automatic If YES: transfers data without clicking Yes transfer the send button. No Time Time in milliseconds before the data Milliseconds will be transferred automatically. Use own unit Use own field for product unit. Yes No Name of own Name of the field, that holds own Name of the field user field product unit. Default Default template Name of the template template Debug Debug mode No Yes Only for testing Page 7 of 18

8 Frontend The OCI will be shown in the thankyou page of Virtuemart. If automatic sending is no, the user have to click the send button. Test mode When HOOK_URL has the value test, the "reflector for testing forms" shows the order data. Page 8 of 18

9 Customizing What means customizing within kh_vmoci With a template, you can determine which data the OCI sends. With simple PHP functions you can also determine the format of data. The standard template The standard template is default.tpl.php. Where are the templates MyJoomlaInstallation/plugins/system/kh_vmoci/template/xxxxx.tpl.php Edit a template. New best way since Version Copy default.tpl.php and name it as you like. Insert the name in the options of the plugin kh_vmoci. Edit your new default template. This way will guarantee that your template will not be overwritten in case of updating kh_vmoci. <form id="kh_vmocisendform" action=" <?php echo $hook_url?>" method="post" target="_top"> standard parameter <input type="hidden" name="~okcode" value="addi" /> <input type="hidden" name="~target" value="_top" /> <input type="hidden" name="~caller" value="ctlg" /> <?php $counter = 1; foreach( $rows as $row ) {?> In the foreach construct, you can determine the data for each product of the order. E.g. <input type="hidden" name="new_item-description[<?php echo $counter?>]" value="<?php echo substr($row->order_item_name,0,40)?>" /> <input type="hidden" name="new_item-quantity[<?php echo $counter?>]" value="<?php echo number_format($row->product_quantity, 3, '.', '')?>" /> <input type="hidden" name=new_item-unit[<?php echo $counter?>]" value="<?php echo substr($row->product_unit,0,3)?>" /> <input type="hidden" name="new_item-price[<?php echo $counter?>]" value="<?php echo number_format($row->product_item_price, 3, '.', '')?>" /> <input type="hidden" name="new_item-priceunit[<?php echo $counter?>]" value="1" /> <input type="hidden" name="new_item-currency[<?php echo $counter?>]" value="<?php echo $row->order_item_currency?>" /> More data.. <?php $counter++;?> <?php } //end for?> <input type="button" class="button" value="<?php echo $button_text?>" id=kh_submitoci name=kh_submitoci onclick="kh_vmocisendform()"> Page 9 of 18

10 </form> Make sure that you use the corrrect format of decimal point. SAP R3 seems to use always the american format ("."). SAP ByD seems to use the local format; (".") for ameriacan and (",") for european. Because i know, that the administrator of each installation can set the parameters in SAP, you have to inform about by the admin Page 10 of 18

11 Which fields in the template are available /* here are all fields // from order $row->order_id; $row->vendor_id; $row->product_id; $row->order_item_sku; $row->order_item_name; $row->product_quantity; New since $row->product_item_price; //per Unit $row->product_tax //per Position $row->product_basepricewithtax // per Unit $row->product_subtotal_discount //per Postion $row->product_final_price; // per Unit $row->order_item_currency; $row->order_status; $row->order_item_cdate; $row->order_item_mdate; $row->product_attribute; //from product language-file $row->product_s_desc; $row->product_desc; //from product $row->product_weight; $row->product_weight_uom; $row->product_length; $row->product_width; $row->product_height; $row->product_lwh_uom; $row->product_url; $row->product_available_date; $row->product_tax_id; $row->product_unit; $row->product_packaging; */ $user_currency Because in some installions of VM, product_currency is empty I sent user_currency to the template. User_currency holds the value of the user currency that is stored in the order. Use it as you see below. <input type="hidden" name="new_item-currency[<?php echo $counter?>]" value="<?php echo!empty($row->order_item_currency)? $row->order_item_currency : $user_currency?>" /> $row->custom_unit Holds the value of the field, that you set in Name of the field, that holds own product unit Use it as you see below. Page 11 of 18

12 <input type="hidden" name="new_item-unit[<?php echo $counter?>]" value="<?php echo!empty($row->custom_unit)? substr($row->custom_unit,0,3) : substr($row->product_unit,0,3)?>" /> If the field use own unit is set to No, then $row->custom_unit is always empty and so the product unit is used. In the other case (use own unit = Yes) we will send custom_unit if its not empty. Page 12 of 18

13 Templates to users!! Only necessary if different customers want different transmitted data. Otherwise simply edit your default template.!! If necessary, you can specify a template for each user. If no template is specified, kh_vmoci uses default.tpl.php. To assign a template to a user, the following steps have to be executed. 1. In VirtueMart -> Configuration-> Shopper Fields insert a new field with the name kh_oci.!! Attention!! There is a bug in VM! a. The new field will be inserted with index 0. If you delete the field (e.g. wrong name) and insert an a new field, then you have two fields with index 0. At worst, you have to correct the index in the database table jos_vm_userfield in the column ordering. Page 13 of 18

14 2. Insert new users in VirtueMart -> Ordes & Shoppers -> Shoppers -> Additional Information and write the name of the template without extensions into the field kh_oci (e.g. mytemplate). Page 14 of 18

15 Create Custom Unit Field 1. In Virtuemart -> Products -> Custom Fields insert a new custom field. Page 15 of 18

16 2. In Product insert the custom field and write the ISO-unit in the field 3. Don t forget to insert the name of the custom field in the options of kh_vmoci Page 16 of 18

17 What s new Version Custom unit field for product unit VM has changed the input of the product unit from free text field to dropdownbox with few options. And so we can t input ISO units to the products. But SAP (especially SAP ByD) needs ISO units. No, we can make a hack in the core of VM to insert ISO or we can use a custom field. I mean, that a custom field is a better way, because the hack is gone in case of updating VM. So I extended kh_vmoci in a way, that you can use a custom field for ISO unit. Default template Now you can define your own default template in the settings of kh_vmoci. This template will not be overwritten in case of update. Info for developers and translators. Because there were troubles with other extensions, I changed the name of the variables in the language files. Each variable holds now the name of the plugin. E.g. USER_FIELD_LABEL is named now KH_VMOCI_USERFIELD_LABEL Page 17 of 18

18 Authors Karl Hirzberger (developer) Dorin Marmeliuc (SAP ByD) Anonymus (SAP R3) License GNU General Public License Page 18 of 18