Topic: REST Interface for Accessing Data in ConfTool Pro (Read 82513 times)

ConfTool Pro offers a simple but secure REST API to access data of your ConfTool installation from other systems.

First you need to enable the REST interface of ConfTool Pro. Otherwise access is disabled.
To enable the interface go to:

Overview => Data Import and Export => Integrations With Other Systems

Scroll down to "Enable General REST Interface" to define a shared passphrase and enable the interface. The passphrase must have at least 8 characters (see image).
Below the field you can also find the URL of the REST interface. It looks like the following:
https:/ /www.conftool.net/my_conference/rest.php.
In your script to access the interface, please create a cryptomatic "nonce". This nonce has to be an integer (i.e. numerical), unique and increasing, i.e. every nonce must be higher than the last one. We recommend to use the current timestamp as nonce (e.g. use the function “time()” in PHP). More information on timestamps can be found at: http://www.unixtimestamp.com/index.php
Hint: To reset the nonce to 0 set a new shared secret in the backend of ConfTool.
Your cryptographic nonce and the shared password are concatenated and then used to create a SHA256 passhash that will authenticate the request.
Example: With the following timestamp "1372505462" as nonce and the shared passphrase "ctCRDNiH" we get:
sha256 ( "1372505462" + "ctCRDNiH" ) =
7794ca5eb107eacb0b100a13ca8fefb641aed0ec48c93c38bd7e57144ae8fd2f
See http://www.xorbin.com/tools/sha256-hash-calculator
To call the REST interface (e.g. at https:/ /www.conftool.net/my_conference/rest.php )
you can either use GET or POST. We usually recommend to use GET following the REST interface paradigm: http://de.wikipedia.org/wiki/Representational_State_Transfer
The two parameters “nonce” and “passhash” described above are always required to grant access to the interface, e.g.:
nonce=1372505462 (integer, your UNIQUE nonce)
passhash=7794ca5eb107eacb0b100a13ca8fefb641aed0ec48c93c38bd7e57144ae8fd2f
Command and further parameters:
You also have to specify a command and further parameters to create a valid request. Currently three commands are supported: downloadPaper, adminExport and remoteLogin. The command name is specified using the parameter “page”.
- Commands to access the data export function:
  Required:
  page=adminExport (fixed value)
  export_select=users (string, the name of the export required. Allowed values: papers, invitations, authors, subsumed_authors, topics, reviews, reviewers, sessions, participants, nametags, identities, event_participants, payments, identities )
  form_include_deleted=0 (0,1: include deleted entries or not)
  form_export_format=xml (also allowed: xml_short, csv_comma, csv_semicolon, and xls)
  form_export_header=default (include header or not)
  cmd_create_export=true (required, fixed value).
  
  Optional:
  form_export_users_options[]=extended (or "form_export_papers_options[]" etc. Please have a look at the html form code of the data export function of ConfTool Pro to see what names and values are supported)
  
  Please note: Generating exports can be quite time consuming (up to a few minutes). Please be patient and do not send to many requests, as otherwise your client will be blacklisted.
- Command to check the login details from another system and to access account details:
  Required:
  page=remoteLogin (fixed value)
  user=harald (string, the username or the e-mail of the user)
  command=request (get details of this user)
  or
  command=login (test if a user may login with this user name and password)
  For command "login" you therefore also require
  password:*** (string, the password of the user as un-encoded text. The request will not be stored.)
  
  Please see the PDF file for more details and examples.
- The following commands allow to download files/papers via the REST interface:
  Required parameters:
  page=downloadPaper (fixed value. Note: “page” is the name, “downloadPaper” is the value)
  form_id=111 (integer, the ID of the paper to be downloaded)
  Optional parameters:
  form_index=1 (integer, the number of the uploaded file: 1, 2, or 3)
  form_version=first (string, 'first' or 'final' for the final version if available)
  filename: (string, download name for the file)
  
  The call returns the requested file with the corresponding mime type and file name.
  
  Example call:
  https:/ /www.conftool.net/my_conference/rest.php?page=downloadPaper&form_id=5&nonce=1372505462&passhash=7794ca5eb107eacb0b100a13ca8fefb641aed0ec48c93c38bd7e57144ae8fd2f
- If you use the community system / online list of participants, you can also access the images of participants via the REST interface:
  Required parameters:
  page=showCommunityIcon (fixed value. Note: “page” is the name, “showCommunityIcon” is the value)
  form_id=111 (integer, the ID of the community icon to be downloaded, this can be found in the list "Export Conference Profiles")
  Optional parameters:
  filename: (string, download name for the file)
  
  The call returns the requested image using the corresponding mime type.
  
  Example call:
  https:/ /www.conftool.net/my_conference/rest.php?page=showCommunityIcon&form_id=13&nonce=1372505462&passhash=7794ca5eb107eacb0b100a13ca8fefb641aed0ec48c93c38bd7e57144ae8fd2f

For information on how to access the REST interface using a PHP script please refer to
https://www.conftool.net/ctforum/index.php/topic,282.0.html
or using a Linux bash script see
https://www.conftool.net/ctforum/index.php/topic,281.0.html .

More examples for frequently required switches:
For "export_select=papers" the following parameters are often required:
form_export_papers_options[]=authors_extended // Add extra columns for authors
form_export_papers_options[]=authors_extended_firstname // Output the authors in the format "first name last name"
form_export_papers_options[]=authors_extended_capitals // Output the authors' surnames in CAPITALS
form_export_papers_options[]=authors_extended_presenters // Add an * (asterisk) after each presenting author.
form_export_papers_options[]=authors_extended_columns // List name, organization and e-mail in separate columns.
form_export_papers_options[]=abstracts // Include abstracts of submissions.
form_export_papers_options[]=reviews // Include review details.
form_export_papers_options[]=session // Include session information
form_export_papers_options[]=downloads // Include information about uploaded files.
form_export_papers_options[]=submitter // Include details about submitting person, like address and participant status.
form_track=- // Filter by Track/Strand
form_status=p // Export only submissions that will be presented.
form_include_deleted=0 // Do not export withdrawn submissions
form_export_format=xml // Export in XML format OR use
form_export_format=xml_short // Export with XML format and leave out empty XML elements (with no data). This makes the export shorter.
form_export_header=default // required
cmd_create_export=true // required

For export_select=sessions the following parameters are advisable:
form_export_sessions_options[]=all
form_include_deleted=0
form_export_format=xml_short
form_export_header=default // required
cmd_create_export=true // required

Hints:
- "form_userID" can be used as additional filter for export_select=persons, papers, participants, attendees and event_participants
- The request string has to be "URL encoded", i.e., the brackets [] have to be written as %5B%5D
- Example request string (one line, of course the nonce and the passhash have to be replaced):
https://www.conftool.pro/demo/pro/rest.php?nonce=1464279840616&passhash=abcdefgd737c49dbda6671f3d951ccaef3254e37&page=adminExport&export_select=papers&form_export_papers_options%5B%5D=abstracts&form_export_papers_options%5B%5D=session&form_export_papers_options%5B%5D=downloads&form_status=p&form_include_deleted=0&form_export_format=xml_short&form_export_header=default&cmd_create_export=true