Customization Packages

• Package structure
• Create a package
  • Package file template
• Tips
• Sample package files
• XML refresher
• What’s next?

A package is an XML document that defines one or more customization activities that are deployed together to enable a feature.

Package structure

By grouping related activities in a package, you ensure that changes to one activity do not adversely affect other activities in the package. You also have a single location where you can modify all aspects of a feature.

A customization package has a customErpPackage root element that wraps the child elements, as shown:

The child elements provide the content for the customization feature as follows:

• packageDescription names the package, identifies the author, and explains its purpose. This is the only required element.
• customFields wrap the individual customField activities. This is the first activity added to a package and often contains data that other activities will need.
• smartLinks wrap the SmartLink Click, SmartLink Fetch, Smart Rule, and Smart Event activities. Although these activities serve different functions, they share many data commonalities—in XML terms, they fit under one schema definition.
• customReports wrap the individual customReport activities.
• interactiveReports wrap the individual interactiveReport activities.

Create a package

When creating a package, the easiest approach is to start with the XML package file template, then use the Sage Intacct UI to generate parts of the file. For example, you can export the definition of a custom report or interactive custom report using Export Def from the UI, then paste that definition (minus the XML declaration) into the correct place in the template file. You can do the same thing with Smart Events and Smart Rules—see the Sage Intacct product help for more information about using Export Def.

Package file template

<?xml version='1.0' encoding='UTF-8'?>
<customErpPackage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <packageDescription>
        <name>My custom package</name>
        <description>Good stuff you will want</description>
        <author>My name</author>
    </packageDescription>
    <customFields>
        <!-- Put the exported definitions for custom fields here. -->
    </customFields>
    <smartLinks>
        <!-- Put the exported definitions of Smart Rules, Smart Events, or Smartlinks here -->
    </smartLinks>
    <customReports>
        <!-- Put the exported definitions of custom reports here. -->
    </customReports>
    <interactiveReports>
        <!-- Put the exported definitions of interactive custom reports reports here. -->
    </interactiveReports>
</customErpPackage>

Tips

• Understand that if a customization package is deleted in the Sage Intacct UI, everything in that package is deleted. For example, if you include a custom field in your package, and that custom field is used outside of the context of that package, then deleting the package from the UI will delete that custom field everywhere it resides.
• You can put more than one custom field, Smart Rule, Smart Event, Smartlink, or custom report in the appropriate section of the template.
• You can provide a single customization that applies to multiple transaction definitions. Simply choose Inventory Control Transaction Detail, Purchase Order Transaction Detail, or Order Entry Transaction Detail in the Object field of the customization, then add as many transaction definitions as you want in the Document Type field.
• Be aware that when a custom report is installed as part of a package, it cannot be edited in the Sage Intacct UI. However, the report can be duplicated then edited.
• Remove any sections you do not use from the templates—they are not allowed.
• Each activity exported from the Sage Intacct UI includes the XML declaration at the top. Do not include the declaration when you cut and paste into the template.
• Even though you can export a custom list view, the importer does not implement custom list view imports.
• See the Sage Intacct product help for instructions on exporting/importing various activities using the Customization Services wizard and the Custom Report wizard.

Sample package files

The following shows a sample package file that provides a custom field and a related custom report:

<?xml version="1.0" encoding="UTF-8"?>
<customErpPackage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <packageDescription>
        <name>Commission Report with Subtotals</name>
        <description>Commission Report with Subtotals</description>
        <author>johnm</author>
    </packageDescription>
    <customFields>
        <customField>
            <customFieldId>COMMISSION</customFieldId>
            <type>currency</type>
            <ownerObject>arinvoice</ownerObject>
            <label>Commission</label>
            <fieldSet />
            <page>Header</page>
            <dataDescription>
                <currency>
                    <leftOfDecimal>3</leftOfDecimal>
                    <rightOfDecimal>2</rightOfDecimal>
                </currency>
            </dataDescription>
            <description>Commission Amount</description>
        </customField>
    </customFields>
    <customReports>
        <customReport>
            <name>Commission Report with Subtotals</name>
            <description>Commission Report with Subtotals</description>
            <type>summary</type>
            <module>ar</module>
            <root>ARINVOICE</root>
            <columns>
                <field>
                    <path>ARINVOICE.CUSTOMER.CUSTOMERID</path>
                </field>
            </columns>
        </customReport>
    </customReports>
    <interactiveReports>
        <interactiveReport>
            <name>Interactive commission report</name>
            <reportingArea>AR Invoices</reportingArea>
            <type>crw</type>
            <module>ar</module>
            <queryDef>
                PD94bWwgdmV...c2F3OnJlcG9ydD4=
            </queryDef>
        </interactiveReport>
    </interactiveReports>
</customErpPackage>

This excerpt from a package file shows how to use the <documentTypes> tag to specify that a single customization applies to multiple transaction definitions:

<customFields>
    <customField>
        <customFieldID>CUSTOMER_HEALTH</customFieldID>
        ...
        <documentTypes>
            <documentType>Purchase Order-</documentType>
            <documentType>PO Receiver</documentType>
        </documentTypes>
    </customField>
</customFields>

XML refresher

• There may be no white space (character spaces or line returns) before the XML declaration.
• All element attribute values must be in quotation marks (either single or double).
• Tags and Attributes are case sensitive; for example <col>, <COL>, and <Col> are considered three different tags.
• An element must have both an opening and a closing tag, unless it is an empty element.
• If a tag is a standalone empty element, it must contain a closing slash before the end of the tag ( <col />).
• All opening and closing tags must nest correctly without overlap.
• The document must have a single root element, which is a unique element that encloses the entire document. The root element may be used only once in the document.

What’s next?

• Learn about capabilities of Customization Services by walking through the creation of an API Smart Event with conditions.

Provide feedback