Request document structure

When the JSP presentation layer generates request documents, the tree of dynamic elements is generated directly by the URL parser, and the mandatory elements are generated by the component code on the JSP's using data from the URL parser as input.

The General format of request documents

The XML Gateway envelope

All requests to the XML gateway must be wrapped inside an envelope, identifying the invoking user, a unique request identifier and possibly some request parameters. An example is given below.

<idealXML version="2.0" id="UniqueID">
	<header>
		<credential>
			<login>admin@infor.com</login>
			<password>demo</password>
		</credential>
	</header>
	<commands>
		<command.../>
		<command.../>
		...
	</commands>
</idealXML>

The id attribute of the <idealxml> element enables the entire request document to be matched to its <idealxml> response document, which will also include this ID in its <idealxml> element. We recommend that the system that generates the request documents be programmed also to generate a unique ID for each request document.

XML root

The <idealXML> element is the root of the Infor e-Commerce Development Studio XML document structure; it contains all of the other elements.

<idealXML> has the following attributes:

  • version: specifies the version number of the Infor e-Commerce Development Studio XML revision used to format the request. For this release, this will always be equal to "1.0".

  • id: this should be set to a value that is unique for each document sent to the gateway. Usually, an automated system will be used to generate a new unique number for each document. The whole request is saved in the MEC log, which is valuable if the request fails. Though the gateway will still function without unique IDs for each request, we highly recommend that you establish a policy that requires all customers to supply them.

The following example illustrates the idealXML element:

<?xml version="1.0" encoding="UTF-8"?>
<idealXML version="2.0" id="unique number 123">
	...
</idealXML>
Note: All iXML 2.0 requests are validated against a schema, which can be found at:<MeC root>/e-Commerce/request.xsd

Header

The <header> element contains information for authentication. The <header> element is the same regardless of which <Request> element is contained in the document. The following example illustrates the <header> element:

<header>
	<credential>
		<login>xyz@ideal.com</login>
		<password>abc</password>
	</credential>
</header>

Within the <header> element must be nested a pair of <credential> tags, which frame the authentication information. The following elements must appear within the <credential> element:

  • <login>: identifies the user

  • <password>: authenticates the user

Infor e-Commerce Development Studio will process the incoming XML document as though it were a standard session with the specified user account all of the preferences, permissions and restrictions that normally apply to that account when accessing Infor e-Commerce Development Studio through the web interface.

Header

The <header> element contains information for authentication. The <header> element is the same regardless of which <Request> element is contained in the document. The following example illustrates the <header> element:

<header>
	<credential>
		<login>xyz@ideal.com</login>
		<password>abc</password>
	</credential>
</header>

Within the <header> element must be nested a pair of <credential> tags, which frame the authentication information. The following elements must appear within the <credential> element:

  • <login>: identifies the user

  • <password>: authenticates the user

Infor e-Commerce Development Studio will process the incoming XML document as though it were a standard session with the specified user account all of the preferences, permissions and restrictions that normally apply to that account when accessing Infor e-Commerce Development Studio through the web interface.

Command elements

Requests through the XML gateway may contain several commands that each invoke a method on a given business object. These commands are grouped inside a commands element.

<commands>
	<command name="ObjectName" method="Pipeline" id="UniqueID">
		<request.../>
		<request.../>
	</command>
	<command name="ObjectName" method="Pipeline">
		<request.../>
		<request.../>
	</command>
	…
</commands>

The id attribute of the <command> element, if present (it is optional), will be included in the response document to enable the response to each command to be matched to the relevant commands in the original request. We recommend that the system that generates the request documents be programmed also to generate a unique ID for each command.

Request elements

All iXML documents must have an outer element named "request". This element serves to group information for one method (pipeline) on one business object.

When executing requests from the XML gateway, the request elements are wrapped inside a command element, on which two attributes exist, telling which business object and which method (pipeline) is to be executed. The methods are defined in the business object model, each associated with a specific type, e.g. search, update, insert, commit, delete or custom, which specifies the operation that is to be performed.

