Queries

Abstract

This section details the queries supported by this module.

Query Format

Unlike the queries used in the nexiles|gateway core, this plug-in uses a structured query format. Queries need to be given as JSON Objects.

We support passing queries:

• as URL Parameter
• in the request body

URL Parameter

To support easy testing and manual queries using a web browser, the plug-in supports queries specified as URL parameter. Multiple queries are accepted, they are aggregated into one composite query.

Examples (only the query part is shown):

.../services/query/1.0/query?q={"name":"*.prt"}
.../services/query/1.0/query?q={"type":"wt.part.WTPart","name":"*.prt"}
.../services/query/1.0/query?q={"number":"0815*"}&q={"type":"wt.part.WTPart","name":"*.prt"}
.../services/query/1.0/query?q={"name":"269*.asm","config_spec":"latest"}

Request Body

For automated uses it is easier to specify the query in the request body.

Note

Be sure that you specify the correct mime type in the HTTP header application/json

Example (matches the third query from the URL parameter example):

{
    "qq": [
        {
            "number": "0815*"
        } , {
            "type": "wt.part.WTPart"
            "name": "*.prt"
        }
    ]
}

Query Filters

All the query filters supported by the nexiles|gateway core query module are supported.

Config Specs

The user of this plug-in can make use of config specs. These are additional filters which are processed on the server and filter the result set in certain ways.

Config specs are passed as config_spec key in the query. The value of this key specifies the config spec, e.g:

"config_spec": "<<config-spec-type>>"

Some config specs take arguments, which are passed after the type separated by pipes (|):

"config_spec": "<<config-spec-type>>|<<argument>>|<<argument>>|...."

Note

Config Specs can not be combined.

Note

Some Config Specs are usable only on certain types.

config spec: Latest

allowed types:Iterated types

:type latest :arguments: none example: “config_spec”: “latest”

Returns, in priority order, the latest iteration for a master owned by the current principal, the latest iteration by comparing the iterationIdentifier’s series value if not owned by the current principal, or the latest by create Timestamp if the series values are equivalent. Note that only one iteration is returned for any given master.

config spec: Life Cycle State

allowed types:things which have a life cycle

:type lifecycle :arguments: the life cycle name example: “config_spec”: “lifecycle|INWORK”

This config spec filters the result set for a given life cycle state.

Original WT10 docs:

The LifeCycleConfigSpec can be applied to LifeCycleManaged elements to filter them based on life cycle state. Only those elements at the specified life cycle state will be returned.

config spec: Folder

allowed types:things which have are Foldered

:type folder :arguments: The OID of a Folder object, or a cabinet based object. example: “config_spec”: “folder|OR:wt.folder.Cabinet:12345”

The IteratedFolderedConfigSpec can be used to filter IteratedFoldered elements based on folder location. Only those elements in the particular folder or sub-folder will be returned by this ConfigSpec.

Uf the OID passed resolves to a object which implements the ‘Folder’ interface, then this object is used, else a method getDefaultCabinet is queried to fetch the default cabinet of the object. This is means that one can pass e.g. a Product, a Library etc. and the config spec works as expected.

Fields and Associations

Often it’s application dependent how much information about each of the results is actually needed.

Per default the query plug-in only reports a minimal set of values per query result to keep the response time down.

If an application needs more information, then it can specify fields and associations along with the query.

fields

This specifies the attributes which are read from the resulting object. Please note, this only works for simple object attributes. If a attribute is not found, then null is returned.

associations

This specifies the associations which should be returned per result object. This is expensive in terms of processing time on the server – so be careful.

Fields

Field examples

Note

For a comprehensive list refer to the Windchill java docs and look for simple attributes.

field name	description	object type
name	the name attribute	e.g. EPMDocument
CADName	the CADName attribute	e.g. EPMDocument
latestIteration	the latestIteration attribute	all Iterated types
state	the Life Cycle State attribute	all Iterated types
location	the folder the object is located in	all Foldered types
folderPath	path of the object in it’s container	all Foldered types
containerName	the name of the container of this object	all Contained types
versionDisplayIdentifier	the version	all Versioned types
iterationDisplayIdentifier	the iteration	all Versioned types

Note

The example latestIteration is actually a flag returned by the method isLatestIteration() – but we can only use values not methods.

Example Query

Consider the following query:

