Upload script

While there is a user interface for manual upload of files, it is generally quicker to develop the integration using an upload script from the very start.

The upload script needs to:

Authenticate each request to the server using HTTP basic authentication, using the username haplo and an API key as the password.

Upload one or more files, each with a separate name parameter, matching the names in the files section of the control file.

When all files are uploaded, make a separate request to apply the files.

Upload scripts just need to make POST requests to https URLs, using the multipart/form-data encoding for the request body. Just about all HTTP client libraries are capable of making these requests.

Example script for UNIX

The standard curl utility is often pre-installed on UNIX-like operating systems, such as Linux and macOS, or easily obtained through a package.

#!/bin/sh
set -e

# TODO: Edit this configuration
API_KEY=YOUR_API_KEY_HERE
FILE_DIRECTORY=/path/to/directory
SERVER=research.example.org

# Upload the control file
curl -X POST -F name=_control -F file=@${FILE_DIRECTORY}/_control.json --user haplo:${API_KEY} https://${SERVER}/api/haplo-user-sync/upload-file

# TODO: Edit the name and file arguments, and repeat if there are multiple files
curl -X POST -F name=users -F file=@${FILE_DIRECTORY}/users.json --user haplo:${API_KEY} https://${SERVER}/api/haplo-user-sync/upload-file

# Applies the files
curl -X POST --user haplo:${API_KEY} https://${SERVER}/api/haplo-user-sync/start-sync

Example script for Windows

For Windows servers, we recommend the use of the User Sync Uploader utility.

You can download a binary from the releases page. Checksums for the .exe downloads are:

Version	SHA256 checksum
20190924	`f362d0ab8b3a293e001597a22efbefe33d1f2ac7b55b6d4b8d7c4360762032fd`

At least .NET 4.7 is required for TLS 1.2 support, which is required for connecting to Haplo applications.

An example upload script is:

set HAPLO_API_KEY=YOUR_API_KEY_HERE
set HAPLO_SERVER=research.example.org

haplo-user-sync-uploader file _control path\to\_control.json
haplo-user-sync-uploader file users path\to\users.json
haplo-user-sync-uploader apply

Configuring the script

The server name is the hostname of the application you’re testing, or eventually the live application.

The API key is generated for a special service user using User sync administration UI:

Your Name » User sync administration » Create API key…

After creation, API keys are managed through System Management:

Your Name » System management » Users » SRV » Generic user sync access

Scroll to the bottom of the right hand pane to view the API keys.

All user sync API keys should have /api/haplo-user-sync/ as the Request path to restrict them to just the user sync APIs.

Control files

The control file is uploaded with the _control name, and should be uploaded as the first file. If it is not uploaded for a sync run, the previous control file will be used.

API

The user sync API uses two endpoints on the application. Both must be authenticated using HTTP basic authentication with the haplo username and an API key as the password.

POST /api/haplo-user-sync/upload-file

The request body must be multipart/form-data encoded, and contain two parameters:

name – the name of the file, matching an entry in the files property of the control file.

file – the data file. The filename of this file is ignored.

As a special case, if the name is _control, then the control file is replaced with the file.

Files do not all need to be uploaded from the same server, as long as the request to start the sync happens after they have all been uploaded.

If this API succeeds, the response will have a 200 status status code and the body will be a JSON document with three properties:

`digest`	SHA256 digest of the uploaded file
`fileSize`	Size of the uploaded file in bytes
`filename`	Filename of the uploaded file

For example,

{
    "digest": "bb0216c6ec24c67658a8257733a47504f4131ef8a116b1085eda7f00932fb057",
    "fileSize": 189373,
    "filename": "users.xml"
}

If this API fails, a non-200 status code will be returned.

POST /api/haplo-user-sync/start-sync

After all files have been uploaded, make a POST request this endpoint to start the sync run. An error will be returned if not all files have been uploaded yet.

If automatic apply of the user sync has been disabled in the admin user interface, or the files are too different from the previous run (for example, their size differs by more than 10%), then a manual action will be needed to apply the sync.

The first run will always need a manual apply.

This API will by default return a text/plain body with a human readable description of the status of the sync.

If the user sync has all the files required, a 200 status code will be returned, otherwise a non-200 status code is returned.

There are alternative APIs available if a structured response is required. Unlike the default API, the alternatives will return a 200 status cade even if the required files have not all been uploaded. The structured response will contain the following values:

`status`	The status of the user sync. Possible values are: `queued-for-apply`, `missing-files`, and `admin-intervention-required`
`error`	Whether an error has occurred
`message`	A human readable explanation of the state

JSON

The first alternative is returning the data in JSON format. This can be used by POSTing to /api/haplo-user-sync/start-sync/json.

Example response:

{
    "status": "queued-for-apply",
    "error": false,
    "message": "OK. Sync queued."
}

XML

Another alternative is returning the data in XML format. This can be used by POSTing to /api/haplo-user-sync/start-sync/xml. The message value is the text of the sync element, while the error and status values are stored as attributes on it.

Example response:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response>
    <sync error="false" status="queued-for-apply">OK. Sync queued.</sync>
</response>