This is a powerful query web method that accepts criteria via the QuerySpecification and returns all attributes on each object retrieved.
The main criteria needs to be specified on the first XFRItem in the query XFRDataTransfer class below. The classdef and name criteria used for the query have been specified below.
'
' Setup the query request.
'
Dim lobjQuery As New DownloadService.XFRDataTransfer
Dim lobjItems() As DownloadService.XFRItem
ReDim lobjItems(0)
Dim lobjQueryItem As New DownloadService.XFRItem
lobjQueryItem.C = "DEVTag"
lobjQueryItem.N = "20CB%"
Dim lobjAttributes() As DownloadService.XFRAttribute
ReDim lobjAttributes(0)
lobjQueryItem.XFRA = lobjAttributes
lobjItems(0) = lobjQueryItem
lobjQuery.XFRItems = lobjItems
In some cases, the query needs to be run by interfacedef rather than classdef. This query gives more flexibility to return a variety of objects. To support this, there is a property on the web method called InterfaceDefToOverrideClassDef.
A ReturnSpecification can be specified, allowing the caller to specify one or many relationships to be returned.
For example, you could do a query for Tags and then decide to send back each system related to the tag.
Inputs
-
QuerySpecification – use the transferobject.Item to define attributes and relation attributes to use as criteria for the query.
-
ReturnSpecification – detail what related items to be returned by the query.
'
' Setup the return
'
Dim lobjReturn As New DownloadService.XFRDataTransfer
lobjReturn.XFRItems = Nothing
Dim lobjRetItems() As DownloadService.XFRItem
ReDim lobjRetItems(0)
Dim lobjReturnItem As New DownloadService.XFRItem
Dim larrRelDefs() As String = lstrRelDefs.Split(","c)
Dim lintRelDefs As Integer = larrRelDefs.Count
Dim lobjRetAttributes() As DownloadService.XFRAttribute
ReDim lobjRetAttributes(lintRelDefs - 1)
For lintX As Integer = 0 To lintRelDefs - 1
Dim lobjAttribute As New DownloadService.XFRAttribute
lobjAttribute.N = larrRelDefs(lintX)
lobjRetAttributes(lintX) = lobjAttribute
Next
lobjReturnItem.XFRA = lobjRetAttributes
lobjRetItems(0) = lobjReturnItem
lobjReturn.XFRItems = lobjRetItems
-
IncludeHistorical – returns terminated items
-
MaxNumber – If the user knows there are only 3 rows and wants to only return them, then this is used to instruct the RDBMS to return that many rows, making the query much faster.
-
InterfaceDefToOverrideClassDef – specify an interfacedef to be used in the query instead of classdef.
-
ReturnAsHierarchy – different way to send back the query results when using a return specification. See the output section for details on the differences.
Criteria examples
These are added as attributes to the first item in the QuerySpecification.
To find objects created since a date, see the example below,
Dim lobjAttributes() As DownloadService.XFRAttribute
ReDim lobjAttributes(0)
Dim lobjCreationDateAttr As New DownloadService.XFRAttribute
lobjCreationDateAttr.N = "CreationDate"
lobjCreationDateAttr.V = "2010/09/21-11:06:00:000"
lobjAttributes(0) = lobjCreationDateAttr
lobjQueryItem.XFRA = lobjAttributes
Primary Classification using Name of Classification and specifying the pathdefn.
Could be any relationship, Classification is being used here.
Dim lobjClassificationAttr As New XFRAttribute
lobjClassificationAttr.Name = "+SPFPrimaryClassification"
lobjClassificationAttr.Value = "DEV Battery bank"
lobjQueryItem.XFRAttributes.Add(lobjClassificationAttr)
Primary Classification using Name of Classification and specifying the ClassDef of Classification
Dim lobjClassificationAttr As New XFRAttribute
lobjClassificationAttr.Name = "SPFEquipmentClass"
lobjClassificationAttr.Value = "DEV Battery bank"
lobjQueryItem.XFRAttributes.Add(lobjClassificationAttr)
Related Item - in this case Folder
Dim lobjRelFolderAttr As New XFRAttribute
lobjRelFolderAttr.Name = "SPFFolder"
lobjRelFolderAttr.Value = "Apex-PlantA-001"
Multiple related items supported.
lobjRelFolderAttr.Value = "IN (Apex-PlantA-001,Apex-PlantA-002)"
lobjQueryItem.XFRAttributes.Add(lobjRelFolderAttr)
Property called DEVWeight value of 11kg.
Dim lobjWeightAttr As New XFRAttribute
lobjWeightAttr.Name = "DEVWeight"
lobjWeightAttr.Value = "11~kg"
lobjQueryItem.XFRAttributes.Add(lobjWeightAttr)
Object has an interface IDEVTag instantiated on it
Dim lobjIDefAttr As New XFRAttribute
lobjIDefAttr.Name = "IDEVTag"
lobjIDefAttr.Value = ""
lobjQueryItem.XFRAttributes.Add(lobjIDefAttr)
Use edges for criteria but only those with one relationship in the path definition, sometimes these are described as "simple edges." The purpose of using a simple edge as criteria is normally to filter the results set, making use of PropertyComparison and ValidEndInterfaces.
Dim lobjEdgeAttr As New XFRAttribute
lobjEdgeAttr.Name = "EDG_CurrentRevisions"
lobjEdgeAttr.Value = ""
lobjQueryItem.XFRAttributes.Add(lobjEdgeAttr)
Outputs
All attributes plus any relationships specified in the Return specification.
ReturnAsHierarchy = False
<XFRItem N="SPFFormPurpose" C="ClassDef">
<XFRA V="0003EVA" N="OBID" />
<XFRA V="SCHEMA" N="DomainUID" />
<XFRA V="20CB203" N="SPFFolderTag"
<XFRA V="ADMIN" N="SPFFolderOwningGroup"
REAL DATA
<XFRItem N="CreateListDocument" C="SPFMethod">
<XFRA V="List Document" N="SPFGUIDisplayAs" />
<XFRA V="SPFListDocClassClassDef" N="SPFArgument1" />
<XFRA V="True" N="SPFArgument2" />
<XFRA V="DC_Document_category_1" N="SPFArgument3" />
<XFRA V="ISPFListDocumentClass" N="SPFArgument4" />
<XFRA V="" N="SPFArgument5" />
<XFRA V="SPFDesignFile~SPFFileComposition~PROMPT" N="SPFArgument6" />
<XFRA V="" N="SPFArgument7" />
<XFRA V="" N="SPFArgument8" />
<XFRA V="" N="SPFArgument9" />
<XFRA V="True" N="SPFAvailableinDesktop" />
<XFRA V="False" N="SPFAvailableinWeb" />
<XFRA V="" N="SPFCascadeName" />
<XFRA V="001YR0A" N="OBID" />
<XFRA V="MTH_CreateListDocument" N="UID" />
<XFRA V="ADMIN" N="DomainUID" />
<XFRA V="2010/09/21-11:37:47:447" N="CreationDate" />
<XFRA V="9999/12/31-23:59:59:999" N="TerminationDate" />
<XFRA V="2010/09/21-11:37:47:447" N="LastUpdatedDate" />
<XFRA V="MTH_CreateListDocument" N="UniqueKey" />
<XFRA V="" N="Config" />
<XFRA V="superuser" N="CreationUser" />
<XFRA V="" N="TerminationUser" />
<XFRA V="CreateListDocument" N="Name" />
<XFRA V="New List Document..." N="Description" />
<XFRA V="Core.DocMgt" N="ContainerID" />
<XFRA V="CreateClassObj" N="-SPFClientAPIMethods" />
<XFRA V="DocumentUpdate,SystemAdmin,ProcessEngineer" N="-SPFAccessGroupMethod" />
<XFRI N="ISPFAdminItem" />
<XFRI N="ISPFSubscribableItem" />
</XFRItem>
ReturnAsHierarchy = True
<XFRItem N="SPFFormPurpose" C="ClassDef">
<XFRA V="0003EVA" N="OBID" />
<XFRA V="SCHEMA" N="DomainUID" />
<XFRR P="+SPFFolderTag" U=RelatedObjOBID RelUID~RelatedObjOBID RelUID"
<XFRItems>
<XFRItem ...
<XFRA V="20CB203" N="Name"
<XFRItem
<XFRR P="+SPFFolderOwngingGroup" U= RelatedObjOBID RelUID~RelatedObjOBID RelUID"
<XFRItems>
<XFRItem ...
<XFRA V="ADMIN" N="Name"
<XFRItem
REAL DATA
<XFRItem N="CreateListDocument" C="SPFMethod">
<XFRA V="List Document" N="SPFGUIDisplayAs" />
<XFRA V="SPFListDocClassClassDef" N="SPFArgument1" />
<XFRA V="True" N="SPFArgument2" />
<XFRA V="DC_Document_category_1" N="SPFArgument3" />
<XFRA V="ISPFListDocumentClass" N="SPFArgument4" />
<XFRA V="" N="SPFArgument5" />
<XFRA V="SPFDesignFile~SPFFileComposition~PROMPT" N="SPFArgument6" />
<XFRA V="" N="SPFArgument7" />
<XFRA V="" N="SPFArgument8" />
<XFRA V="" N="SPFArgument9" />
<XFRA V="True" N="SPFAvailableinDesktop" />
<XFRA V="False" N="SPFAvailableinWeb" />
<XFRA V="" N="SPFCascadeName" />
<XFRA V="001YR0A" N="OBID" />
<XFRA V="MTH_CreateListDocument" N="UID" />
<XFRA V="ADMIN" N="DomainUID" />
<XFRA V="2010/09/21-11:37:47:447" N="CreationDate" />
<XFRA V="9999/12/31-23:59:59:999" N="TerminationDate" />
<XFRA V="2010/09/21-11:37:47:447" N="LastUpdatedDate" />
<XFRA V="MTH_CreateListDocument" N="UniqueKey" />
<XFRA V="" N="Config" />
<XFRA V="superuser" N="CreationUser" />
<XFRA V="" N="TerminationUser" />
<XFRA V="CreateListDocument" N="Name" />
<XFRA V="New List Document..." N="Description" />
<XFRA V="Core.DocMgt" N="ContainerID" />
<XFRI N="ISPFAdminItem" />
<XFRI N="ISPFSubscribableItem" />
<XFRR U="001USIAC_CreateClassObj.MTH_CreateListDocument" P="-SPFClientAPIMethods">
<XFRItems>
<XFRItem N="CreateClassObj" C="SPFClientAPI">
</XFRItems>
</XFRR>
<XFRR U="001Y4WAMAG_DocumentUpdate.MTH_CreateListDocument~0024JXAMAG_ProcessEngineer.MTH_CreateListDocument~0003YEAMAG_SystemAdmin.MTH_CreateListDocument" P="-SPFAccessGroupMethod">
<XFRItems>
<XFRItem N="ProcessEngineer" C="SPFAccessGroup">
<XFRItem N="SystemAdmin" C="SPFAccessGroup">
<XFRItem N="DocumentUpdate" C="SPFAccessGroup">
</XFRItems>
</XFRR>
</XFRItem>
The relationships shown above are nested underneath the object with a XFRR node detailing the pathdefn and details of the rel UIDs (for each rel, the software takes the end object OBID appends the rel UID and join using tilda (~)). The highlighted areas in both output formats show the same data but with different outputs.
Implementation Notes
-
Each attribute in the QuerySpecification represents an AND criteria.
-
For relationships, specify multiple values in a Comma-separated format that represents OR – no wild card support and the IN must be specified. For example, IN (Name1,Name2)
-
Wildcards are supported (using %) on name only
-
Query is case sensitive
-
No support for complex objects as this is a business layer feature.
-
UOM’s can be specified by separating the Value and UOM in the value field. For example, 11~kg
-
IncludeHistoricalItems=True returns terminated items as well. For example, voided tags and so on