http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/1.0/query?limit=5&q={"name":"SQ*.prt%"}&field=name&field=CADName&field=latestIteration&field=number

Here, we ask for all EPMDocument types which have a name attribute like SQ*.prt, and we’d like additionally see the attributes name, number, CADName and isLatestIteration.

Note

For easier debugging and testing, we also allow to specify the fields URL parameter. Note that there the name is singular because URL parameter can be specified multiple times.

The JSON post body parameter is called fields (plural).

Here’s the result (shortened, formatted):

{
    url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/1.0/query/190952?start=0&limit=5&page=0",
    next: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/1.0/query/190952?start=0&limit=5&page=1",
    session: 190952,
    start: 0,
    count: 5,
    success: true,
    limit: 5,
    page: 0,
    pos: 0,
    total_count: 433,
    items: [
        {
            url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/epmdocuments/OR:wt.epm.EPMDocument:48430",
            latestIteration: true,
            CADName: "sqb.prt",
            number: "SQB.PRT",
            details: "http://windchill.virtual.nexiles.com/Windchill/app/#ptc1/tcomp/infoPage?oid=OR:wt.epm.EPMDocument:48430&u8=1",
            oid: "OR:wt.epm.EPMDocument:48430",
            name: "sqb.prt"
        },
        {
            url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/epmdocuments/OR:wt.epm.EPMDocument:49045",
            latestIteration: true,
            CADName: "sqb001.prt",
            number: "SQB001.PRT",
            details: "http://windchill.virtual.nexiles.com/Windchill/app/#ptc1/tcomp/infoPage?oid=OR:wt.epm.EPMDocument:49045&u8=1",
            oid: "OR:wt.epm.EPMDocument:49045",
            name: "sqb001.prt"
        },
        {
            url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/epmdocuments/OR:wt.epm.EPMDocument:48588",
            latestIteration: true,
            CADName: "sqb002.prt",
            number: "SQB002.PRT",
            details: "http://windchill.virtual.nexiles.com/Windchill/app/#ptc1/tcomp/infoPage?oid=OR:wt.epm.EPMDocument:48588&u8=1",
            oid: "OR:wt.epm.EPMDocument:48588",
            name: "sqb002.prt"
        },
        {
            url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/epmdocuments/OR:wt.epm.EPMDocument:48771",
            latestIteration: true,
            CADName: "sqb003.prt",
            number: "SQB003.PRT",
            details: "http://windchill.virtual.nexiles.com/Windchill/app/#ptc1/tcomp/infoPage?oid=OR:wt.epm.EPMDocument:48771&u8=1",
            oid: "OR:wt.epm.EPMDocument:48771",
            name: "sqb003.prt"
        },
        {
            url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/epmdocuments/OR:wt.epm.EPMDocument:48667",
            latestIteration: true,
            CADName: "sqb004.prt",
            number: "SQB004.PRT",
            details: "http://windchill.virtual.nexiles.com/Windchill/app/#ptc1/tcomp/infoPage?oid=OR:wt.epm.EPMDocument:48667&u8=1",
            oid: "OR:wt.epm.EPMDocument:48667",
            name: "sqb004.prt"
        }
    ]
}

Associations

Associations are used in e.g. ExtJS to model data structures which have associations. In Windchill, we have multiple associations, which are type specific.

Examples:

IBA Attributes

Some object may have IBA Attributes.

Secondary Content

Objects which implement the ContentHolder interface may have multiple content objects.

Representations

Objects which implement the Representable interface may have multiple representations (viewables).

Association Keys

assoc key	description	remark	status
ibas	IBA attributes	Only EPMDocument types ATM	draft
content	content files	objects implementing the ContentHolder interface	draft
vault_info	vault file info	objects implementing the ContentHolder interface	draft
files	content files using file service URLs	objects implementing the ContentHolder interface	draft
representations	representations	objects implementing the Representable interface	draft
versions	version history	objects implementing the Iterated interface	not yet implemented
iterations	iteration history	objects implementing the Iterated interface	not yet implemented

Example query

Please consider the following query:

http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/1.0/query?q={"name":"SQ*.prt"}&field=name&field=CADName&field=latestIteration&assoc=ibas&assoc=representations&limit=5

Here we again ask for EPMDocument types matching a certain name pattern, include some additional fields (see above). This time, we asked for the associations ibas and representations.

Note

For easier debugging and testing, we also allow to specify the associations as URL parameter. Note that for the URL parameter the key is assoc (singular) since that parameter can be specified multiple times.

