Developer

XML via HTTP Step Response Mapping

An XML Response mapping is a child definition to the XML via HTTP step definition, defined to extract data returned by the parent step and map it to the property values or other data members of the application. Data returned may be extracted by the mapping when that takes the form of a Cookie, HTTP Header, or XML. The value extracted may be assigned to the properties of the definition for which the step was defined, or to one of several other data values within the application.

The response mapping defines both the source type, or “Mapping Type,” of the data returned by the step definition, and the data component of the mobile application where the value is stored. If the mapping type is an XPath Expression or XSL Transformation, the return data must be structured XML. Included in the response mapping then is the XPath or XSL to extract the data from the XML document received by the step after its request was submitted.

Once the data is extracted by the response mapping definition it is assigned to the data component of the mobile application as specified within the mapping definition. This can include a property within the definition for which the parent step was defined, as well as messaging, user ID, the creation of local and local XML data tags, the parent object’s key property, or the value may be used for validation.

A given XML via HTTP step can contain multiple response mappings. Each will extract data from the same data set returned by the step to the Agentry Server. The parent step definition’s property view contains a list of all response mappings. The order in which the mappings are processed is the position in which the mappings are listed in this view. This order can be modified by moving the mappings up or down within the list.

Response Mapping Attributes

  • Mapping Type: This attribute specifies the type of data from which the value will be extracted for the response mapping. This may be one of Cookie, HTTP Header, XPath Expression, or XSL transformation. If XPath or XSL is selected, the return set from the step is assumed to be an XML document. This requires the definition of the Base XPath and XPath, or XSL attributes to specify which components of the XML document are to be extracted.
  • Name: Contains the unique internal name for the response mapping. This value must be unique among all response mappings within the same parent step. The label for this attribute field in the Editor will change based on the selected Mapping Type.
  • Base XPath: This attribute is enabled when the Mapping Type attribute is set to either XPath Expression or XSL Transformation. The Base XPath is set to locate an element within the XML Document that contains one or more child elements of the same type. The XPath attribute then specifies the specific child element type within the element specified by the Base XPath. The response mapping will iterate over all instances of the child element, extracting the value of each and assigning to the value specified in the mapping attributes. This is most commonly used when synchronizing data object instances within a collection property.
  • XPath: This attribute contains the XPath expression for the specific element within the XML Document whose contents are to be extracted by the response mapping. This expression is used in combination with the Base XPath (if specified) to provide iterative processing of multiple instances of the same element within the same parent element within the document.
  • XSL:
  • Maps To:
    • Error Message: This selection will map the data to error text display by the mobile application.
    • Last Update: This selection specifies the extracted value is a date and time indicating when the data table’s source in the back end system was last modified. This value is compared against the internal last update value for the data table as provided by the Client.
    • Local String (<<local>>): This selection will create a local data tag available to subsequent data mappings in the same parent HTTP Request. The value of this data tag will the value extracted by the response mapping. When selected, the attribute String Name will be available to name the local data tag created. This is the equivalent to calling the SDML function tag <<local ...>>.
    • Local XML (<<localXML>>): This selection will create a local XML data tag available to subsequent data mappings in the same parent HTTP Request. The value of this data tag will be the value extracted by the response mapping.
    • Notification [Cancel] Button Label: This selection specifies that the value extracted by the response mapping should be used to label the cancel button displayed in the Notification Dialog displayed by push definitions. If the step is used in any other manner than push processing, this selection will have no effect.
    • Notification [OK] Button Label: This selection specifies that the value extracted by the response mapping should be used to label the OK button displayed in the Notification Dialog displayed by push definitions. If the step is used in any other manner than for push processing, this selection will have no effect.
    • Notification Text: This selection specifies that the value extracted by the response mapping should be used as the message text displayed in the Notification Dialog displayed by push definitions. If the step is used in any other manner than for push processing, this selection will have no effect.
    • Notification Title: This selection specifies that the value extracted by the response mapping should be used as the title bar text of the Notification Dialog displayed by push definitions. If the step is used in any other manner than for push processing, this selecting will have no effect.
    • Parent Object Key Property: This selection specifies that value extracted by the response mapping should be matched with the key property of the parent object to the object being synchronized. This is primarily used in fetches and object read steps, where the data for a nested collection is being retrieved. When this option is selected, the Key Property attribute will be enabled to allow for the selection of the parent key property to match with the value.
    • Property Path: This selection specifies that value extracted by the mapping is assigned to a property within the object definition for which the step has been defined. This selection has no meaning for steps defined for fetch definitions. For steps defined for transactions this option is selected when the parent step is expected to return the key property of the object targeted by the transaction. This is only the case when the transaction step usage definition defines a client response of Update Client Key Property.
    • User ID: This selection will map the value extracted by the response mapping to the user’s ID. This value is the equivalent to the SDML data tag <<user.id>>. If a previous response mapping in any HTTP Request processed by the Server set the user ID, setting it here will override that value. This will then be the value available for all HTTP-XML system connection processing where the data tag <<user.id>> is referenced.
    • Validation: This selection allows for validation within of the user during the request made by the step. When the validation item is selected, the XPath defined for the step must successfully locate and XML element. The failure to locate the element is treated as failed validation.
  • String Name: This attribute is enabled when the Maps To attribute is set to “Local String (<<local>>).” This attribute contains the name of the local data tag to be created. This name can be set to any character consisting of alphanumeric characters.
  • XML Name: This attribute is enabled when the Maps To attribute is set to “Local XML (<<localXML>>).” This attribute contains the name of the local XML data tag to be created. This name can set to any string consisting of alphanumeric characters.
  • Key Property: This attribute is enabled when the Maps To attribute is set to “Parent Object Key Property.” The Key Property attribute is set to the key property of an object that is an ancestor to the object being synchronized.
  • Property: This attribute is enabled when the Maps To attribute is set to “Property Path.” The Property attribute is set to the property whose value will be set to the one extracted by the parent step definition. The property selected here should be defined within the definition for which the parent step was defined