Document toolboxDocument toolbox

Integration ServiceOptimizer XML Format for Table-Based Notes

Owned by Matthew Wren
Nov 24, 2022
3 min read

Related Pages:

Certain ServiceOptimizer SOAP APIs allow free-form notes to be passed in using an XML format, which causes ServiceGANTT and ServiceMobility to display the notes in a table-based format.

Displaying Notes in a Table

Integration ServiceOptimizer Book Non-Appointment Job SOAP API and Integration ServiceOptimizer Book Appointment SOAP API both contain a field called desc2, of standard Data Type Desc2, which is is a free format text field of 3500 characters.

The contents of this field are displayed in the ServiceGANTT Job Details screen and can be optionally passed to the mobile device where ServiceMobility is implemented.

In order to make this field more readable, an XML format can be passed in through the SOAP APIs, in which case ServiceGANTT and ServiceMobility will display the text as a table. 

Through ServiceMobility, this data can be made available to other applications and the XML format can be used to determine its usage in these applications.

XML Definition

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="p">
        <xsd:complexType>
            <xsd:simpleContent>
                <xsd:extension base="xsd:string">
                    <xsd:attribute name="id" type="xsd:string"
                        use="required" />
                    <xsd:attribute name="d" type="xsd:boolean"
                        use="optional" default="1" />
                    <xsd:attribute name="x" type="xsd:string"
                        use="optional" />
                </xsd:extension>
            </xsd:simpleContent>
        </xsd:complexType>
    </xsd:element>
    <xsd:element name="notes">
        <xsd:complexType>
            <xsd:sequence minOccurs="1" maxOccurs="unbounded">
                <xsd:element ref="p" />
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
</xsd:schema>

Attribute Name

Description

id

Display name for the value

d

Should the data be displayed on the gantt. 1 = yes, 0 = no.  Default value is yes so this attribute can be omitted if display is required.

x

Used to specify whether the data should be displayed in ServiceMobility and/or other application.

0 = Neither

1 = Mobility Only

2 = ‘Other application’ Only

3 = Both

Default value is 0 so this attribute can be omitted if no external use of this value is required.

Example

<?xml version="1.0" encoding="UTF-8"?>
<notes>
    <p id="Product Code" d="0" x="2">1357SEN-125</p>
    <p id="Serial Number" d="0" x="3"></p>
    <p id="Contract Number" x="3">123456789-34</p>
    <p id="Warranty Type" x="1">Insured</p>
    <p id="Payment Type" d="0" x="3">Account</p>
    <p id="Damage Assessment" x="3">Part needs to be replaced</p>
</notes>

It should be understood that the definition of the desc2 field is not altered to handle this functionality and as such the XML is in fact passed in as a string:

<?xml version="1.0" encoding="UTF-8"?><notes><p id="Product Code" d="0" x="2">1357SEN-125</p><p id="Serial Number" d="0" x="3"></p><p id="Contract Number" x="3">123456789-34</p><p id="Warranty Type" x="1">Insured</p><p id="Payment Type" d="0" x="3">Account</p><p id="Damage Assessment" x="3">Part needs to be replaced</p></notes>