The JSON post body parameter is called associations (plural).

This is the (shortened, only one result shown) result. Things to notice:

• A association returns a empty list if it contains no objects. This is also true if the association does not match the result type.
• The runtime (_runtime field) is considerably higher. In this example the back end needed to fetch all representations for the page results.
• Associations are not cached – if you request a page ten times, the associations are calculated ten times.

{
    _runtime: 1.20300006866455078,
    count: 5,
    url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/1.0/query/191313?start=0&limit=5&page=0",
    next: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/1.0/query/191313?start=0&limit=5&page=1",
    query: {
        associations: [
            "ibas",
            "representations"
        ],
        fields: [
            "name",
            "CADName",
            "latestIteration"
        ],
        qq: [
            {
                name: "SQ*.prt"
            }
        ]
    },
    start: 0,
    success: true,
    limit: 5,
    page: 0,
    pos: 0,
    total_count: 433,
    items: [
        {
            url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/epmdocuments/OR:wt.epm.EPMDocument:48430",
            details: "http://windchill.virtual.nexiles.com/Windchill/app/#ptc1/tcomp/infoPage?oid=OR:wt.epm.EPMDocument:48430&u8=1",
            oid: "OR:wt.epm.EPMDocument:48430",
            name: "sqb.prt",
            latestIteration: true,
            CADName: "sqb.prt",
            ibas: [ ],
            representations: [
                {
                    url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/wvspvp.pvp?u8&HttpOperationItem=wt.content.ApplicationData%3A88944&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=wvspvp.pvp&forceDownload=true",
                    role: "PRODUCT_VIEW_EDP",
                    filename: "wvspvp.pvp",
                    name: "Demo"
                },
                {
                    url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt.pvm?u8&HttpOperationItem=wt.content.ApplicationData%3A88953&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt.pvm&forceDownload=true",
                    role: "PRODUCT_VIEW_EDM",
                    filename: "sqb_prt.pvm",
                    name: "Demo"
                },
                {
                    url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt_small.jpg?u8&HttpOperationItem=wt.content.ApplicationData%3A88938&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt_small.jpg&forceDownload=true",
                    role: "THUMBNAIL_SMALL",
                    filename: "sqb_prt_small.jpg",
                    name: "Demo"
                },
                {
                    url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt.pvs?u8&HttpOperationItem=wt.content.ApplicationData%3A88956&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt.pvs&forceDownload=true",
                    role: "PRODUCT_VIEW_ED",
                    filename: "sqb_prt.pvs",
                    name: "Demo"
                },
                {
                    url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt.pvt?u8&HttpOperationItem=wt.content.ApplicationData%3A88941&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt.pvt&forceDownload=true",
                    role: "THUMBNAIL3D",
                    filename: "sqb_prt.pvt",
                    name: "Demo"
                },
                {
                    url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt.ol?u8&HttpOperationItem=wt.content.ApplicationData%3A88950&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt.ol&forceDownload=true",
                    role: "SECONDARY",
                    filename: "sqb_prt.ol",
                    name: "Demo"
                },
                {
                    url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt.pva?u8&HttpOperationItem=wt.content.ApplicationData%3A88947&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt.pva&forceDownload=true",
                    role: "SECONDARY",
                    filename: "sqb_prt.pva",
                    name: "Demo"
                },
                {
                    url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt.jpg?u8&HttpOperationItem=wt.content.ApplicationData%3A88935&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt.jpg&forceDownload=true",
                    role: "THUMBNAIL",
                    filename: "sqb_prt.jpg",
                    name: "Demo"
                }
            ]
        },

        ...
    ]
}

Macro Expansion

Some queries are very cumbersome for the end-user to specify. Therefore, the query plugin supports macros.

macro key	parameters	description
@folder_path	context	Expands into a series of folder queries

Macro: folder_path

This macro expands into a series of folder queries such that the query will limit itself to objects below or in the given folder path.

Example – find all assemblies below /Default/1_CoreAndFrame of the given context:

{
    "qq": [
        "@folder_path": "/Default/1_CoreAndFrame",
        "context":      "OR:wt.inf.library.WTLibrary:3204656",
        "name":         "*.asm"
    ],
    "fields": [ ... ]
}

Query Options

You can set these global options on a query using the options key:

option	description
adminquery	Execute query as administrator