Tutorial

This tutorial provides a quick dive into using the API and the broad stroke concepts involved.

Note

This tutorial uses the distribution bundle in a web page, but you can also use the node REPL. See Installing for instructions.

Start of by creating a directory for the tutorial, download and place the pre-built JavaScript API file there. Create a new HTML file and include the following contents.

<!DOCTYPE html>
<html>
<head>
    <title>ftrack API example</title>
</head>
<body>
    <h1>ftrack API example</h1>

    <!-- Include the ftrack API -->
    <script type="text/javascript" src="./ftrack.min.js"></script>
</body>
</html>

Save the HTML file and open it in your web browser of choice. Then open the browser’s JavaScript console to start playing around with the API.

The API uses sessions to manage communication with an ftrack server. Create a session that connects to your ftrack server (changing the passed values as appropriate):

var session = new ftrack.Session(
    'https://my-company.ftrackapp.com',
    'john.doe@example.com',
    '7545344e-a653-11e1-a82c-f22c11dd25eq'
);

session.initializing.then(function () {
    console.info('API session initialized successfully.');
});

If everything works as expected, you should see the console message appear in the JavaScript console. If not, double check that the credentials you specified are correct.

The communication with the ftrack server in the JavaScript API is asynchronous, often returning Promises. When the session is constructed, the instance is returned immediately, while the API is being initialized in the background. Once the API has been initialized, the session.initializing promise will be resolved.

Note

If session methods are used before the session is fully initialized, the execution will be delayed until the session is initialized.

Query projects

Now, let’s start of using the API with an example. Let’s list the names of all projects.

var request = session.query('select name from Project');
request.then(function (response) {
    var projects = response.data;
    console.info('Listing ' + projects.length + ' projects');

    projects.forEach(function (project) {
        console.info(project.name);
    });
});

Each project returned will be a plain JavaScript object and contain the selected attributes.

The session contains a few other methods besides query(), such as create(), update() and delete(). Next up, let’s take a look at combining the query call with an update operation. Since the method return promises, we can chain various asynchronous operations one after the other.

In the example below a specific project is retrieved, and then its status is set to hidden, hiding the project from the UI.

var projectName = 'my_project';
var request = session.query(
    'select id from Project where name is ' + projectName
);

request.then(function (response) {
   return response.data[0].id;

}).then(function (projectId) {
    return session.update('Project', [projectId], {
        status: 'hidden'
    });

}).then(function (response) {
    console.info('Project hidden', response);
});

See also

Now that you have gotten the hang of the basics, have a look at a more realistic example, using the API to display versions published in a dashboard widget within the ftrack web interface.

https://bitbucket.org/ftrack/ftrack-javascript-api-example-basic-widget

Uploading files

Files are stored as components in ftrack. Here is an example on how to create a component from a file in ftrack and upload it to the ftrack.server location.

// Create a fake file. In real world this would come from a file dropped in the
// browser. Please note that the File constructor is not supported in all browsers.
var data = { foo: 'bar' };
var file = new File([JSON.stringify(data)], 'data.json');

var promise = session.createComponent(file);

promise.then((response) => {
    var component = response[0].data;
    console.debug('Component', component);
    console.debug('ComponentLocation', response[1].data);

    console.debug('Component URL: ' + session.getComponentUrl(component.id));
    console.debug('Component thumbnail URL: ' + session.thumbnailUrl(component.id));
});