<command name="RequestName" method="Pipeline">
	<request.../>
</command>

In general, the structure of each request is dependent on the structure of the business object on which the request operates. Within each request element there may be a set of mandatory and a set of and dynamic elements. Mandatory elements include keys and parameters and must be present for the request to be valid; dynamic elements are given as bindings or entity definitions and are not mandatory.

Search requests

A search request always includes one element named "search" inside the request element. If no dynamic behavior is needed, this is all that is needed to perform a search request.

<request>
	<search/>
</request>

The order in which the business objects are to be returned and the offset and limit can be defined as child elements to the search element. In the following example the products returned should be ordered by the "ProductName" attribute, in ascending order, and the first 10 products should be returned.

<request>
	<search>
		<paging offset="0" limit="10"/>
		<order priority="0" attribute="ProductName" direction="ascending"/>
	</search>
</request>

To limit the search from all business objects, it is possible to add an element named bindings. Inside the bindings element it is possible to add a number of search criteria on the attributes of the business object. In the example below, a product search is defined with the criteria that only the products in which the "Weight" attribute is equal (eq) to "100" should be returned. An overview of the possible operators can be found in the table below.

<request>
	<search>
		<bindings operator="or">
			<binding operator="and">
				<inding attribute="Weight" value="100" operator="eq"/>
			</binding>
		</bindings>
	</search>
</request>
operator value description
eq Equal to
lt Less than
le Less than or equal to
gt Greater than
ge Greater than or equal to
ne Not equal to
contains Contains
fulltextsearch Full-text indexing support
prefix Begins with
suffix Ends with
null Is null
ncontains Does not contain
nprefix Does not begin with
nsuffix Does not end with
nnull Is not null

The bindings elements can appear in any number of layers. The bottom layer must include a binding element with the binding itself.

With URLs, only the normal "and" driven bindings are possible using clauses, but manually written documents can use the whole functionality. The following example illustrates this:

<bindings operator="or">
	<bindings operator="and">
		<binding attribute="CurrencyID" value="USD" operator="eq"/>
		<binding attribute="Price" value="50" operator="le"/>
	</bindings>
	<bindings operator="and">
		<binding attribute="CurrencyID" value="DKK" operator="eq"/>
		<binding attribute="Price" value="500" operator="le"/>
	</bindings>
</bindings>

This gives the following logical expression:

(CurrencyID = "USD" AND Price <= 50) OR (CurrencyID = "DKK" AND Price <= 500)

Note: There are a set of rules for the binding element to work properly. The attribute value should also be an attribute of the business object. This attribute should be defined in the bindings section of business object model and should be a dynamic type in a dynamic group.

Subsets

Binding criteria, ordering and offset can also be defined on the subsets of the business object by adding a subset element under the business object element. The same criteria can be added as on the business object element, except for offset and limit. In the example below we have defined that we only want the products that have a price subset where the "Price" attribute is "le" (less or equal) to 50 and where the "currencyID" is equal to "USD".

<request>
	<search>
		<paging offset="0" limit="10"/>
		<order priority="0" attribute="ProductName" direction="ascending"/>
		<bindings>
			<bindings>
				<binding attribute="Weight" value="100" operator="eq"/>
				<binding attribute="Size" value="20" operator="ge"/>
			</bindings>
		</bindings>
		<subsets>
		<subset name="Price">
			<order priority="0" attribute="Price" direction="ascending"/>
			<bindings>
				<bindings>
					<binding attribute="CurrencyID" value="USD" operator="eq"/>
					<binding attribute="Price" value="50" operator="le"/>
				</bindings>
			</bindings>
		</subset>
	</subsets>
</search>
</request>

If a subset has subsets of its own, criteria can be added to these in the same manner recursively.

Mandatory parameters

