Customizing Quotes to Orders
With Sage ERP Accpac 6.0A we have incorporated Web based versions of the Accpac Order and Quote entry screens into SageCRM. These are the first accounting document entry screens in the new Accpac Sage Web Toolkit (SWT) technology. A common question I get asked is how to customize these screens. Certainly the regular current Accpac Order Entry screen is one of the most customized screens in the Accpac system. However it is very hard to customize the current screen when it’s run from SageCRM because of the way it is packaged and run from a CAB file. The new screens are regular Accpac screens and run inside SageCRM just like they would run from Accpac. This means all the regular customization techniques for the new web based technology can be used on them.
The XML file is located in the folder: C:\”Program Files (x86)\Common Files\Sage\Sage Accpac\Tomcat6\portal\swtServices\uiDefinitions\oe60a\eng\sagecrmorderui”. The file we will look at is SageCRMOrderUIUIDefinition.xml. The XML files for a couple of popup forms are here also and you can customize these also. You can edit these files in any text or XML editor. If you have the SDK you can edit these files in a visual SWT UI designer, however for the purposes of this blog posting we will assume you don’t have the SDK and edit this file directly as a text file. One nice thing about the new web based technologies is that they are entirely configured by XML files, which being text files can easily be edited for customization purposes.
Introduction to XML
First just a few notes about XML. It’s worth your while to check out a site like http://en.wikipedia.org/wiki/XML to learn the basics of XML. But for what we’re doing here you really don’t need to know very much, just how to find things, cut and paste things, and make minor changes.
The key point is that all data is contained between a starting tag and a closing tag like:
<caption>This is a caption</caption>
Where the closing tag is the opening tag with a / in front of it.
Sometimes you can express attributes for a tag like:
<caption font=”Sans Serif”>This is a caption</caption>
Also if there is no general data then you can end the tag with a /> like:
<caption font=”Sans Serif” text=”This is a caption”/>
Generally most of the other stuff you find in the XML file, you would leave alone, like the version and encoding and such.
We talked a bit on how to layout forms in https://smist08.wordpress.com/2010/05/28/how-to-layout-forms-in-sage-erp-accpac-6/. So we won’t talk too much about how to control the layout here, but we may look at this more in depth in a future posting. But beware that there are two types of widgets in a screen definition file, there are layout widgets that control how things look and then data widgets for displaying/editing data.
Here a technical description of widgets in the layout XML files taken from the reference XSD file. An XSD file defines what is correct in a corresponding XML file
A widget element must contain a “type” attribute (corresponding to the namespace-qualified class name of the widget). It may contain other attributes such as an ID as well as other attributes corresponding to simple properties (such as “enabled”).
A widget element may also contain other elements that correspond to compound properties. These compound properties include action (for predefined actions associated with button-like widgets), translatable display string properties such as caption, column headers (for tables), images (which include the URLs to the normal, normal, mouseover, and disabled images for a widget), search fields (for finders) and selectable items (for list boxes).
A “regular” container (“HasWidgets”) widget’s element contains a “children” element. That “children” element in turn contains a list of widget elements for child widgets.
A grid-type container (“HasWidgetsInGrid”) widget’s element contains a “rows” element. That “rows” element in turn contains a list of “row” elements, each of which contains a list of “cell” elements. Each cell is either empty or contains one (child) widget element.
A dock panel widget’s element contains a “dockedWidgets” element. That “dockedWidgets” element in turn contains a set of docking position elements (e.g. “northWidget” element) for north, south, east, west, and center (in that order). Each docking position element is either empty or contains one (child) widget element.
A menu bar or menu button widget’s element contains a “menuItemList” element. That “menuItemList” element in turn contains a list of “menuitem” elements, which in turn may contain other “menuItemList” elements (representing submenus).
Below is a screen shot of the Order Entry screen in CRM as it ships un-modified in the product:
Editing the Layout
Within the layout XML files are widget definitions of the form:
<widget type=”swt:SwtTextBox” id=”orders_ORDNUMBER” enabled=”true” datasourceID=”oeorders” propertyBinding=”ORDNUMBER” width=”170″ style=”swt-TextBox-nohint-noBackground”/>
This is the contents for the base structure of a widget element. These are the elements we customize.
Changing a Caption
Suppose we want to change the Document Number caption in this form. We can find the XML tag for this widget in the XML file:
<widget type=”swt:SwtLabel” style=”swt-Label documentDetails-LeftRow”>
<transText text=”xDocument Number:” textID=”oe60a_sagecrmorderui_lblDocNumber”/>
This references a nice translatable string that exists in the Portal database, but we want to change this to a hard coded string specific for our customer. If we blank out the textID field, then it will use the text specified in the text field, so we can change the above to:
<widget type=”swt:SwtLabel” style=”swt-Label documentDetails-LeftRow”>
<transText text=”Customer Specific Reference:” textID=””/>
Once we save this change, then running the Q2O Order Entry screen will show this caption instead of the one from the Portal database.
Adding a Field
The Quote to Order screen is optimized to make it easy for salespeople to enter orders quickly. However suppose the form is too simple and you require your sales people to enter another field that isn’t already on this screen. In the Q2O screen there is the order description field, but no order reference field. So let’s add the reference field to the Document Details tab.
To do this, find the SwtSingleTabPanel with transText: oe60a_sagecrmorderui_pnlDocDetails. A couple of lines below this is a SwtGridPanel with a rowCount of 4, change this rowCount to 6 (since we are adding one row with the label and one with the textbox.
Then add a new <row> at the end of the grid, this will be just before the </rows> tag:
<text> <transText text=”Reference:” textID=””/> </text>
<widget type=”swt:SwtTextBox” id=”orders_REFERENCE” datasourceID=”oeorders”
This will add the controls to the layout. However it won’t work quite yet. This is because the REFERENCE field for the Order Header isn’t provided in the SData feed. However we can add it. To do this we need to edit another XML file, namely: C:\Program Files (x86)\Common Files\Sage\Sage Accpac\Tomcat6\portal\sageERP\oe60a\resourceMap\OEOrderViewMapping.xml. This file among other things defines which Order fields to include in the SData feed. In the <includedFields> section for the header, add the line:
<resourceViewField viewFieldName=”REFERENCE” />
This will add the REFERENCE feed to the header. Make sure you add this to the includeFields for the header and not one of the details.
Whenever you change one of the SData definition files, you need to restart Tomcat to have it take effect. After you do this you should see the new field on the form and be able to set and edit it.
Here is the screen shot with these two customizations:
Hopefully this starts to give some idea of how to customize the new screens. If you have the SDK then you can use the SwtUIDesigner to edit these forms; but, hopefully in future versions the visual screen designer will be included in the main product making this process much easier for non-SDK partners to customize.
But at least for now, once you get used to XML you can do a lot of customizations to the current Web based version 6.0A screens.