Understanding Queries
Queries are crucial in Gotransverse because your application will often need to retrieve information to create objects. For example, creating an order requires queries for bill cycle, billing account category, and product.
For more detailed instructions, refer to REST Overview and SOAP Overview.
Query Keys
Queries can be as broad as "return all the billing accounts" and as specific as "return billing account with eid of ‘1557’". Query Keys are parameters used as keys to filter query results. Most queries require a key to filter results. Refer to the table of Query Keys for more information.
Logic Filters
The whereClause parameter adds an additional filter to query results. The whereClause allows you to specify a parameter within the entity and filter it using one or more relational expressions.
Example: <whereClause entityType="paymentTerm" clause="eid neq '134'"/> | Returns instances of the queried entity where the paymentTerm does not equal 134. Refer to whereClause for more information.
Query Scope
Query Scope determines the depth of information returned in a query response. By default, queries are SHALLOW. A SHALLOW query will return attributes on the queried object, but will only return the EID of any elements within, and only the count of any collections. A DEEP query will return all attributes for the object AND the collections in the object.
Example SHALLOW Query Result
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:queryResponse xmlns="http://www.tractbilling.com/billing/1_28/domain" xmlns:ns2="http://www.tractbilling.com/billing/1_28/service">
<ns2:return successful="true">
<billingAccounts pageNumber="1" pageSize="50" totalElements="1" elementCount="1" totalPages="1">
<billingAccount accountNum="1089" billType="EMAIL" automaticRecurringPayment="true" status="ACTIVE" pendingChargesTotal="0.00" balance="-10.09" startDate="2015-09-17T16:43:04.000-05:00" taxExempt="false" currencyType="USD" nextInvoiceDate="2014-08-04T00:00:00.000-05:00" eid="51800" queryScope="SHALLOW">
<dailyBillCycle eid="214" queryScope="EID"/>
<organization eid="55572" queryScope="EID"/>
<recurringPayments pageNumber="1" pageSize="50" totalElements="1" elementCount="0" totalPages="1"/>
<billingAccountCategory eid="80" queryScope="EID"/>
<services pageNumber="1" pageSize="50" totalElements="1" elementCount="0" totalPages="1"/>
<pendingCharges pageNumber="1" pageSize="50" totalElements="2" elementCount="0" totalPages="1"/>
<customFieldValues pageNumber="1" pageSize="50" totalElements="0" elementCount="0" totalPages="0"/>
<paymentTerm eid="136" queryScope="EID"/>
</billingAccount>
</billingAccounts>
</ns2:return>
</ns2:queryResponse>
</soap:Body>
</soap:Envelope>Example DEEP Query Result
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:queryResponse xmlns="http://www.tractbilling.com/billing/1_28/domain" xmlns:ns2="http://www.tractbilling.com/billing/1_28/service">
<ns2:return successful="true">
<billingAccounts pageNumber="1" pageSize="50" totalElements="1" elementCount="1" totalPages="1">
<billingAccount accountNum="1089" billType="EMAIL" automaticRecurringPayment="true" status="ACTIVE" pendingChargesTotal="0.00" balance="-10.09" startDate="2015-09-17T16:43:04.000-05:00" taxExempt="false" currencyType="USD" nextInvoiceDate="2014-08-04T00:00:00.000-05:00" eid="51800" queryScope="DEEP">
<dailyBillCycle name="Daily BC 1" startDate="2015-09-24T00:00:00.000-05:00" endDate="2015-09-25T00:00:00.000-05:00" billCycleType="Daily" autoBill="false" status="ACTIVE" currencyType="USD" eid="214" queryScope="DEEP"/>
<organization name="Hole In The Wall" eid="55572" queryScope="DEEP">
<addresses>
<postalAddress purpose="SERVICE" country="USA" city="Austin" regionOrState="TX" postalCode="78705" line1="100 Guadalupe" eid="205432" queryScope="DEEP"/>
<postalAddress purpose="BILLING" country="USA" city="Austin" regionOrState="TX" postalCode="78705" line1="100 Guadalupe" eid="205434" queryScope="DEEP"/>
<emailAddress purpose="PRIMARY" email="ialexander@gotransverse.com" eid="205436" queryScope="DEEP"/>
<telecomAddress purpose="OFFICE" countryCode="1" areaCode="512" number="7738577" eid="205438" queryScope="DEEP"/>
</addresses>
</organization>
<recurringPayments pageNumber="1" pageSize="50" totalElements="1" elementCount="0" totalPages="1"/>
<billingAccountCategory type="All Accounts" description="Default billing account category" status="BA_CATEGORY_ACTIVE" eid="80" queryScope="DEEP"/>
<services pageNumber="1" pageSize="50" totalElements="1" elementCount="0" totalPages="1"/>
<pendingCharges pageNumber="1" pageSize="50" totalElements="2" elementCount="0" totalPages="1"/>
<customFieldValues pageNumber="1" pageSize="50" totalElements="0" elementCount="0" totalPages="0"/>
<paymentTerm name="Net 30" termDays="30" graceDays="0" eid="136" queryScope="DEEP"/>
</billingAccount>
</billingAccounts>
</ns2:return>
</ns2:queryResponse>
</soap:Body>
</soap:Envelope>
Refer to the following topics for more information about queries: