XML Results
Many of the netFORUM xWeb web methods have a response that returns XML, particularly web methods that return a list of records. We will call these "get" methods since their purpose is to get data. The type of the return is a complexType with an any sequence indicator.
In many (but not all cases), the XML returned will be in a similar structure containing an outer node called Results with repeating inner node(s) called Result, only with different element names depending on the type of data returned.
The XML response is based on the XmlNode class in Microsoft Visual Studio .NET.
Although the elements returned by each method are different, we will call this "type" generically by the name XML Results.
Response
In many cases, "get" web methods that return a list of zero, one or more elements in response to a request, will be in a structure like this:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<AuthorizationToken xmlns="http://www.avectra.com/2005/">
<Token>5f9bcd8c-0b95-4ac0-9a3b-5b6290843d97</Token>
</AuthorizationToken>
</soap:Header>
<soap:Body>
<MethodNameResponse xmlns="http://www.avectra.com/2005/">
<MethodNameResult>
<Results recordReturn="2">
<Result>
<zzz_field1>value</zzz_field1>
<zzz_field2>another value</zzz_field2>
<zzz_field3>yet another value</zzz_field3>
</Result>
<Result>
<zzz_field1>value2</zzz_field1>
<zzz_field2>another value2</zzz_field2>
<zzz_field3>yet another value2</zzz_field3>
</Result>
</Results>
</MethodNameResult>
</MethodNameResponse >
</soap:Body>
</soap:Envelope>
Contained in the soap:Body will be an outer node called MethodName (whatever the name of the method is) followed by the word Response (for example, GetEventListResponse if the web method is called GetEventList.). Within that node will be a single node called MethodName (again, whatever the name of the method is) followed by the word Result (for example, GetEventListResult).
Within that node will be another node called Results which will contain an attribute called recordReturn which will contain the count of records returned.
Within Results will be a repeating nodes called Result, one node for each single result.
Within each Result will be the actual list of fields, each field represented as an XML element.
DateTime Types
Data whose base data type is DateTime will typically be returned in the following format:
5/24/2009 12:00:00 AM
In other cases, however, data whose base data type is DateTime might be formatted in MM/DD/YYYY format (with leading zeroes for single-digit months and days).
Schema
The schema of these response types looks like this (assuming the name of the web method is MethodName):
<s:element name="MethodNameResponse">
<s:complexType>
<s:sequence>
<s:element minOccurs="0" maxOccurs="1" name="MethodNameResult">
<s:complexType mixed="true">
<s:sequence>
<s:any/>
</s:sequence>
</s:complexType>
</s:element>
</s:sequence>
</s:complexType>
</s:element>
Recommendations
Since most xWeb integrations will be calling multiple GET methods, you might want to develop a universal class to interpret these results, rather than working directly with XML. Since each response has a different field name, you still need to refer to each field name.
For example, suppose you have a response like this:
<Results recordReturn="2">
<Result>
<sac_key>aa904587-991c-4276-aaf3-3c33b4867735</sac_key>
<sac_cat_key>909b5d5b-b451-449b-a539-547653322849</sac_cat_key>
<sac_action_code>KEYSTONE</sac_action_code>
<sac_key_ext>aa904587-991c-4276-aaf3-3c33b4867735</sac_key_ext>
</Result>
<Result>
<sac_key>ef3355f8-efc8-4346-a7e8-5d4824e2850c</sac_key>
<sac_cat_key>909b5d5b-b451-449b-a539-547653322849</sac_cat_key>
<sac_action_code>7CMT5</sac_action_code>
<sac_key_ext>ef3355f8-efc8-4346-a7e8-5d4824e2850c</sac_key_ext>
</Result>
</Results>
If you are working in .NET, you could have a method like this. Other programming languages might have equivalent constructs.
/// <summary>
/// Returns a DataSet with a single DataTable, from the provided XMLNode. Each Result in the XML will
/// become a DataRow in the first DataTable, with one DataColumn for each XML element.
/// </summary>
/// <param name="xmlNode"></param>
/// <returns></returns>
public DataSet PopulateDataSetFromXmlNode(XmlNode xmlNode)
{
XmlReader xmlReader = new XmlNodeReader(xmlNode);
DataSet oDataSet = new DataSet();
oDataSet.ReadXml(xmlReader, XmlReadMode.Auto);
return oDataSet;
}
You would call the method like this. Note that this code fragment does not have error handling, etc.:
// Get Action Sub-Type List:
// Instantiate web service and authenticate
xWeb.netForumXML xweb = new netForumXML( Url = "https://my.xweb.url/secure/netforumxml.asmx");
xweb.Authentication("myusername", "mypassword");
// Action Type key to pass to the web method
guidActionTypeKey = new Guid("909B5D5B-B451-449B-A539-547653322849");
// Call the web method and convert the XML into a DataSet:
DataSet dsActionSubTypes = PopulateDataSetFromXmlNode(xweb.GetActionSubTypeList(guidActionTypeKey));
// Loop through each DataRow in the DataSet's first (and only) DataTable and get the results:
foreach(DataRow row in dsActionSubTypes.Tables[1].Rows)
{
string actionSubTypeKey = row["sac_key"].ToString();
string actionSubTypeCode = row["sac_action_code"].ToString();
}
FAQ
Needing Additional Data Elements
Q. A particular web method works great but I need one additional field. How can I get this additional field?
A. Baseline web methods cannot be modified. If the field is a baseline field (that is, not an Extender Column) and is closely related to the other fields in the return, then contact Abila as it might be possible to modify the baseline web method to include the additional field.
Another alternate is to create a custom web method; check with your Abila representative on the options.
We do NOT recommend calling the base web method and then calling additional method(s) to get the additional data. Doing so can compromise performance. Although it might be expedient to do this, in the long run that's not the best solution. Please work with Avectra to arrive at the best long-term solution.