General Interface is an open source project hosted by the Dojo Foundation

Modifying Mapping Rules Files

Creating Mapping Rules Files Chapter 5 Communicating with Data Services Mapping GUI Components to Mapping Rules

The rules file is automatically created when the XML Mapping Utility first parses the source document(s). However, you can manually modify any individual rule to reflect structures not accurately reflected in the source documents.You can add rules, add mappings, delete rules, view sample messages, and so on.

There are several ways to modify the mapping rules file:

Working in the Rules Tree Panel

The rules tree in the Rules Tree panel reflects the structure and order of the information being transformed---inputs that are being created to send to a remote service and outputs that will be processed to update information in General Interface applications. The source documents used to generate the rules tree, which are typically WSDLs and Schemas, define the structure of the rules tree. However, requirements do change and some interactions simply don't involve WSDL/SOAP.

In these situations, the tools in the Rules Tree panel help you manage the structure and relationship for each rule, including reordering rules using drag-and-drop, adding new rules, cloning existing rules, and removing existing rules.

Reordering Rules

Because the rules tree is an execution tree, the order of the rules defines the order of execution. More specifically, the rules are traversed by depth and then breadth.

To reorder a rule, simply drag and drop it to a new location in the tree.

Adding Rules

To add a rule to the rules file, right-click a rule in the rules tree and choose Add New Rule. Then choose a command from the submenu, such as Element, Attribute, or CDATA. Once you've created a rule, you can modify the profile in the Rule Profile panel. See Working in the Rule Profile Panel.

Cloning Rules

It's also possible to clone any node in the rules tree, including its descendant content. To clone a rule, right-click a rule in the rules tree and choose Clone.

Deleting Rules

If you only need to work with some of the rules that were automatically generated when the source document(s) were parsed, you can delete the unnecessary rules to reduce the clutter in the Rules Tree panel. Reducing the rules in the tree also optimizes the rules file for the web as it only contains necessary rules. This optimized rules file is a key advantage to using the XML Mapping Utility instead of the more verbose WSDL file. Note that deleting rules doesn't affect the source document.

To delete a rule and all of its children from the rules tree, select the rule(s) you want to delete and choose Delete > Selected Rules.

To delete all unselected sibling rules from the rules tree, select the rule(s) you don't want to delete and choose Delete > Unselected Sibling Rules.

Use Ctrl+click or Shift+click to select multiple rules.

Regenerating Rules

The ability to reparse rules is helpful if you've deleted a rule by mistake or you want to remove the rule settings. Often, minor changes to the source WSDL can be handled by downloading a copy of the updated WSDL and replacing the local copy that you used to create the original rules file. Then, right-click the parent rule in the rules tree. Choose Reparse to re-parse from that rule down. When the Reparse Selected Branch dialog displays, click the Reparse button to reparse the rule. The rule is returned to its original state and all mappings are lost.

In some situations the reparse will fail. If that occurs, select the rule in the rules tree, choose the Rule Node Profile radio button, and write your own XPath in the Source Path field to recreate the binding between the rule in the rules tree and the Schema definition in the source document from which it originates.

For example, if you parse the default WSDL Address.wsdl, the ReturnCityState element maps to the Schema node at this address: 

//jsx3:schema[@targetNamespace='http://ws.cdyne.com/']//jsx3:element[@name='ReturnCityState']

The above address is brittle, because if an additional element is added to the Schema, it can corrupt the absolute addressing. In such a case, simply edit the XPath to use an XPath address that is less brittle. For example, 

//jsx3:element[@name='ReturnCityState']
When authoring your own XPath for a WSDL document, use the jsx1 prefix to point to any node in the source document belonging to the namespace, http://schemas.xmlsoap.org/wsdl/. Use jsx3 to resolve to the namespace, http://www.w3.org/2001/XMLSchema. For all other source document types (XHTML, Schema, XML, etc), the prefix is an incremented value (jsx1, jsx2, jsx3, etc) that reflects the order in which the namespace was first declared in the source document.

Adding Mappings

Rules that descend from input or output rules can be mapped to GUI components, as well as to CDF documents, records, and attributes. For example, you can map user input in a text field to a rule in your rules file and then send this data to a web service in the outgoing message. Incoming data from the web service can then be mapped to a CDF document, allowing the server's response to be displayed in the user interface.

There are several ways to add mappings:

For more information on mapping types, see Message Rules.

Detaching Mappings, Restrictions, and Headers

You can remove existing mappings, restrictions, and headers from a rule in the Rules Tree panel. This is useful if you've made an error or you want to reduce the size of your rules file.

To remove mappings from a rule, select one or more rules that have a mapping and choose Detach > Mappings. Rules that have mappings are indicated with a Mapping icon . Mappings are displayed in the Settings panel on the right.

