XML SChemas

To generate reliable reports in Activator, it is essential to clearly structure the data to be used. Without a defined model, the risk of errors and inconsistencies increases. The XML Schemas component meets this need by allowing you to define, via XML schemas, the exact structure of the data expected by reports.

 

Creation

In Activator Admin, XML Schemas are located within the menu container, among the items listed under 📈Reporting. As shown at (1) on the image below.

✋NB: Make sure you are in the System Component main module.

 

XML1.png
After initiating the creation of the XML Schemas, by clicking on the +Add new button (illustrated at (2) on the image above), you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields

🔬After filling in the name and description fields, let's focus on the Definition and Meta Data fields. 

The Meta Data field gathers and provides additional information for the component, please refer to  Meta Data for the complete list of additional information related to this component.

As for the Definition field, let's take a closer look at its XML content in the next point.

 

Definition

<?xml version="1.0" encoding="utf-8" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  
</xs:schema>

 

Description

This schema is currently empty, meaning that no data structures have yet been defined; it serves as a starting point for creating element definitions, of simple or complex types, for validating XML files.

 

Building The XML Schema For The Report Model

First of all, we need to create and name the parent element that will contain our entire object.

<?xml version="1.0" encoding="UTF-8" ?>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
        <xs:element name="reportName">
            <!-- Le contenu de l'objet ici-->

        </xs:element>
    </xs:schema>

 

Add An Element

<?xml version="1.0" encoding="UTF-8" ?>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
        <xs:element name="memberInfo">
            <xs:complexType>
                <xs:sequence>
                    <xs:element name="lastname" type="xs:string" /> <!-- Last Name -->
                    <xs:element name="firstname" type="xs:string" /> <!-- First Name -->
                </xs:sequence>
            </xs:complexType>
        </xs:element>
    </xs:schema>

This XML schema defines an element named memberInfo, which contains a structure made up of two sub-elements: lastname and firstname, both of which are of string type (xs:string). This schema can therefore be used to validate an XML file containing information on a member, with a surname followed by a first name.

Here is a JSON example corresponding to the structure defined by the XML schema (with a single memberInfo object containing lastname and firstname):

{
  "memberInfo": {
    "lastname": "John",
    "firstname": "Doe"
  }
}

 

Add An Object

<?xml version="1.0" encoding="UTF-8" ?>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
        <xs:element name="membersList">
            <xs:complexType>
                <xs:sequence>
                    <xs:element name="localization"> <!-- Object Name -->
                        <xs:complexType>
                            <xs:sequence>
                                <xs:element name="region" type="xs:string" /> <!-- Object Element 1 -->
                                <xs:element name="city" type="xs:string" /> <!-- Object Element 2 -->
                            </xs:sequence>
                        </xs:complexType>
                    </xs:element>
                </xs:sequence>
            </xs:complexType>
        </xs:element>
    </xs:schema>

This XML schema defines a main element called membersList, which contains a sub-element called localization. The latter is defined as a complex object (thanks to xs:complexType) containing in turn two sub-elements: region and city, both of type xs:string. The use of the <xs:sequence> tag imposes an order of appearance for the elements: region must appear before city. This schema can therefore be used to validate an XML file describing a list of members, each associated with a structured location comprising a region and a city.

Here is a JSON example corresponding to the structure defined by the XML schema (with a localization object containing region and city):

{
  "membersList": {
    "localization": {
      "region": "Littoral",
      "city": "Douala"
    }
  }
}

 

Add A List

<?xml version="1.0" encoding="UTF-8" ?>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
        <xs:element name="membersList">
            <xs:complexType>
                <xs:sequence>
                    <xs:element name="list" maxOccurs="unbounded"> <!-- Objects List: materialized by the presence of `maxOccurs="unbounded"` attribute -->
                        <xs:complexType>
                            <xs:sequence>
                                <xs:element name="lastname" type="xs:string" />
                                <xs:element name="firstname" type="xs:string" />
                            </xs:sequence>
                        </xs:complexType>
                    </xs:element>
                </xs:sequence>
            </xs:complexType>
        </xs:element>
    </xs:schema>

This XML schema defines a main element named membersList, which contains a list(array) of objects represented by the list element. The maxOccurs=“unbounded” attribute on this element indicates the difference between an object and an array(list). Each list(object) element corresponds to a member, described by two sub-elements: lastname and firstname, both of type xs:string. This makes it possible to structure collections of members in an XML file, ensuring that each member respects this structure.

Here is a JSON example corresponding to the structure defined by the XML schema (with a list of members containing lastname and firstname):

{
  "membersList": {
    "list": [
      {
        "lastname": "Smith",
        "firstname": "John"
      },
      {
        "lastname": "Charles",
        "firstname": "Kamdem"
      },
      {
        "lastname": "Lucie",
        "firstname": "Sine"
      }
    ]
  }
}

 

Diagram Representation In A Report

 

Conclusion

In short, XML Schemas allow you to precisely structure and validate the data used in Activator, be it simple elements, nested objects or lists of objects. Thanks to these definitions, data is better organized, easier to understand and ready for consistent use. This structuring is essential to guarantee the reliability of the information transmitted to reports, as the latter rely directly on the data model defined by XML schemas to generate clear, dynamic reports. Let's now look at how this data is used in reports.