API Description

Author:Stefan Eletzhofer Date:July 03, 2015 State:production

Abstract

This is a description of the file service.

Purpose

The purpose of the file service is to provide programmers a high-level api to Windchill content items of Windchill business objects.

URLs

The API may be accessed by using HTTP Requests to the following URLs.

Base URL

BASE URL:<<windchill host>>:<<port>>/<<web service>>/servlet/nexiles/tools/services/files

The URLs below need the base url prefixed – e.g. to fetch the version one would use a URL like:

http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/files/version

API URLs

The following URLs define the API to the file service:

URL	Method	Purpose
files/version	GET	plug-in version
files/:oid	GET	return list of files
files/:oid/:filename	GET	return file content
files/:oid/:filename	POST	create update a file
files/:oid/:filename	DELETE	delete a file

To provide a way to create stable links to files, we need a alternate way to refer to business objects. For this purpose we’ll use the number of business objects.

Note

When using numbers, the file service assumes WTDocument types.

API: Version

URL:files/version method:GET

This fetches the version of the file service plug-in.

Data Format

The result of the HTTP GET is a JSON document, which has the following structure:

{
    version: "0.1dev",
    build: 4,
    date: "2013-04-15"
}

Example

Getting the plug-in version using CURL:

$ curl -q  --user nxoa:nxoa -X GET http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/files/version
{
  "version": "0.1dev",
  "build": 0,
  "date": "2013-04-04"
}

Using jQuery:

$.ajax({
    url: "/Windchill/servlet/nexiles/tools/services/files/version",
    context: document.body,
    success: function(data) {
        console.log("plug-in version" + data.version);
    }
});

API: File Listing

URL:files/ method:GET

The GET on for the list of files takes an optional role parameter, where role is the content role or all for all roles. The default is SECONDARY.

Example

http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber?role=all http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber?role=SECONDARY http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber?role=PRIMARY http://example.com/Windchill/servlet/nexiles/tools/services/files/OR:wt.doc.WTDocument:4711?role=all

Data Format

The result of the HTTP GET is a JSON document, which has the following structure:

{
    "count": <<number of files>>,
    "items": [
        {
            "url": <<url to file content>>,
            "role": <<content role>>
            "mimetype": <<the mime type of the file>>,
            "filename": <<the file name>>
            "size": <<the file size in bytes>>
        },
        ...
    ]
}

Examples

Using CURL:

curl -q  --user nxoa:nxoa -X GET http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/files/0000000001
{
  "_runtime": 0.04700016975402832,
  "count": 2,
  "items": [
    {
      "url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/files/0000000001/latest-xkcd.png",
      "role": "SECONDARY",
      "filename": "latest-xkcd.png",
      "mimetype": "image/png",
      "size": 34230
    },
    {
      "url": "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/files/0000000001/Minto-Pyramid-Principle.pdf",
      "role": "SECONDARY",
      "filename": "Minto-Pyramid-Principle.pdf",
      "mimetype": "application/pdf",
      "size": 666021
    }
  ]
}

Using jQuery:

$.ajax({
    url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/files/0000000001",
    type: "GET"
}).done(function (data) {console.log("file list: " + data.items); });

API: Get File Content

URL:files/:oid_or_number/:filename method:GET

Returns the file content of the named file.

Data Format

N/A – this request returns the raw bytes of the file.

Examples

http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber/afile.txt

or dynamically using jQuery:

$.ajax({
    url: "http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber/afile.txt",
    type: "GET"
}).done(function (data) {console.log("file data: " + data); });

Or by just using the URL in e.g. a IMG tag:

<img src="http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/files/0000000001/latest-xkcd.png"
     alt="example" />

API: Create or update a file

URL:files/:oid_or_number/:filename method:POST

To update a file, issue a HTTP POST request to the URL of the file. The content needs to be base64 encoded, the author uses https://github.com/carlo/jquery-base64 for that.

To create a new file, just do the same, inventing a new filename url.

POST Data Format

The POST body must be a JSON data structure with the following format:

{
    "data":         "<<data>>"
    "message":      "<< a check in message>>"
    "role":         "<<a winchill content role>>"
    "iterate":      True | False
}

The data supplied needs to be base64 encoded.

The role, iterate and message values my optionally specified as POST URL parameters.

data

default:none required:yes

The base64 encoded data.

message

default:“update file ‘<<name>>’” required:no

The message to use for the change made in the content holder. This message will show up in the standard Windchill UI.

role

default:“SECONDARY” required:no

The content role to use. For a list of valid content roles consult the Windchill Sys Admin Guide. The most prominent ones are ‘PRIMARY’ and ‘SECONDARY’.

iterate

default:False required:no

If true, a new iteration is made automatically.

Response Data Format

The response is a JSON encoded data structure with the following format:

{
    "success": true|false,
    "oid":  <<the (possibly new) OID>>,
    "url": <<the URL to the file download>>
}

Examples

Using CURL:

TBD

Using Python and the requests library:

TBD

Using jQuery – this assumes the base64 plugin for jQuery is installed:

var data = "file content";
$.ajax({
    url: "http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber/afile.txt",
    type:     "POST",
    dataType: "json",
    contentType: "application/json",
    data:     JSON.stringify({ data: $.base64.encode(data) })
}).done(alert("file updated"));

API: Delete a file

URL:files/:oid_or_number/:filename method:DELETE

To delete a file, issue a HTTP DELETE request to the URL of the file.

Response Data Format

The response is a JSON encoded data structure with the following format:

{
    "success": true|false,
    "oid":  <<the (possibly new) OID>>,
    "url": <<the URL to the file list>>
}

Examples

Deleting a file using jQuery:

$.ajax({
    url: "http://example.com/Windchill/servlet/nexiles/tools/services/files/somenumber/afile.txt",
    type: "DELETE"
}).done(alert("file deleted"));