To remove restrictions from a rule, select one or more rules that have restrictions and choose Detach > Restrictions. Rules that only have maxoccur and minoccur restrictions don't have an icon in the rules tree. Rules that have additional restrictions are indicated with a Restriction icon . Restrictions are displayed in the Settings panel on the right.

Use Ctrl+click or Shift+click to select multiple rules.

To remove HTTP headers from a rule, select an operation rule that has HTTP headers and choose Detach > Headers. HTTP headers are displayed in the Settings panel on the right.

Working in the Rule Profile Panel

After the physical structure of the rules tree is defined, you can use the Rule Profile panel to define attributes for a rule, such as the node name and target namespace.

To modify the rule profile in the rules tree, do the following:

  1. Select the rule you want to modify in the Rules Tree panel.
  2. Select the Rule Node Profile radio button below the Rules Tree panel.
  3. Click in the Value field next to the name you want to modify.
  4. Type in a value.
  5. Generate a test message to test the impact of changes to the rule profile. To generate a test message, right-click an input or output rule in the Rules Tree panel and choose Generate Sample Message.

For field definitions, see Rule Node Profile.

Working in the Settings Panel

The most significant step in the mapping process is to create the actual mappings for each rule. To add and remove mappings, use the Settings panel, which provides a unique set of settings appropriate to the type of rule. For example, operation rules allow you to define the endpoint URL where an outbound request will be sent. Some of the most common settings can be set using shortcut methods in the Rules Tree panel. For more information, see Adding Mappings and Detaching Mappings, Restrictions, and Headers.

The Settings panel only displays fields pertinent to the selected rule. These four types of rules display fields in the Settings panel:

  • Operation or transaction rules
  • Input rules
  • Output rules
  • Message rules

Modifying Operation Rules

When you select an operation rule in the Rules Tree panel, the Settings panel displays the fields Endpoint URL, Method, and HTTP Headers.

For more information on these fields, see Operation Rules.

Using the SCRIPT Transport Method for JSON

The default transport method for the XML Mapping Utility is POST. Other transport methods are supported, however, including a JSON-specific transport named SCRIPT.

When you use the SCRIPT method, the XML Mapping Utility uses a SCRIPT tag for the transport instead of the standard XMLHTTP control.

With the SCRIPT method, you can set an additional field to specify that the service uses JSONP (JSON with padding). When this field is set, the service class appends an additional parameter to the URL in the form 

callback={method}

where {method} is a temporary callback function managed by the Service instance.

This allows for flexibility when using JSON Services that are also available as JSONP Services---you can use the same endpoint URL, but implement different behaviors. If the given JSONP Service expects the name of the callback parameter to be something different than callback, use the runtime API call, setJSONP, to pass the parameter name that is expected by the given JSON Service.

For example, Yahoo! Pipes supports the parameter name "_callback" for its implementation of JSONP. Therefore, when calling Pipes, make sure to set the true name of the callback before sending the request: 

objService.setJSONP("_callback");
objService.doCall();

Note that the following two statements are equivalent, because the default JSONP name used by the system is " callback ": 

objService.setJSONP(true);
objService.setJSONP("callback");

You can also implement a callback of your own by directly modifying the endpoint URL to call the named function. In such situations, pass false to this method, so that the transport will not attempt any form of automated callback.

If you implement your own callback handlers, you must manually conclude the service call with a call to the Service method doRespond, by passing the JSON object returned from the Service back to the mapper.

Modifying Input Rules

Input rules, also known as requests, can be modified in the Settings panel. To modify input rules, select an Input (request) rule in the Rules Tree panel. The Settings panel displays the following fields: Stub URL, Stub Path, and onBeforeSend.


For more information on fields in the Settings panel, see Input Rules.

Stub URL

To enable the Stub URL field, click the Enable button next to the field.

The Stub URL field is typically used in conjunction with the Stub Path field to support SOAP-based web services. When SOAP is used, each request document is encapsulated by a SOAP Envelope. The XML Mapping Utility treats the Envelope as a static document into which the actual request is placed. For example, the default stub used by the XML Mapping Utility is as follows: 

<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Body>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This document is generic enough to encapsulate the majority of SOAP messages and it's recommended that you use it.

However, if this default document does not contain enough information, you can specify the URL for a static stub of your own. For example, you might also need to include a SOAP Header in addition to a SOAP Body element in the Envelope.

The Stub URL value can be updated at runtime using the API call, setOutboundStubURL. If more control is needed over the stub document and its structures, you can provide a parsed jsx3.xml.Document instance of your own by calling the setOutboundStubDocument() method.

Stub Path

