Bookshelf v7.7: XML User Data

This section gives a summary of the most common XML tags returned to the third-party application following a request for user data to SWE. The user data is returned as an XML document.

In the Siebel database, data is contained in applets, which are contained within views, and views in turn are contained in screens. Make an XML request to the SWE to access data in the Siebel database. If you want to retrieve only data, set the parameter SWEDataOnly to TRUE. By using this flag, you can make sure the XML document contains only data tags and does not contain any user interface navigation elements such as drop-down menus, page tabs, and so on.

XML Page Content

In order to support different implementations, the Siebel Mobile Connector defines user interfaces and user data in the XML format.

In response to the XML requests of third-party applications, the Siebel Mobile Connector returns XML pages as output. The XML page output is based on the application definitions, including application, screen, view, applet and controls, that are defined in a repository. The output can be tailored to the application by including only data specified during configuration by applying XSL style sheets generated by the Siebel Mobile Connector for this purpose.


Section	Required or Optional	Description
XML version and encoding	Required	Describes the version of XML supported and the type of encoding used. Appended in all XML pages.
Application	Required	Describes the application name, such as the Siebel Mobile Connector or the Siebel Sales Enterprise, that the third-party application is connected to and interacting with. Appended in all XML pages.
User agent markup	Required	Describes the default markup language that is supported. It is based on the user-agent in the HTTP request header.
Navigation elements	Optional	Contains the following user interface information (the UI is defined in Siebel Tools): Menu, Tool bar, Screen bar, Thread bar, and Page item. The information under this tag can be turned off by specifying SWEDataOnly=TRUE in the HTTP request.
Form definitions	Optional	Contains the user interface for predefined queries (the UI is defined in Siebel Tools). Like the navigation elements, this information is generated by default. The information under this tag can be turned off by specifying SWEDataOnly=TRUE in the HTTP request.
Active Screen, View and Applets definition and User Data	Optional	Contains the current active screen and view information, applets, and the record (user data) defined in that view. Some UI elements are contained in this section that will not be included in data only mode. This section is generated by default. Specify SWEDataOnly=TRUE in the HTTP request to return only this information.

Common XML Tags

Table 2 provides a list of common XML tags returned in user XML documents and their attributes.

Table 2. Common XML Tags and Attributes
XML Element	Description
APPLICATION	Specifies the name of the application. For example, <APPLICATION NAME="Siebel Mobile Connector"> where APPLICATION is the tag, NAME is its attribute and the Siebel Mobile Connector is the value of NAME attribute.
USER_AGENT	Specifies information about the user agent or the browser type that made the XML or HTML request.
SCREEN	Specifies information about the name and title for the currently active screen. Contained inside the APPLICATION element.
VIEW	Describes the name and title of the currently active view (similar to the SCREEN element).
APPLET	Returns additional information in addition to the name and title of the applet. Contained inside the VIEW element.
MODE	Describes what mode the applet is in. Possible values include EDIT or BASE. EDIT specifies that the applet allows modification, deletion, creation and querying of records. BASE specifies that the applet is read only and cannot be modified.
NO_INSERT, NO_MERGE, NO_DELETE, NO_UPDATE, NO_EXEC_QUERY	Provides a filter to what specific edit mode operations are possible for the applet. If any of these attributes are TRUE, then that particular operation is not possible. For example, if NO_INSERT attribute is TRUE then new records cannot be inserted into the applet. The third-party application can customize the associated commands based on these attributes. For example, if the NO_EXEC_QUERY attribute is set to FALSE for an applet, this indicates that the third-party application should be able to query for a contact using that applet.
CLASS	Specifies the C++ class the applet belongs to. For example, in the first sample in this section, the CLASS attribute has a value of CSSFrameListBase, which means it is a List applet. The second sample has a CLASS value of CSSFrameBase, which means it is a Form applet.
ROW_COUNTER	Gives an indication of the number of data records returned. A plus sign (+) at the end indicates that there are more records than that returned.
RS_HEADER	Contains the COLUMN element.
COLUMN	Specifies the column details for the data records.
NAME, DISPLAY_NAME, TEXT_LENGTH	Specifies information about the name, title and text length of the columns respectively.
DATATYPE	Describes what kind of data type the column represents. For example, the phone number has a data type of phone and an email has a data type of email. This information could be used by the third-party application to make a call or send an email.
REQUIRED	Specifies whether or not the column is required. This information is useful when creating new records. The third-party application can determine what field information is mandatory by looking at this attribute.
FORMAT	Specifies the format of the data. For the Date data type this attribute should contain the acceptable Date Format (refer to the following sample). For revenue and other price related fields this attribute will have the format for the dollar amount. The third-party application can use this to get or display the right information back to the user.
CALCULATED	Specifies that the column has been calculated, for example, by using mathematical expressions. The column has not been directly derived from the database tables. This information could be useful during record creation.
FIELD	Specifies the name of the FIELD element in the business component that the column refers to. The FIELD element contains the actual data. The third-party application would make use of both FIELD and COLUMN elements to get more information on the data. FIELD is useful in determining what fields to query on while fetching a particular record.
READ_ONLY, LIST_EDITABLE	Specifies whether the column is editable or just read only. This information could be useful to the third-party application when modifying certain columns.
NUMBER_BASE, TEXT_BASED	Indicates whether the column or field is a number or text.
RS_DATA	Contains the XML tags that hold the actual data.
ROW	Identifies the row id of the data in the attribute ROW_ID. This information is very useful in querying for a particular row of data and getting the detailed information for that row.
SELECTED	Indicates that the particular row is selected on the user interface.

Retrieving Data Only

If SWEDataOnly is set to TRUE, all elements contained within both the NAVIGATION_ELEMENTS tag and the FORM tag will not be returned. For example, this code fragment represents an XML document where SWEDataOnly is set to FALSE:

In contrast, this code fragment represents an XML document where SWEDataOnly is set to TRUE:

Retrieving Detailed Information About the Data

The RS_HEADER section holds detailed information about each data column. For instance, if the third-party application wants to detect if a particular column holds a phone number, then it should lookup the DATATYPE attribute in the COLUMN element (under the RS_HEADER section) and then get the data from the FIELD element. The FIELD attribute of the COLUMN element gives a link to the FIELD element, which holds the actual data.

NOTE: Using the field attributes in the RS_DATA section for data type detection is not recommended, because this information is not guaranteed to be a constant. The RS_DATA might change if the object definition, field names in this case, are changed in Siebel Tools.