To carry the attributes that have been defined as mandatory bindings in the model, a params element can be added under the request element. The params element may contain a number of param elements that each represent an attribute associated with an attribute value. This could, for example, be the language and the currency code of the current user. The params element may include both session values and non-session values. The number of param elements must be equal to the number of parameters defined in the model for the given pipeline. These values may be used to limit the search on both main set attributes as well as subset attributes.

<request>
	<params>
		<param name="LanguageCode">DK</param>
		<param name="CurrencyCode">DKK</param>
	</params>
	<search>
		<paging offset="0" limit="10"/>
		<order priority="0" attribute="ProductName" direction="ascending"/>
		<bindings/>
		<subsets>
			<subset name="Price">
				<bindings/>
			</subset>
		</subsets>
	</search>
</request>

The set of parameters necessary for each pipeline is derived from the business object model. If a pipeline requires some parameters from the session, these must be extracted from the session on the web server and added to the XML document before it is sent to the application layer.

URL mapping

In general, the bindings are generated directly from @where elements in the URL; @sort and @start are expressed as attributes on the search element. In the subset example above, the equivalent URL is

@where.Weight=100&@where.Size@op.ge=20&@where.Price:CurrencyID=USD& @where.Price:Price@op.le=50&@start=0&@maxrecords=10

Insert requests

An insert request may contain several business object entities to be inserted. Each entity is represented inside an entity element and these are grouped inside an element named entities, which is a child to the request element. An insert request may also contain mandatory parameters in a params element like the search request (usually session values). These parameters are common to all entities.

<request>
	<params>
		<param name="LanguageCode">DKK</param>
	</params>
	<entities>
		<entity/>
		<entity/>
		...
	</entities>
</request>

Each entity element must contain several parameters, as defined in the model for the given method on the given business object. The parameters are grouped according to their business object structure, e.g. the parameters for a subset must be placed in a sub element with the name of the given subset. Below is an example of a request that inserts a product that includes an attributes subset.

<request>
	<params>
		<param name="LanguageCode">DKK</param>
	</params>
	<entities>
		<entity>
			<attributes>
				<attribute name="ModularQty">500</ttribute>
				<attribute name="MinimumQty">600</attribute>
				<attribute name="ProductID">CS-8565</attribute>
			</attributes>
			<subsets>
				<subset name="Attributes">
					<attributes>
						<attribute name="Mandatory">Y</attribute>
						<attribute name="AttributeID">cs-monitor</attribute>
					</attributes>
				</subset>
			</subsets>
		</entity>
	</entities>
</request>

URL mapping

Basically, each entity element corresponds to one key value, and each @field element maps into an attribute element. The URL corresponding to the request above is:

@field.ModularQty=500&@field.MinimumQty=600& @field.ProductID=CS-8565&@field.Attributes:Mandatory=Y& @field.Attributes:AttributeID=cs-monitor

A key may be specified in order to join @field elements in entities. When doing an insertion the value of the key must begin with +, and it does not need to be included in the request document.

Update requests

Update request have the same structure as insert requests, except that a number of keys (usually one) must be provided for each subset (including the main set). The keys are used to identify which subset is to be updated with the values provided in the parameter elements. Which keys must be provided is defined in the model. In the example below, we update the Product that have a ProductID with the value "288ATX" and the Price subset associated with that Product which have a CurrencyID attribute equal to "USD".

<request>
	<params>
		<param name="LanguageCode">DK</param>
		<param name="CurrencyCode">DKK</param>
	</params>
	<entities>
		<entity>
			<keys>
				<key name="ProductID" value="288ATX"/>
			</keys>
			<attributes>
				<attribute name="Weight">2.2</attribute>
				<attribute name="Name">Test</attribute>
			</attributes>
			<subsets>
				<subset name="Price">
					<keys>
						<key name="CurrencyID" value="USD"/>
					</keys>
					<attributes>
						<attribute name="Price">100</attribute>
					</attributes>
				</subset>
			</subsets>
		</ntity>
	</entities>
</request>