When the stub document changes, it is often necessary to update the Stub Path to reflect the XPath address for the node in the Stub document to which the message will be appended. To enable the Stub Path field, click the Enable button next to the field.

Use the Stub Path field in conjunction with the Stub URL field. Type in a valid XSL query that describes where to place the generated document in the Stub document. For example, the following document is generated when the GetHistoricalQuotes operation is called in the WSDL Mapping 2 sample:

<jsx1:GetHistoricalQuotes>
<jsx1:Identifiers>ibm,yhoo,goog,tibx</jsx1:Identifiers>
<jsx1:IdentifierType>Symbol</jsx1:IdentifierType>
<jsx1:AsOfDate>3-21-06</jsx1:AsOfDate>
</jsx1:GetHistoricalQuotes>

The combination of the default Stub URL(GI_HOME_/GI_Builder/JSX/stubs/soap.xml) and Stub Path(/SOAP-ENV:Envelope/SOAP-ENV:Body) results in the following document being sent:

<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Body>
    <jsx1:GetHistoricalQuotes
    xmlns:jsx1="http://www.xignite.com/services/">
    <jsx1:Identifiers>ibm,yhoo,goog,tibx</jsx1:Identifiers>
    <jsx1:IdentifierType>Symbol</jsx1:IdentifierType>
    <jsx1:AsOfDate>3-21-06</jsx1:AsOfDate>
    </jsx1:GetHistoricalQuotes>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This value can be updated at runtime using the API call, setOutboundStubPath.

onBeforeSend

Enter one or more JavaScript statements in this field to execute immediately before the request message is sent. For example, if you want to output the XML request to the System Log before sending it, you enter the following statement, where the keyword, this, refers to the jsx3.net.Service instance: 

jsx3.log(this.getOutboundDocument().getXML());

Modifying Output Rules

Output rules, also known as responses, can be modified in the Settings panel. To modify output rules, select an Output (response) rule in the Rules Tree panel. The Settings panel displays the following fields: Stub URL and onAfter Receive.


For more information on fields in the Settings panel, see Output Rules.

Stub URL

The XML Mapping Utility provides a static mode that allows you to test against a typical service response. This is useful in situations where the service isn't built yet or is inaccessible. Use the Stub URL field to specify an XML document that contains a response for testing purposes.

To use the static mode feature, complete these steps:

  1. Save a valid XML document (the typical response) and enter the URL in the Stub URL field.
  2. Do one of the following to set the static mode:
    • Choose Project > Project Settings and change the Mode option on the Deployment panel of the Project Settings dialog from Live to Static, and refresh the browser to reload the project. See Deployment Panel.
    • Call setMode(0) on the jsx3.net.Service instance to make only that instance run in static mode while leaving the remainder of the project in live mode.

Now when transactions are run by a service, a request isn't sent. Instead the sample document is processed as if the remote service returned it.

This URL can also be set at runtime using the API call, setInboundURL.

onAfterReceive

JavaScript statements entered in the onAfterReceive field execute immediately after the response message is received and before the mappings are applied. This script executes in context of the Service instance. This means that the keyword, this, refers to the Service instance. For example, if you want to output the XML response to the System Log palette each time the service responds, you could write: jsx3.log(this.getInboundDocument().getXML());

onAfterReceive multiRef Example

Another example might be converting a multiRef format to a supported XML Mapping Utility format. This involves writing custom XSLT and running the XSLT on the incoming document to convert a multiRef formatted document to a concrete structure that the XML Mapping Utility understands. The custom XSLT might look similar to the following:

<?xml version="1.0" ?>
  <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:template match="/ | @* | node()">
<xsl:choose>
<xsl:when test="@href">
<xsl:apply-templates select="." mode="concretize"/>
</xsl:when>
<xsl:when test="local-name() != 'multiRef'">
<xsl:copy><xsl:apply-templates select="@*"/></xsl:copy>
</xsl:when>
</xsl:choose>
</xsl:template>

<xsl:template match="*" mode="concretize">
<xsl:param name="myId"><xsl:value-of select="@href"/></xsl:param>
<xsl:copy><xsl:apply-templates
   select="//*[@id=substring-after($myId,'#')]/*"/></xsl:copy>
</xsl:template>
</xsl:stylesheet>

To implement the above transformation, assume the above stylesheet is named multiRefConverter.xsl. You would enter the following code in the onAfterReceive field for your given operation:

/* get the document just returned from the service */
var myXML = this.getInboundDocument();

/* load the xslt that will convert the axis multiref structure to a more
   concrete/literal format */
var myXSL = (new jsx3.xml.XslDocument()).load("multiRefConverter.xsl");

/* transform xml to filter */
var newXML = myXSL.transformToObject(myXML);

