Tutorial: Low Level API Access¶

Author:: Stefan Eletzhofer
Date:: 2012-05-22

Abstract¶

This tutorial chapter discusses how to use the low-level API object.

Prerequisites¶

You should be comfortable using the python REPL.
You should have at least read the Tutorial: Introduction and Tutorial: Performing Queries.

Why A Low Level API?¶

There’ll be always some API calls which will not be wrapped in utility functions.
This API is used by the other, higher level functions
By understanding the low level API, you gain a better understanding how the API works.
Because we can ;)

Overview¶

You can access the API using the API objects which you get by nexiles.tools.api.get_api() and nexiles.tools.api.get_resource().

API Call Results¶

All API calls return a Python mapping object

Specific Resources¶

Calls to a specific resource return a mapping like this:

>>> from nexiles.tools.api import get_api, get_resource
>>> api = get_api(...)
>>> resource = get_resource(api, "document")
>>> resource("OR:....")
{
    "description": "desc",
    "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:149043176",
    "oid": "OR:wt.doc.WTDocument:149043176",
    "modified": "2012-05-04T13:48:11",
    "number": "246B7CC974E5498DAC670FD5307A562B",
    "item": {
        ... more keys ...
    },
    "version": "-.1",
    "details": "http://example.com/Windchill/servlet/TypeBasedIncludeServlet?oid=OR:wt.doc.WTDocument:149043176&u8=1",
    "name": "TestDoc"
}

The idea is that the top level keys are generic, that is, available for all resources:

url: The URL to the object which produces the output.
oid: The OID of the object
number: The number of the object.
details: The Windchill UI details page for this object. This is not a API URL.

If available, these keys are added, too:

name: The name of the object.
cadname: The cadname of the object – i.e. the file name. Only for EPM Documents.
description: The description.
version: The version of iterable items.
path: The path of folderable items.
path: The path of folderable items.
modified: The modified timestamp.

The items key itself is a mapping which contains keys highly specific to a business object.

Queries¶

Queries return lists of items. Example:

>>> resource.get(limit=4)
{
    "count": 4,
    "items": [
        {
            "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:149043432",
            "oid": "OR:wt.doc.WTDocument:149043432",
            "number": "0000000481",
            "name": "foo"
        },
        {
            "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:149047649",
            "oid": "OR:wt.doc.WTDocument:149047649",
            "number": "0000000441",
            "name": "bar"
        },
        {
            "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:149049620",
            "oid": "OR:wt.doc.WTDocument:149049620",
            "number": "00000000482",
            "name": "baz"
        },
        {
            "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:147270335",
            "oid": "OR:wt.doc.WTDocument:147270335",
            "number": "0000000461",
            "name": "quux"
        }
    ]
}

Here, we always include the count key on the top level. This holds the number of results.

The items key holds a sequence of mappings, one mapping for each result. These mappings contain keys:

url: The URL to the resource.
oid: The OID of the result.
number: The name of the result.
name: The name of the result.

Common Tasks¶

Note

For the following examples we assume that the local variable oid holds the OID of a specific object which exists in the Windchill database.

Getting IBA Attributes¶

Accessing the IBA Attributes of a business object in Windchill is done by accessing the attributes action on a specific object:

>>> resource = get_resource(api, "document")
>>> result = resource(oid).attributes.get()
>>> print result
{
    "count": 1,
    "description": "desc",
    "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:149043573",
    "items": [
        {
            "name": "CUSTOMER",
            "value": "nexiles"
        }
    ],
    "oid": "OR:wt.doc.WTDocument:149043573",
    "modified": "2012-05-06T16:57:23",
    "number": "5F03E86A98E84ECABE5F7977C4D63590",
    "version": "-.1",
    "details": "http://example.com/Windchill/servlet/TypeBasedIncludeServlet?oid=OR:wt.doc.WTDocument:149043573&u8=1",
    "name": "TestDoc"
}

This is a query, so we need to check for the count attribute:

>>> count = result["count"]
>>> attributes = result["items"]

Now we have all the attributes in attributes. This is now a list of mappings, each having a name key, and a value key:

>>> print attributes[0]
{
    "name": "CUSTOMER",
    "value": "nexiles"
}

Getting the iteration or version history¶

Accessing the history of a business object in Windchill is done by accessing the history action on a specific object:

>>> resource = get_resource(api, "document")
>>> results = resource(oid).history.get(q="iterations")
>>> print results
{
    "count": 2,
    "description": "",
    "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:147270335",
    "items": [
        {
            "description": "",
            "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:147270335",
            "oid": "OR:wt.doc.WTDocument:147270335",
            "number": "0000000461",
            "modified": "2012-05-03T19:50:14",
            "version": "-.2",
            "details": "http://example.com/Windchill/servlet/TypeBasedIncludeServlet?oid=OR:wt.doc.WTDocument:147270335&u8=1",
            "name": "foo"
        },
        {
            "description": "",
            "url": "http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:wt.doc.WTDocument:147213032",
            "oid": "OR:wt.doc.WTDocument:147213032",
            "number": "0000000461",
            "modified": "2012-05-03T18:36:26",
            "version": "-.1",
            "details": "http://example.com/Windchill/servlet/TypeBasedIncludeServlet?oid=OR:wt.doc.WTDocument:147213032&u8=1",
            "name": "foo"
        }
    ],
    "oid": "OR:wt.doc.WTDocument:147270335",
    "modified": "2012-05-03T19:50:14",
    "number": "0000000461",
    "version": "-.2",
    "details": "http://example.com/Windchill/servlet/TypeBasedIncludeServlet?oid=OR:wt.doc.WTDocument:147270335&u8=1",
    "name": "foo"
}

This is a query, so we need to check for the count attribute:

>>> count = results["count"]
>>> iterations = results["items"]

Now we have all the iterations in iterations.

For all the versions, just pass q=”versions”:

>>> results = resource(oid).history.get(q="versions")

The processing of the results is the same as above.

Getting Help¶

All the actions which are available can be listed like so:

>>> help_items = resource(oid).help.get().get("items")

The help items will each contain a url, docstring, name and http_method attribute.

Note

the above is best viewed using a browser which is able to format JSON documents nicely. For chrome and firefox, install the JSONView plugin. To display the help for a document, navigate to:

http://example.com/Windchill/servlet/nexiles/tools/api/1.0/documents/OR:…./help

You need to replace the OID and the base URL of course.