XML

All models developed with the SDK support XML as a data format. This section shows you how to load Models into the database using XML.

Procedure 16.1. Loading Data Using XML

  1. Review the XML Schema

    The SDK generates an XML schemahttp://www.w3.org/XML/Schema (XSD) for each Model as part of the build process. This XML Schema defines all the XML element and attributes names and types to help you form a valid XML document.

    You can review the schema for your own models in the build/genxsd folder of your module. The java doc documentation for each model contains an excerpt of the XSD../../api/javadoc/com/onenetwork/platform/common/Enterprise.html. See

    <complexType name="Enterprise">
    <complexContent>
    <extension base="{http://www.onenetwork.com/Platform}Model">
    <sequence>
    <element name="ActionExecTime" type="{http://www.onenetwork.com/Platform}DateTime" minOccurs="0"/>
    <element name="ActionName" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="InputRefId" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="Error" type="{http://www.onenetwork.com/Platform}Error" minOccurs="0"/>
    <element name="Name" type="{http://www.w3.org/2001/XMLSchema}string"/>
    <element name="ValueChainId" type="{http://www.w3.org/2001/XMLSchema}long"/>
    <element name="DisplayName" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="Description" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="TypeName" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="StartDayOfWeek" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="DUNSNumber" type="{http://www.w3.org/2001/XMLSchema}long" minOccurs="0"/>
    <element name="TimeZoneId" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="LastModifiedDate" type="{http://www.onenetwork.com/Platform}DateTime" minOccurs="0"/>
    <element name="LastModifiedUser" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="Active" type="{http://www.w3.org/2001/XMLSchema}boolean" minOccurs="0"/>
    <element name="LocalOnboardCompleted" type="{http://www.w3.org/2001/XMLSchema}boolean" minOccurs="0"/>
    <element name="LastComputedDate" type="{http://www.onenetwork.com/Platform}DateTime" minOccurs="0"/>
    <element name="AttachmentsDisabled" type="{http://www.w3.org/2001/XMLSchema}boolean" minOccurs="0"/>
    <element name="Address" type="{http://www.onenetwork.com/Platform}Address" minOccurs="0"/>
    <element name="Phone" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="Fax" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="BillingAddress" type="{http://www.onenetwork.com/Platform}Address" minOccurs="0"/>
    <element name="BillingContactFirstName" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="BillingContactLastName" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="BillingContactPhone" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="BillingContactFax" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="BillingContactEmail" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="OneEnterpriseNumber" type="{http://www.w3.org/2001/XMLSchema}string" minOccurs="0"/>
    <element name="ExcludeFromCmd" type="{http://www.w3.org/2001/XMLSchema}boolean" minOccurs="0"/>
    <element name="Udfs" type="{http://www.onenetwork.com/Platform}NameValuePairList" minOccurs="0"/>
    <element name="Issue" type="{http://www.onenetwork.com/Platform}Issue" maxOccurs="unbounded" minOccurs="0"/>
    <element ref="{http://www.onenetwork.com/Platform}MDFs" maxOccurs="unbounded" minOccurs="0"/>
    </sequence>
    </extension>
    </complexContent>
    </complexType>

    You can also access the XSD for core Platform models in a live server by accessing http://localhost/oms/OneNetwork.xsd, and each deployed module's XSD will be available at http://localhost/oms/apps/ModuleName/moduleModels.xsd. (Replace ModuleName with the actual module name in this URL.)

  2. Choose an Action

    As with all Model writes in Platform, you will need to execute an Action in order to load models through XML. You can locate Actions by viewing the MPT within your Module, or by viewing the ModelDocs../../api/modeldoc/index.html of other Modules.

    For this example, we'll use the PLT.InsertOrUpdate action on the Enterprise model from the Platform core. Review your specific Action to find out which fields are optional/required, and whether Create, Update or Delete are supported.

  3. Create your XML

    Next, you should create the XML you intend to load. To create a sample, right-click the Model in question in your MPT and select Generate Sample XML.
    images/download/attachments/144835940/GenerateSampleXml-version-1-modificationdate-1678373398000-api-v2.png
    This will generate sample XML which you can copy, paste and modify.
    images/download/attachments/144835940/SampleXml-version-1-modificationdate-1678373398000-api-v2.png

    The outermost element for these XML documents is always ModelList. ModelList is a simple container for models that provides a default ValueChainId, CustomModelName and ActionName to be used when writing the specific models. You can then include as many Model instances as you want (in this case Enterprise) within the ModelList, but please note that they must all be of the same type. (For example, you can't mix Enterprise and Organization in the same ModelList.)

    For the purposes of this example, we'll use the following XML. Note in particular that we set the ValueChain ID to the Bookstore ValueChain (9123), and that we gave a CustomModelName of Standard Enterprise and ActionName of PLT.InsertOrUpdate.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <ModelList xmlns="http://www.onenetwork.com/Platform" xmlns:ZBKS="http://www.mybooks.com/Bookstore">
    <ValueChainId>9123</ValueChainId>
    <CustomModelName>Standard Enterprise</CustomModelName>
    <ActionName>PLT.InsertOrUpdate</ActionName>
    <Enterprise>
    <Name>LoadDataXmlEnterprise1</Name>
    <ValueChainId>9123</ValueChainId>
    <Description>LoadData sample</Description>
    <Address>
    <Country>US</Country>
    <Component Type="STATE">TX</Component>
    <Component Type="CITY">Dallas</Component>
    <Component Type="STREET1">4055 Valley View Ln</Component>
    <Component Type="ZIP">75000</Component>
    </Address>
    </Enterprise>
    <Enterprise>
    <Name>LoadDataXmlEnterprise2</Name>
    <ValueChainId>9123</ValueChainId>
    <Description>LoadData sample 2</Description>
    <Address>
    <Country>US</Country>
    <Component Type="STATE">TX</Component>
    <Component Type="CITY">Dallas</Component>
    <Component Type="STREET1">4056 Valley View Ln</Component>
    <Component Type="ZIP">75000</Component>
    </Address>
    </Enterprise>
    </ModelList>

    We will save this in data/LoadDataXmlEnterprises.xml.

  4. Using the Load-Data Ant Target

    One convenient way to load data is through the load-data ant target in the dataset. This ant target loads XML and CSV files using LoadData.xml as a controller. Let's add a ModelFile entry for LoadDataXmlEnterprises.xml:
    images/download/attachments/144835940/LoadDataXmlEnt-version-1-modificationdate-1678373398000-api-v2.png

    Now run the load-data ant target. Assuming you have not specified a remote Location tag in your LoadData.xml, the data is loaded to your local server. You can review the Platform Server console output for errors.

    But what if I make a mistake? In the event that your XML is malformed or invalid, or the ActionName is invalid, or required fields are missing, or any other type of mistake is made, these errors will be reported in the Platform Server console.

Procedure 16.2. To Convert Models to XML

The Model interface includes a toXML() method which will convert that model (and its children) into XML. For example, the following java code could be used to implement a REST resource that creates an Enterprise model and returns XML to the caller:

@GET
@Path("/EnterpriseXml")
@Produces({"text/xml"})
public String getEnterpriseXml() {
Enterprise enterprise = new Enterprise();
enterprise.setValueChainId(100L);
enterprise.setName("MyEnterprise");
enterprise.setDescription("Test for XML");
return enterprise.toXML();
}
The XML produced will look like this:
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Enterprise xmlns="http://www.onenetwork.com/Platform">
<Name>MyEnterprise</Name>
<ValueChainId>100</ValueChainId>
<Description>Test for XML</Description>
</Enterprise>
You can also convert a ModelList to XML.
 
@GET
@Path("/ModelListXml")
@Produces({"text/xml"})
public String getModelListXml() {
Enterprise enterprise = new Enterprise();
enterprise.setValueChainId(100L);
enterprise.setName("MyEnterprise");
enterprise.setDescription("Test for XML");
ModelList<Enterprise> modelList = new ModelList<Enterprise>("CreateEnterprises", enterprise);
return modelList.toXML();
}
This will produce:
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ModelList xmlns="http://www.onenetwork.com/Platform">
<ValueChainId>0</ValueChainId>
<CustomModelName>Standard Enterprise</CustomModelName>
<ActionName>CreateEnterprises</ActionName>
<Enterprise>
<Name>MyEnterprise</Name>
<ValueChainId>100</ValueChainId>
<Description>Test for XML</Description>
</Enterprise>
</ModelList>

For more advanced use cases where you want to stream the XML rather than creating a String, you can use the "marshal" method in XMLService.

Procedure 16.3. To Convert XML to Models

XMLService provides methods for converting XML to model objects, a process known as "unmarshalling". For example, assume we have the following XML in a text file Enterprise.xml

    
s    
    
You can produce a model object from this XML as follows:
XMLService xmlService = Services.get(XMLService.class);
Enterprise enterprise = (Enterprise) xmlService.unmarshal(new FileInputStream("Enterprises.xml"));

You can also unmarshal a ModelList with the same technique:

XMLService xmlService = Services.get(XMLService.class);
ModelList<Enterprise> modelList = (ModelList<Enterprise>) xmlService.unmarshal(new FileInputStream("ModelList.xml"));