/* replace the server's document with the new, transformed document */
this.setInboundDocument(newXML);

Modifying Message Rules

Message rules are rules that are included in the actual message structure and are identified by the following icons and types:

  • Element
  • Complex
  • Attribute
  • CData

When a message rule is selected in the Rules Tree panel, the Settings panel displays a Mappings table, a Restrictions table, and a Repeat When field.


For more information on fields in the Settings panel, see Message Rules.

Adding a Mapping to the Mappings Table

To add a mapping to the Mappings table, complete the following steps:

  1. Select a message rule in the Rules Tree panel to display the Mappings table in the Settings panel.
  2. Click the down arrow in a blank Type field of the Mappings table and select a type, such as DOM.
  3. Type a value in the Value field, if required. For example, if you selected DOM, type the component object name. A Mapping icon now displays next to the rule in the rules tree.

For more information on mapping types, see Mappings.

For more information on mapping GUI components, see Mapping GUI Components to Mapping Rules.

For information on mapping response data, see Mapping Response Data to CDF GUI Components.

Restrictions

When Schema or WSDL are used as the input, any restrictions in the input source file display in the Restrictions table of the Settings panel. Rules that have restrictions are indicated with a Restriction icon in the rules tree.

You can also add restrictions on a rule. For example, you might restrict user input to a five-digit number for a field that requires a zip code. To add a restriction:

  1. Select a message rule in the Rules Tree panel to display the Restrictions table in the Settings panel.
  2. Click the down arrow in a blank Type field of the Restrictions table and select a type, such as maxLength.
  3. Type a value in the Value field, such as 5. This would limit user input to a maximum of five characters.

For more information on restriction types, see Restrictions.

Repeat When

The Repeat When field is only applicable to outbound (input) messages. Enter one or more JavaScript statements in the Repeat When field. As long as this field evaluates to true, this specific rule is rerun.

The Repeat When field is typically used by mapping rules that convert a JavaScript array into an XML Node-set in the outgoing message. Conceptually, this feature is similar to a do-while loop, where execution will happen at least once and continue as long as the while (Repeat When) statement is true.

If your mapping rule was originally created from a source WSDL, you can easily identify message rules that are part of a collection by looking at the Restrictions table. The rule is a good candidate for using the Repeat When field if it declares a maxLength restriction with a value of unbounded, *, or greater than 1.

Example 1

For example, if you write a function similar to this:

window.iii= 1;
window.getNext = function() {
   window.iii = window.iii+1;
   return window.iii<=3;
}

and enter a call to the function in the Repeat When field for an addressToCheck rule in the WSDL Mapping 1 sample: 

window.getNext();

the JavaScript code iterates through the function three times and three records are added to the XML message for the rule. This sample message shows the three added records. 

<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Body>
   <jsx1:StandardizedAddress xmlns:jsx1="http://ws.cdyne.com/">
   *<jsx1:addressToCheck>???</jsx1:addressToCheck>*
   *<jsx1:addressToCheck>???</jsx1:addressToCheck>*
   *<jsx1:addressToCheck>???</jsx1:addressToCheck>*
   <jsx1:LicenseKey>
   <rule_node/>
   </jsx1:LicenseKey>
   </jsx1:StandardizedAddress>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example 2

Another example might be if you have an array of ids that you need to send to a server. You can include a Repeat When statement, so that the XML Mapping Utility knows how to iterate through this array. For example, the given web service might expect the following XML, where the id field repeats to contain as many ids as necessary:

<ids>
  <id/>
</ids>

A simple approach is to use the Array.shift() method on a Script mapping that you will bind to the id rule. For example, if you have a global array named myArray, the Script mapping for the id rule would look like this:

setValue( myArray.shift() );

Now, place the following in the Repeat When field.

myArray.length > 0

Because the shift method will remove the array element as soon as it is read, you can be certain that the XML Mapping Utility will only loop as many times as it has array elements. This results in only one node in the outgoing message for each item in the array:

<ids>
  <id>a</id>
  <id>b</id>
  <id>c</id>
</ids>

Also note that CDF mappings automatically repeat when necessary. For more information on CDF GUI components, see Mapping Response Data to CDF GUI Components.

Viewing Sample Messages

After you've modified your rules file, it's helpful to see the sample messages that are generated. This is a quick way to determine if your messages are written as you expect. You can view the default sample message or you can test the service and see the actual messages with the data.

To view a sample message, select an Input (request) rule or an Output (response) rule and choose Sample Message.

To test the service, see Testing Outbound and Inbound Messages.

Creating Mapping Rules Files Chapter 5 Communicating with Data Services Mapping GUI Components to Mapping Rules

Contents

Searching General Interface Docs

Expand all   Collapse all
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.