Bookshelf v7.7: XML Command Block

Siebel Portal Framework Guide > Delivering Content to External Web Applications > XML Request Structure >

XML Command Block

To initiate an action on a Siebel eBusiness XML screen, you must use a specific set of XML tags and they must conform to a specific structure. Table 10 lists the three valid XML tags that are used to perform a command.

Table 10. XML Tags
Tag	Description
<EXEC>	The root tag for each command that you want to send to the SWE. The <EXEC> tag encloses the <CMD> and <ARG> tags. This tag represents a single command.
<CMD>	This tag indicates the SWE command that you want to access and encloses all arguments for the command.
<ARG>	This tag indicates the object on which the command is to be executed and any additional parameters that are required. Unlike the <EXEC> and <CMD> tags, which are used only once in a command block, you can have multiple arguments within a command block.

For example, using the information from Table 10, a valid syntax format for an XML command block is as follows:

<EXEC>

<ARG NAME="argumentName">argument1Value</ARG>

<ARG NAME="argumentName">argument2Value</ARG>

...

<ARG NAME="argumentName">argumentNValue</ARG>

<ARG NAME="SWEDataOnly"> TRUE | FALSE </ARG>

</CMD>

</EXEC>

Each <EXEC> tag encloses a complete command block. The <CMD> and <ARG> tags are enclosed within the <EXEC> tag, and their attributes and values specify which commands are executed by the SWE.

A valid XML command block must conform to a specific structure. It must have a valid execute tag followed by a command tag that encloses the arguments. The syntax of the name-value pairs and the attributes that accompany the XML tags within a command block must follow a specific format. This section details the syntax of each XML tag. For the DTD for the inbound XML document, see Inbound DTD.

EXE Tag

The Execute tag is the root tag for each command that you want to execute.

Description

Think of the Execute tag as a container. Each container represents a single SWE command or screen action. Enclosed within an Execute tag are the commands, arguments, and information required to complete a single command. There should be only one <EXEC> tag for each command that you want to execute. The PATH attribute is the only attribute used by the <EXEC> tag, although it is not required.

Attributes

Table 11 lists the attributes used with the Execute tag:

Table 11. EXEC Tag Attributes
Attribute	Description
PATH	The PATH attribute is used to indicate the location of the SWE object manager. By default, the eBusinessSWEXML application looks in its root directory for the SWE object manager. If you want to specify an object manager for the Web application to use, you must indicate its location using the PATH attribute.

Example

The following example uses the Execute tag to enclose the login command.

<?xml version="1.0" encoding="UTF-8"?>

<ARG NAME="SWEPassword">jdoepassword</ARG>

</CMD>

</EXEC>

CMD Tag

The Command tag is required for each command block and is used to indicate the SWE command that you want to execute.

Description

Like the Execute tag, the Command tag also acts as a container. Enclosed between the open and close Command tags are the arguments required to complete a command. There should be only one <CMD> tag for each command block that you want to execute.

Attributes

Table 12 lists the attributes that are used with the Command tag:

Table 12. CMD Tag Attributes
Attribute	Description
NAME	The NAME attribute should always be set to "SWECmd". This indicates that the type of command you want to execute is a SWE command.
VALUE	The VALUE attribute specifies which SWECmd you want to execute. Listed below are the SWE commands most commonly used with eBusiness: n ExecuteLogin n GotoPageTab n InvokeMethod n LogOff

Example

Using the information from the table above, the following example illustrates how to use the Command tag to execute a login command:

<?xml version="1.0" encoding="UTF-8"?>

<ARG NAME="SWEPassword">jdoepassword</ARG>

</CMD>

</EXEC>

ARG Tag

A command block can contain multiple Argument tags. Each Argument tag indicates an additional command parameter required to complete the action specified in the command block.

Description

The Argument tag uses name/value pairs to send command parameters to the SWE. A command will not execute without having all the appropriate parameters passed to the SWE.

Attributes

Table 13 lists the attributes that are used with the Argument tag.

Table 13. ARG Tag Attributes
Attribute	Description
NAME	This is the only attribute used by the Argument tag. The NAME attribute is used to indicate an argument, or the name of a parameter, for which you are sending additional information. The parameter's value is entered between the open and close Argument tags. Listed below are the parameter names most commonly used with eBusiness: n SWEApplet n SWEDataOnly n SWEMethod n SWEPassword n SWEScreen n SWESetNoTempl n SWESetMarkup n SWESetRowCount n SWEStyleSheet n SWEUserName n SWEView Table 14 lists the values that are most commonly used with these parameter names.

Example

For each argument name that you include in a command block, you must also indicate a value for the argument. For example, to use the InvokeMethod command, you must indicate which method you want to invoke. Additionally, if the method is one that requires parameters, as is the case with the WriteRecord, you must send those parameters to the SWE. With the WriteRecord method, you need to indicate the view and the applet you are working with. You also need to indicate the column to which you want to write the record, and finally you need to indicate what information you want to write. The following example illustrates how to use Argument tags to send the required parameters for a WriteRecord method:

<?xml version="1.0" encoding="UTF-8"?>

<ARG NAME="SWEMethod">WriteRecord</ARG>

<ARG NAME="SWEView">Account List View</ARG>

<ARG NAME="SWEApplet">Account List Applet</ARG>

<ARG NAME="Lot Name">65 metal car</ARG>

</CMD>

</EXEC>hr

Required Arguments

The following three arguments are required for each command block sent to the SWE:

<ARG NAME="SWEDataOnly">TRUE | FALSE</ARG>

SWESetMarkup. The SWE returns a response for each command block it receives. You can use the SWESetMarkup attribute to indicate whether a response is returned as XML, HTML, or WML.
You can also set the response markup format by allowing the User Agent (UA) service to retrieve the default markup from the UA device table, or by setting the SWESetMarkup property in the appropriate Siebel Server configuration file. The SWESetMarkup tag is not required in the payload when you use one of these alternatives.

NOTE: The examples in this chapter specify the response markup format using the SWESetMarkup attribute in the payload.
SWEDataOnly. In addition to specifying the type of markup language for a SWE response, you must also indicate whether the response should include data only or data and user interface information, such as non-data controls (anchors and navigation controls). You can set the SWEDataOnly attribute to TRUE to indicate that only data should be returned, or you can set it to FALSE to indicate that both data and user interface information should be returned.
NOTE: If the SWEDataOnly parameter is not included, the default is FALSE.
SWESetNoTempl. By default, Siebel eBusiness XML uses a server-side Web template to filter specific items and controls from SWE responses. When using XML, you can control whether a response will return all the information related to the request or a subset of it dictated by the Web template. Setting the attribute to TRUE makes sure that the Web template is not used and that the SWE response contains all the necessary information to complete an action. When a SWESetNoTempl attribute is set to FALSE, the Web template is used and the page items and controls specified in the template are filtered from the response.
NOTE: If the SWESetNoTempl parameter is not included, the default is FALSE.

Common Name-Value Pairs

Table 14 lists commonly used argument name-value pairs.

Table 14. ARG Parameter Name-Values Pairs
Parameter Name	Parameter Values
SWEApplet	`Applet name`
SWEDataOnly	TRUE FALSE
SWEMethod	n DeleteRecord n EditRecord n ExecuteQuery n GoToNextSet n GotoPageTab n NewRecord n NewQuery n WriteRecord
SWEPassword	`Password`
SWEScreen	`Screen name`
SWESetMarkup	HTML XML
SWEUserName	`User name`
SWEView	`View name`

NOTE: When determining what arguments to define, it is a good idea to look at the XML Response. The response will include what arguments are expected.

Siebel Portal Framework Guide