#header-wrapper { display: none; } body { visibility: visible; } #main { height: 100px; overflow: hidden; } The website is not operational without JavaScript. Please check your browser settings and reload the page.

Displayr API

The Displayr API allows you to automatically create and update documents. See the Reference for technical details.

Overview

Uploading and configuring a new document

Uploading and configuring a new document	This the process of automatically taking a raw data file (e.g. SPSS .sav file) and creating a document from it. Automating this process makes sense if you expect to have many data files with a similar structure. Work out how what actions you need to perform to set up the document as a normal user, using Displayr's normal interface, and find corresponding QScript commands to automate the same actions. For example, you will need to: Use the QScript command `DataFile.setQuestion()` to combine variables into multiple-response variable sets, unless they are properly defined in the data file. Creates pages using `ReportGroup.appendGroup()` to become pages in your document Create charts, tables, etc. on each page using `ReportGroup.appendPlot()`, `ReportGroup.appendTable()`, etc. Write a QScript to automate the setup. Your script must be able to deal with the variety of data files you expect. This script should start out using `project.addDataFile()` to add your raw data. Use the API to create a document: Use `/API/Upload` to upload your raw data. Substitute the ID returned by `/API/Upload` into your script. Use `/API/NewProjectFromScript` to upload your script. Record the document secret returned, in case you want to use it to update the data (see below) or delete the document (`/API/DeleteProject`)
Automatically updating a document with new cases	This is the process you use to keep a document up to date with new raw data from a tracking study. A much easier alternative to using the API is to instead insert a new data set in Displayr using Insert > Data > Data Set, selecting URL and then pasting the URL of the data file from a cloud storage service such as Dropbox - this data will then update automatically whenever you edit your document. To instead use the API, you would use a process such as this periodically (e.g. daily): Upload the new data file using `/API/Upload`. If your data files are large you can upload just the new cases (see the `partial` parameter of `/API/ImportUpdatedData`), but uploading everything every time is safer because you need not worry about failed or duplicated transfers. Invoke `/API/ImportUpdatedData` to update an existing document using this file. To do this you will need the document secret that was returned by `/API/NewProjectFromScript`. You can also see the secret for a document you have uploaded manually from the Document Settings page in Displayr.

This the process of automatically taking a raw data file (e.g. SPSS .sav file) and creating a document from it. Automating this process makes sense if you expect to have many data files with a similar structure.

Work out how what actions you need to perform to set up the document as a normal user, using Displayr's normal interface, and find corresponding QScript commands to automate the same actions. For example, you will need to:
- Use the QScript command DataFile.setQuestion() to combine variables into multiple-response variable sets, unless they are properly defined in the data file.
- Creates pages using ReportGroup.appendGroup() to become pages in your document
- Create charts, tables, etc. on each page using ReportGroup.appendPlot(), ReportGroup.appendTable(), etc.
Write a QScript to automate the setup. Your script must be able to deal with the variety of data files you expect. This script should start out using project.addDataFile() to add your raw data.
Use the API to create a document:
1. Use /API/Upload to upload your raw data.
2. Substitute the ID returned by /API/Upload into your script.
3. Use /API/NewProjectFromScript to upload your script.
4. Record the document secret returned, in case you want to use it to update the data (see below) or delete the document (/API/DeleteProject)

Automatically updating a document with new cases

This is the process you use to keep a document up to date with new raw data from a tracking study.

A much easier alternative to using the API is to instead insert a new data set in Displayr using Insert > Data > Data Set, selecting URL and then pasting the URL of the data file from a cloud storage service such as Dropbox - this data will then update automatically whenever you edit your document.

To instead use the API, you would use a process such as this periodically (e.g. daily):

Upload the new data file using /API/Upload. If your data files are large you can upload just the new cases (see the partial parameter of /API/ImportUpdatedData), but uploading everything every time is safer because you need not worry about failed or duplicated transfers.
Invoke /API/ImportUpdatedData to update an existing document using this file. To do this you will need the document secret that was returned by /API/NewProjectFromScript. You can also see the secret for a document you have uploaded manually from the Document Settings page in Displayr.

Hints

Consider using naming conventions so your scripts can identify classes of variable sets. For example, you could name your demographic questions "D1", "D2", etc.
Check status codes in responses from Displayr. If you get a failure, e-mail the response body to yourself because it will contain an explanation of the error.
Calls involving long scripts or large data files may take multiple minutes to complete. Make sure you don't time out prematurely.