System Endpoints

There are some resources available for getting or setting system information and configuration. You can set the Usage Reporting configuration for the server, retrieve the Server Audit Logs, or perform a Direct Backup.

Usage Reporting Configuration

(introduced: version 1.3)

Getting the current configuration

GET /v1/config/analytics

If the Usage Reporting configuration is not set, this endpoint will return a 404. Once the configuration is set, this endpoint will indicate whether the server will share usage data with the Central team. If the server will share usage data, and contact information was provided, this endpoint will also return the provided work email address and organization name.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: application/json

{
  "key": "some_type",
  "setAt": "2018-01-06T00:32:52.787Z",
  "value": {
    "enabled": true,
    "email": "my.email.address@getodk.org",
    "organization": "Organization Name"
  }
}

object

key

string

The type of system configuration.

setAt

string

ISO date format. The last time this system configuration was set.

value

object

Details about the Usage Reporting configuration.

expand

enabled

boolean

true if the server will share usage data with the Central team and false if not.

email

string

The work email address to include with the metrics report.

organization

string

The organization name to include with the metrics report.

HTTP Status: 403

Content Type: application/json

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

number

Example: 403.1

message

string

Example: The authenticated actor does not have rights to perform that action.

HTTP Status: 404

Content Type: application/json

{
  "code": "404.1",
  "message": "Could not find the resource you were looking for."
}

object

code

string

message

string

Setting a new configuration

POST /v1/config/analytics

An Administrator can use this endpoint to choose whether the server will share anonymous usage data with the Central team. This configuration affects the entire server. Until the Usage Reporting configuration is set, Administrators will see a message on the Central administration website that provides further information.

If an Administrator specifies true for enabled, the server will share anonymous usage data monthly with the Central team. By specifying true, the Administrator accepts the Terms of Service and Privacy Policy. The Administrator can also share contact information to include with the report.

If an Administrator specifies false for enabled, the server will not share anonymous usage data with the Central team. Administrators will no longer see the message on the administration website.

If the Usage Reporting configuration is already set, the current configuration will be overwritten with the new one.

Request

Request body

{
  "enabled": true,
  "email": "my.email.address@getodk.org",
  "organization": "Organization Name"
}

object

enabled

boolean

See above.

email

string

A work email address to include with the metrics report.

organization

string

An organization name to include with the metrics report.

Response

HTTP Status: 200

Content Type: application/json

{
  "key": "some_type",
  "setAt": "2018-01-06T00:32:52.787Z",
  "value": {
    "enabled": true,
    "email": "my.email.address@getodk.org",
    "organization": "Organization Name"
  }
}

object

key

string

The type of system configuration.

setAt

string

ISO date format. The last time this system configuration was set.

value

object

Details about the Usage Reporting configuration.

expand

enabled

boolean

true if the server will share usage data with the Central team and false if not.

email

string

The work email address to include with the metrics report.

organization

string

The organization name to include with the metrics report.

HTTP Status: 403

Content Type: application/json

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

number

Example: 403.1

message

string

Example: The authenticated actor does not have rights to perform that action.

Unsetting the current configuration

DELETE /v1/config/analytics

If the Usage Reporting configuration is unset, Administrators will once again see a message on the the Central administration website.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: application/json

{
  "success": true
}

object

success

boolean

HTTP Status: 403

Content Type: application/json

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

number

Example: 403.1

message

string

Example: The authenticated actor does not have rights to perform that action.

Usage Report Preview

(introduced: version 1.3)

An Administrator of Central may opt in to sending periodic reports summarizing usage. Configuration of this reporting is described here. For added transparency, the API provides a preview of the reported metrics.

Getting the Usage Report preview

GET /v1/analytics/preview

An Administrator can use this endpoint to preview the metrics being sent. The preview is computed on the fly and represents what the report would look like if sent at that time. This endpoint does not directly submit the Usage Report; that is handled internally as a scheduled Central task.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 403

Content Type: application/json

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

number

Example: 403.1

message

string

Example: The authenticated actor does not have rights to perform that action.

Server Audit Logs

(introduced: version 0.6)

Many actions on ODK Central will automatically log an event to the Server Audit Log. Creating a new Form, for instance, will log a form.create event, with information about the Actor who performed the action, and sometimes some additional details specific to the event.