When updating a business object, it does not necessarily mean that all subsets must be updated as well. It is possible to update a business object while inserting a new subset. This is done by omitting the keys element for the appropriate subset—of course it must be defined in the model that this is how the given method is to be invoked. In the example below, we update a product and add a new price subset.

<request>
	<params>
		<param name="LanguageCode">DK</param>
		<param name="CurrencyCode">DKK</param>
	</params>
	<entities>
		<entity>
			<keys>
				<key name="ProductID" value="288ATX"/>
			</keys>
			<attributes>
				<attribute name="Weight">2.2</attribute>
				<attribute name="Name">Test</attribute>
			</attributes>
			<subsets>
				<subset name="Price">
					<attributes>
						<attribute name="CurrencyID">USD</attribute>
						<attribute name="Price">100</attribute>
					</attributes>
				</subset>
			</subsets>
		</entity>
	</entities>
</request>

A special case of the update request contains no keys. This is used when the selection of business objects to be updated it is defined by static bindings.

<request>
	<entities>
		<entity>
			<attributes>
				<attribute name="Weight">2.2</attribute>
				<attribute name="Name">Test</attribute>
			</attributes>
		</entity>
	</entities>
</request>

It is even possible to submit a request without parameters. Then it is entirely defined in the model what operations are performed by the request (no dynamic behavior).

<request>
	<entities>
		<entity/>
	</entities>
</request>

URL mapping

The first example above, where the subset is also updated, corresponds to the URL:

@field.Weight@key.%3D288ATX=2.2&@field.Name@key.%3D288ATX=Test& @field.Price:Price@key.%3D288ATX%3DUSD=100

The "=" character is encoded as %3D and the "+" character is encoded as %2B. In order to perform a combined main set update and subset create as in the second example, the key for the subset must begin with the + character:

@field.Weight@key.%3D288ATX=2.2&@field.Name@key.%3D288ATX=Test& @field.Price:Price@key.%3D288ATX%2BUSD=100

Commit requests

A commit request is a combination of an insert request and an update request. A commit request may contain both insert and update entities. If an entity has a "keys" element it is an update, else it is an insert. In the example below, two entities exist. The first one updates a product, while the latter one inserts a new product.

<request>
	<entities>
		<entity>
			<keys>
				<key name="ProductID" value="288ATX"/>
			</keys>
			<attributes>
				<attribute name="Weight">2.2</attribute>
				<attribute name="Name">Test</attribute>
			</attributes>
		</entity>
		<entity>
			<attributes>
				<attribute name="ModularQty">500</attribute>
				<attribute name="MinimumQty">600</attribute>
				<attribute name="ProductID">CS-8565</attribute>
			</attributes>
		</entity>
	</entities>
</request>

Delete requests

Delete requests have the same structure as update requests. Delete requests have no subsets though, as all parameters are taken as input to one stored procedure (like search requests). It is defined in the model which parameters a given request must take. Below is an example of a delete request that deletes a product.

<request>
	<delete>
		<keys>
			<key name="ProductID" value="TestProduct"/>
		</keys>
	</delete>
</request>

When deleting subsets, the parameters are represented in a hierarchical structure like the business object model. Below is an example of a delete request that deletes a price subset on a product (the attribute PriceID identifies the subset that is to be deleted on the product identified by the ProductID).

<request>
	<delete>
		<keys>
			<key name="ProductID" value="TestProduct"/>
		</keys>
		<dsubsets>
			<dsubset name="Price">
				<keys>
					<key name="PriceID" value="gold"/>
				</eys>
			</dsubset>
		</subsets>
	</delete>
</request>

As with update requests, a request without dynamic parameters can be used. Then it is defined statically in the model which operations should be performed by the request.

<request>
	<delete/>
</request>

URL mapping

The URL syntax for specifying deletions on subsets can only be done using @field elements to point out the subset. The second request above becomes:

@delete.TestProduct=&@field.Price:PriceID@key.gold=

Custom requests

Custom requests may contain any XML inside the request element. It is the developer of the stage that is to use the XML that decides this.