Any time an audit action is logged, the request headers are checked. If X-Action-Notes are provided anywhere, those notes will be logged into the audit entries as well. Note that some requests generate multiple audit entries; in these cases, the note will be attached to every entry logged.

Server Audit Logs entries are created for the following actions:

  • user.create when a new User is created.
  • user.update when User information is updated, like email or password.
  • user.assignment.create when a User is assigned to a Server Role.
  • user.assignment.delete when a User is unassigned from a Server Role.
  • user.session.create when a User logs in.
  • user.delete when a User is deleted.
  • project.create when a new Project is created.
  • project.update when top-level Project information is updated, like its name.
  • project.delete when a Project is deleted.
  • form.create when a new Form is created.
  • form.update when top-level Form information is updated, like its name or state.
  • form.update.draft.set when a Draft Form definition is set.
  • form.update.draft.delete when a Draft Form definition is deleted.
  • form.update.publish when a Draft Form is published to the Form.
  • form.attachment.update when a Form Attachment binary is set or cleared.
  • form.submissions.export when a Form's Submissions are exported to CSV.
  • form.delete when a Form is deleted.
  • form.restore when a Form that was deleted is restored.
  • form.purge when a Form is permanently purged.
  • field_key.create when a new App User is created.
  • field_key.assignment.create when an App User is assigned to a Server Role.
  • field_key.assignment.delete when an App User is unassigned from a Server Role.
  • field_key.session.end when an App User's access is revoked.
  • field_key.delete when an App User is deleted.
  • public_link.create when a new Public Link is created.
  • public_link.assignment.create when a Public Link is assigned to a Server Role.
  • public_link.assignment.delete when a Public Link is unassigned from a Server Role.
  • public_link.session.end when a Public Link's access is revoked.
  • public_link.delete when a Public Link is deleted.
  • submission.create when a new Submission is created.
  • submission.update when a Submission's metadata is updated.
  • submission.update.version when a Submission XML data is updated.
  • submission.attachment.update when a Submission Attachment binary is set or cleared, but only via the REST API. Attachments created alongside the submission over the OpenRosa /submission API (including submissions from Collect) do not generate audit log entries.
  • submission.delete when a Submission is soft-deleted.
  • submission.purge when soft-deleted Submissions are purged.
  • submission.restore when a Submission is restored.
  • submission.reprocess when an Entity Submission is held in a processing backlog and then removed.
  • dataset.create when a Dataset is created.
  • dataset.update when a Dataset is updated.
  • dataset.update.publish when a Dataset is published.
  • entity.create when an Entity is created.
  • entity.error when there is an error processing a Submission to create or update an Entity.
  • entity.update.version when an Entity is updated.
  • entity.update.resolve when an Entity conflict is resolved.
  • entity.delete when an Entity is deleted.
  • config.set when a system configuration is set.
  • analytics when a Usage Report is attempted.
  • blobs.s3.upload when blobs are moved from the database to external storage.
  • blobs.s3.failed-to-pending when blobs that failed to upload are reset to the pending state to be retried.
  • Deprecated: backup when a backup operation is attempted for Google Drive backups.

Getting Audit Log Entries

GET /v1/audits

This resource allows access to those log entries, with some paging and filtering options. These are provided by querystring parameters: action allows filtering by the action types listed above, start and end allow filtering by log timestamp (see below), and limit and offset control paging. If no paging parameters are given, the server will attempt to return every audit log entry that it has.

The start and end parameters work based on exact timestamps, given in ISO 8601 format. It is possible to provide just a datestring (eg 2000-01-01), in which case midnight will be inferred. But this value alone leaves the timezone unspecified. When no timezone is given, the server's local time will be used: the standard Docker deployment will always set server local time to UTC, but installations may have been customized, and there is no guarantee the UTC default hasn't been overridden.

For this reason, we recommend always setting a timezone when querying based on start and end: either by appending a z to indicate UTC (eg 2000-01-01z) or by explicitly specifying a timezone per ISO 8601 (eg 2000-01-01+08). The same applies for full timestamps (eg 2000-01-01T12:12:12z, 2000-01-01T12:12:12+08).

start may be given without end, and vice versa, in which case the timestamp filter will only be bounded on the specified side. They are both inclusive (>= and <=, respectively).

This endpoint supports retrieving extended metadata; provide a header X-Extended-Metadata: true to additionally expand the actorId into full actor details, and acteeId into full actee details. The actor will always be an Actor, but the actee may be an Actor, a Project, a Form, or some other type of object depending on the type of action.

Request

Parameters

action

(query)

string

The name of the action to filter by.

Example: form.create

start

(query)

string

The timestamp before which log entries are to be filtered out.

Example: 2000-01-01z

end

(query)

string

The timestamp after which log entries are to be filtered out.

Example: 2000-12-31T23:59.999z

limit

(query)

number

The maximum number of entries to return.

Example: 100

offset

(query)

number

The zero-indexed number of entries to skip from the result.

Example: 200

Response

HTTP Status: 200

Content Type: application/json

[
  {
    "actorId": 42,
    "action": "user.session.create",
    "details": {
      "userAgent": "Mozilla/5.0"
    },
    "acteeId": "85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "loggedAt": "2018-04-18T23:19:14.802Z"
  }
]

array

actorId

number

The ID of the actor, if any, that initiated the action.

Example: 42

action

string

The action that was taken.

Example: form.create

acteeId

string

The ID of the permissioning object against which the action was taken.

Example: 85cb9aff-005e-4edd-9739-dc9c1a829c44

details

object

Additional details about the action that vary according to the type of action.

loggedAt

string

ISO date format

Example: 2018-04-18T23:19:14.802Z

HTTP Status: 200

Content Type: application/json; extended

[
  {
    "actorId": 42,
    "action": "form.create",
    "details": {
      "userAgent": "Mozilla/5.0"
    },
    "acteeId": "85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "loggedAt": "2018-04-18T23:19:14.802Z",
    "actor": {
      "createdAt": "2018-04-18T23:19:14.802Z",
      "displayName": "My Display Name",
      "id": 115,
      "type": "user",
      "updatedAt": "2018-04-18T23:42:11.406Z",
      "deletedAt": "2018-04-18T23:42:11.406Z"
    }
  }
]

array

actorId

number

The ID of the actor, if any, that initiated the action.

Example: 42

action

string

The action that was taken.

Example: form.create

acteeId

string

The ID of the permissioning object against which the action was taken.

Example: 85cb9aff-005e-4edd-9739-dc9c1a829c44

details

object

Additional details about the action that vary according to the type of action.

loggedAt

string

ISO date format

Example: 2018-04-18T23:19:14.802Z

actor

object

expand

createdAt

string

ISO date format

Example: 2018-04-18 23:19:14.802000+00:00

displayName

string

All Actors, regardless of type, have a display name

Example: My Display Name

id

number

Example: 115.0

type

enum

The type of actor

expand

user

string

field_key

string

public_link

string

singleUse

string

updatedAt

string

ISO date format

Example: 2018-04-18 23:42:11.406000+00:00

deletedAt

string

ISO date format

Example: 2018-04-18 23:42:11.406000+00:00

actee

object

The details of the actee given by acteeId. Depending on the action type, this could be a number of object types, including an Actor, a Project, or a Form.

HTTP Status: 400

Content Type: application/json

{
  "code": "400",
  "message": "Could not parse the given data (2 chars) as json."
}

object

code

number

Example: 400

details

object

a subobject that contains programmatically readable details about this error

message

string

Example: Could not parse the given data (2 chars) as json.

HTTP Status: 403

Content Type: application/json

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

number

Example: 403.1

message

string

Example: The authenticated actor does not have rights to perform that action.

Direct Backup

(introduced: version 1.1)

ODK Central offers an HTTP endpoint that will immediately perform a backup on the system database and send that encrypted backup as the response. To use it, POST with an encryption passphrase.

Note that performing the backup takes a great deal of time, during which the request will be held open. As a result, the endpoint will trickle junk data every five seconds while that processing is occurring to prevent the request from timing out. Depending on how much data you have, it can take many minutes for the data stream to speed up to a full transfer rate.

Using an Encryption Passphrase

POST /v1/backup

Use the POST verb to start a direct download ad-hoc backup. You will want to supply a passphrase with your chosen encryption passphrase. It is possible to omit this, in which case the backup will still be encrypted, but it will decrypt given an empty passphrase.

Please see the section notes above about the long-running nature of this endpoint.

Request

Request body

{
  "passphrase": "my-password"
}

object

passphrase

string

The passphrase with which to encrypt the backup.

Response

HTTP Status: 403

Content Type: application/json

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

number

Example: 403.1

message

string

Example: The authenticated actor does not have rights to perform that action.

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No