API Integration Guide

Crisisworks has a mature web services API that provides REST and RPC access to key data and functionality.  This document provides details for system integrators to develop clients to connect, extract data and control Crisisworks.

On this page

Introduction

Crisisworks offers a unified web services endpoint for both REST (Representational State Transfer) and RPC (Remote Procedure Call) commands. Some commands are RESTful while others implement an RPC interface. All commands use HTTPS as the transport, and support the common HTTP/1.1 verbs such as GET, POST, PUT, PATCH and DELETE.  

The general format for accessing the API is:

https://site.crisisworks.com/api/adapter/command?param=value&token=XXX

This comprises the following components:

site

Your Crisisworks site URL

adapter

Your selected data adapter; this transforms the data to the appropriate format

command

The command to run

param

Zero or more parameters and their corresponding values — see each command for details

token

Your authentication token, if required. 

The API supports different adapters to read and write the data contained within the HTTPS transport. The default and recommended transport is JSON, which reads and writes the data in JavaScript Object Notation.

Adapter

Format

Description

Adapter

Format

Description

json

Javascript Object Notation

The default and recommended adapter, whcih reads and writes JSON data using native Crisisworks JSON structures.

csv

Comma Separated Values

This adapter reads and writes data in CSV format, providing ready compatibility to many legacy systems. Due to the nature of CSV as a flat file format, complex linked structures cannot be represented, so it is only recommended for simpler integrations.

geojson

GeoJSON

A read-only adapter that returns JSON data in the open GeoJSON format. This provides ready compatibility for many geospatial platforms such as web mapping systems including OpenLayers and Leaflet.

binary

Binary

A binary response is used by some APIs (for example, file) to return the raw source file

rss

RSS XML

A read-only adapter that returns the data in RSS format with the geospatial extension. This provides ready compatibility for RSS readers and news ticker systems.

Example: Calling the "ping" diagnostic command

$ curl https://demo.crisisworks.com/api/json/ping "2016-10-24T05:34:46+00:00"

Working with Authentication

Most APIs require authentication, and in order to use any authenticated API, you must first acquire a valid API token.

To do this, first call the register API command, and supply the user credentials to retrieve a token. From then on, supplying that token to authenticated API commands will perform the command on behalf of that user.

Crisisworks account & Duty Status

The API uses a regular Crisisworks account. We recommend that this account is only used for the API, as such give it a name like API User.

Ensure this user has the levels of access required to access the data it needs to view or edit for the specific registers.

If this API user is going to edit data in registers, the API user MUST BE ON DUTY in the event in one or more positions to have access to read or write data in the registers.

If the API user is only updating assets or asset contacts, this data is not in a register, so they don't need to be on duty in any events.

 

 

Fetching an API token

The register command takes a username and password and returns a token for use in using authenticated API commands.

Inputs

The register API command takes the following parameters in a JSON payload within a POST method:

Parameter

Type

Mandatory

Description

Parameter

Type

Mandatory

Description

uuid

string

Yes

A unique code that represents the connected device. For devices this is the device's UUID code. For servers, this should be the server's URL.

platform

string

Yes

A freetext string representing the type of connection — e.g. iPad, iPhone, Windows

version

string

Yes

The version of the client software

name

string

Yes

The name of the device — e.g. "Steve's iPad Pro"

username

string

Yes

The user username

password

string

Yes

The user's password

expiry

string

No

An optional date YYYY-MM-DD for token expiry, used for setting up integration endpoints. This must be within the overall configured expiry policy limits set for your service.

Results

If the user is successfully authenticated, the command returns a JSON object with the following values:

Key

Type

Description

Key

Type

Description

token

string

An API token which can be used to perform actions on behalf of a nominated user

htmlHtml

string

An HTML snippet that can be displayed in client software containing help and support information for Crisisworks

If the user's credentials are invalid, the server responds with a 401 HTTP error.

Example: calling the "register" command to fetch an API token

Example
$ curl -X POST \ -H "Accept: application/json" \ -H "Content-Type: application/json;charset=UTF-8" \ -d '{ "uuid": "$YOUR_DEVICE_UUID", "platform": "$YOUR_CLIENT_PLATFORM", "version": "1", "name": "$YOUR_CLIENT_NAME", "username": "$YOUR_USERNAME", "password": "$YOUR_PASSWORD" }' \ "https://$SITE_URL/api/json/register" { "token": "8162e97a0fabf76b3bf0b1bfa50e90e8", "helpHtml": "Visit <a target=\"_blank\" href=\"http:\/\/www.crisisworks.com\/support\" target=\"_blank\">Crisisworks Online Support<\/a> for help and support" }

Using a token to access secure API commands

Once you have acquired a token, it must be supplied to any calls requiring authentication by using the Authorization header. Note that the header must be in the following format (take special note of spaces):


Example: supplying the token in the Authorization header

It is also possible to supply the token and uuid as part of the request parameters, however this is discouraged.

Working with RPC APIs

RPC APIs are simply a remote call to procedure on the server.

They use GET for read actions and POST for write actions, and accept payload formats based on the adaptor in use (e.g. "json").

Example: calling the "ping" command



Example

Working with REST APIs

REST provides a consistent URI for access and manipulation of a specific data record.

Under REST, a single URI represents a data record, and the HTTP verb controls the manipulation according to the following table:

Method

Description

Example

Method

Description

Example

Collection Commands

GET

Returns a collection of items based on a filter

GET /api/json/item?event=123

POST

Creates a new item

POST /api/json/item

Record Commands

GET

Returns a single item

GET /api/json/item/id/1

PUT

Updates a single item

PUT /api/json/item/id/1

PATCH

Updates a single item with the supplied fields only

PATCH /api/json/item/id/1

DELETE

Deletes a single item

DELETE /api/json/item/id/1

Collections

The Crisisworks REST API returns either returns a single object or a collection of objects, based on its invocation.

Collections contain the following JSON structure:

In the collection structure:

  • models contains an array of individual model structures, 

  • count contains the number of returned objects, and 

  • total contains the total set (this will be different if you call the API with a limit and/or offset parameter to paginate the set).

Fetching a single record

Use the GET method and supply an 'id' parameter to fetch a single record.

Each command returns records of a specific schema, and the example below is made up and not valid. Consult the command reference for details of the specific model.

Example

Note: The contents of the record structure depends on the type of content being retrieved.

Fetching a collection of records

Fetching a collection of RESTful objects is achieved by calling its base URL without an identifier. e.g.

Filters can be added, depending on the object. e.g.

Example

Paginating records

You can paginate large result-sets by taking note of the count and total values returned in the payload, and supplying limit and offset parameters in the request.

For example, to fetch 100 at a time:

Will return

You can then fetch the second set:

And the final set

Submitting new records

New records can be submitted using POST. 

  • JSON Input follows the same structure as that returned from the GET API.

  • The JSON response reflects the final values of the record after being saved.

  • Possible error codes include 40x and 50x status codes. All have a human-readable message, and use http codes so you can follow that spec to know whether it's a temporary or permanent error.



Example

Note: it is not normal to submit such a short request, but it makes for a good example.

 

Updating existing records

To update an existing record, use PUT or PATCH.

PUT and PATCH work similarly, where:

  • PUT expecting a full record, while 

  • PATCH expects a change-set. 

Tip: When using PUT, missing data will be treated as if the value is set to null, and this will overwrite existing values at the server.

Possible error codes include 40x and 50x codes, as usual.

Example

DELETE

Delete can be called if the object supports it.

Certain RESTful commands may not allow deletions, in which case a 400 Bad Request will be returned. For those that do implement it, a 200 code will be returned on success, and 40x and 50x codes will be returned on failure.



Example

API Command Reference

The following public API commands are available:

API Command

URL

Type

Methods

Authenticated

Description

API Command

URL

Type

Methods

Authenticated

Description

asset

/api/json/asset

REST

GET, POST, PUT, PATCH, DELETE

Yes

Create, retrieve and delete assets from the system

asset-type

/api/json/asset-type

RPC

GET

Yes

Read-only access to look up asset types

create-event

/api/json/create-event

RPC

POST

Yes

A simple method to create events, usually based on existing templates

event

/api/json/event

REST

GET

Yes

Retrieve events and update them

file

/api/binary/file

RPC

GET, POST

Yes

Upload and retrieve file attachments. Note, this command only uses the binary adapter, and returns JSON on failure.

item

/api/json/item

REST

GET, POST, PUT, PATCH, DELETE

Yes

Create, retrieve and delete register items, which are the core operational record in Crisisworks.

log

/api/json/log

REST

GET

Yes

Read-only access to audit logs

media

/api/json/media

REST

GET, POST, PUT, PATCH, DELETE

Yes

Create, retrieve and delete media attachments on register items

ping

/api/json/ping

RPC

GET

No

A diagnostics command for debugging and uptime analysis

register

/api/json/register

RPC

POST

No

Register a username/password against a device and retrieve an API token

resource

/api/json/resource

REST

GET, POST, PUT, PATCH, DELETE

Yes

Create, retrieve and delete resources

user

/api/json/user

REST

GET, POST, PUT, PATCH, DELETE

Yes

Create, retrieve and delete users.

user-position

/api/json/user-position

RPC

POST

Yes

Update the current latitude/longitude of a user

participant

/api/json/participant

REST

GET

Yes

Search for participants by event, type and/or query string

import

/api/json/import

RPC

POST

Yes

Schedule an import job, or check on the status of a scheduled job.

These commands are mostly authenticated, and are either RPC or REST APIs. See below the more details on each command.

Asset (REST)

The asset REST command returns and manipulates assets in Crisisworks.

GET Parameters

Parameter

Key(s)

Type

Available Operators

Details

Parameter

Key(s)

Type

Available Operators

Details

Limit

limit

Number

-

When paginating, how many records to return

Offset

offset

Number

-

When paginating, which record to start from

Token

token

String

-

The API token to authenticate

ID

  • id

  • id_operator

Integer

  • equals (default)

  • in

Returns a record of a specific ID (equals), or a collection of records within a comma-separated list of IDs (in).

Contains

  • fulltext

  • fulltext_operator

String

  • Contains (default)

  • NotContains

Returns records containing the supplied text, as analysed by the full-text search parser.

Sounds Like

  • soundex

String

-

Returns records where the title sounds like the supplied string


Aliases: name

Active

  • active

Boolean

-

Returns only active (or inactive) records based on supplied value

Type

  • type

  • type_operator

String

  • Equals (default)

  • In

  • NotIn

  • IsNotBlank

  • IsBlank

Returns records matching the given asset type. For a list of asset types, see the asset-type API command.

Code

  • code

String

-

Returns records matching the given asset code

Is Impacted

  • isImpacted

Boolean

-

Returns records that have an active register item record in Crisisworks

Near

  • latitude

  • longitude

  • range

Number

-

Returns assets near the provided geospatial location.



Example



Asset Type (REST)

This command fetches the available asset types.

This command is read-only and only supports the GET REST method.



Example

Asset Lookup

The Asset Lookup API provides search and lookup capability for Crisisworks API clients, using the same underlying algorithms used by the item import and asset matching systems.

There are two modes of operation:

  • Single query mode — look up a single asset 

  • Multiple query mode — process multiple items in a batch

Single Query Mode

Parameter

Purpose

Parameter

Purpose

query

The string to look up as an asset

output

One of id or asset (default)

key=val

A range of options can be supplied to fine-tune the system. See below for details of the available option keys.

Multiple Query Mode

To process multiple queries at once, construct a JSON payload and pass it via POST.

The result of either call will be formatted in an object map of results, keyed based on the supplied code parameter, or as a 1-based record count if no code was supplied. The object will either be a full asset object (output=asset, or an asset ID output=id).

Options

These additional options are available

Parameter

Purpose

Parameter

Purpose

mode

One of the modes described here. The default is the soundex mode.

assetClass

Optionally limits results to only those matching this asset class.

useExternalLookups

Defaults to true, and engage the Google POI search as a last resort if other methods have failed.

maxRank

For soundex searches, the maximum rank (1 = exact, 2 = all word in order, 3 = all words in any order). Default is 2.

fallbackMode

An optional second fallback mode for if the primary fails

codeField

For mode=code, this is the field to match upon (e.g. propnum)

upgradeExternalLookupToInternalAsset

If the fallback POI system is invoked, you can optionally attempt to upgrade the result to a proper asset. To use this feature, you need to also specify thee assetClass. You may also want to set the geocoderOptions to rooftop-level resolution (seee below), otherwise you will get nearby but not exact properties if the search returns only a nearby road.

geocoderOptions

For useExternalLookups, this is a JSON options array to configure the plugin. The most useful option is restrict matches to houses only:

Example: Look up a single address

Result



Example: Look up multiple addresses 

Result:

Create Event (RPC)

This command provides an easy way to create events, usually based on existing event templates

Example

Parameters

Key

Type

Required?

Default

Details

Key

Type

Required?

Default

Details

templateId

Number

No

ID of "Basic" template

The template event ID to base this new event on.

title

String

Yes

(None)

The title of the event

description

String

No

(None)

An optional description of the event

startDate

Date Time String

No

Current date/time

The time that the event is scheduled to begin

endDate

Date Time String

No

(None)

The time that the event is scheduled to end

status

Number

No

The default state for new events (Usually 1 → "Open"

The status that the event should be set to when created

severity

Number

No

1

1=Test only, 2=Low Severity, 3=Moderate Severity, 4=High Severity

goOnDuty

Number

No

1

Should the user creating the event automatically go on duty for all candidate positions in the event? 1 = Yes, 0 = No



Duty (RPC)

This command provides a way to go on or off duty in an event

Example

Parameters

Key

Type

Required?

Default

Details

Key

Type

Required?

Default

Details

participantId

Number

Yes

(None)

The ID of the participant to go on duty as

onDuty

Number

Yes

1

0 = go off duty, 1 = go on duty

Event (REST)

This command fetches available events, and allows updating.

Fetch Individual Event

Example

Search Events

Example

Parameters

Filter

Keys

Type

Operators

Details

Filter

Keys

Type

Operators

Details

limit

Limit

Number

-

When paginating, how many records to return

offset

Offset

Number

-

When paginating, which record to start from

token

Token

String

-

The API token to authenticate

ID

  • id

  • id_operator

Number

  • equals (default)

  • notEquals

  • in

Set id_operator to the desired operator if changing from the default

Contains

  • fulltext

  • fulltext_operator

String

  • Contains (default)

  • NotContains

Set fulltext_operator to the desired operator if changing from the default

Status

  • status

  • status_operator

String

  • Equals (default)

  • In

  • NotIn

  • IsNotBlank

  • IsBlank

  • IsStatusActive

  • IsStatusInactive

Set status_operator to the desired operator if changing from the default

Active

  • active

Boolean

None

Aliases: isActive

Title

  • title

  • title_operator

String

  • Equals

  • NotEquals

  • Contains (default)

  • NotContains

  • BeginsWith

  • IsBlank

  • IsNotBlank

Set title_operator to the desired operator if changing from the default

Severity

  • severity

  • severity_operator

Number

  • Equals (default)

  • In

  • NotIn

  • IsNotBlank

  • IsBlank

Set severity_operator to the desired operator if changing from the default

Registers

  • registers

  • registers_operator

String

  • Equals (default)

  • In

  • NotIn

  • IsNotBlank

  • IsBlank

Set registers_operator to the desired operator if changing from the default

Started After

  • startDateAfter

  • startDateAfter_operator

Date Time String

  • Equals

  • DateFuzzy

  • NotEquals

  • IsBlank

  • IsNotBlank

  • DateBefore

  • DateBeforeEquals

  • DateAfter

  • DateAfterEquals (default)

  • DateBeforeRel

  • DateAfterRel

Set startDateAfter_operator to the desired operator if changing from the default

Started Before

  • startDateBefore

  • startDateBefore_operator

Date Time String

  • Equals

  • DateFuzzy

  • NotEquals

  • IsBlank

  • IsNotBlank

  • DateBefore

  • DateBeforeEquals

  • DateAfter

  • DateAfterEquals (default)

  • DateBeforeRel

  • DateAfterRel

Set startDateBefore_operator to the desired operator if changing from the default

Event Structure

  • descendants

  • descendants_operator

String

  • NestedSetHasDescendants (default)

  • NestedSetNoDescendants

Set descendants_operator to the desired operator if changing from the default

Tag

  • tag

  • tag_operator

String

  • Tagged (default)

  • NotTagged

Set tag_operator to the desired operator if changing from the default

Location

  • geo

  • geo_operator

  • geo_polygon

  • geo_radius

  • geo_centre

Geo

  • GeoWithinPolygon (default)

  • GeoWithinRange

  • GeoWithinBoundingBox

Set geo_operator to the desired operator if changing from the default

Template

  • isTemplate

Boolean

None



Global

  • isGlobal

Boolean

None



Counter ID

  • counter

Number

None

Aliases: counterId

User Participation

  • participation

  • participation_operator

String

  • (default)

  • active

  • notActive

  • ever

  • can

Set participation_operator to the desired operator if changing from the default

Example: Fetch the most recent event

Update Event

Parameters

Key

Type

Required?

Details

Key

Type

Required?

Details

id

Number

Yes

ID of the event to update

title

String

No

Changed title

description

String

No

Changed description

startDate

Date Time String

No

Changed start date

endDate

Date Time String

No

Changed end date

status

Number

No

New status (generally, 1 = open, -1 = closed)

severity

Number

No

1=Test only, 2=Low Severity, 3=Moderate Severity, 4=High Severity


Example: Close an event and update its description

File Attachment (RPC)

Documentation is currently unavailable for this command

Register Item (REST)

A RESTful command to access and manage register items, which are the primary business object within the system.

GET Parameters

In addition to the standard filters listed below, each register may also have a list of additional filters. Please consult the register guide or contact Datalink's Service Desk for more details.

Filter

Keys

Type

Operators

Details

Filter

Keys

Type

Operators

Details

limit

Limit

Number

-

When paginating, how many records to return

offset

Offset

Number

-

When paginating, which record to start from

token

Token

String

-

The API token to authenticate

Contains

  • contains

  • contains_operator

String

  • Contains (default)

  • NotContains

Aliases: search; Set contains_operator to the desired operator if changing from the default

Record ID

  • itemId

  • itemId_operator

String

  • equals (default)

  • notEquals

  • in

Aliases: id; Set itemId_operator to the desired operator if changing from the default

System ID

  • systemId

  • systemId_operator

String

  • Equals (default)

  • NotEquals

  • Contains

  • NotContains

  • BeginsWith

  • IsBlank

  • IsNotBlank

Set systemId_operator to the desired operator if changing from the default

Type

  • type

  • type_operator

String

  • Equals (default)

  • In

  • NotIn

  • IsNotBlank

  • IsBlank

Aliases: class; Set type_operator to the desired operator if changing from the default

User ID

  • userId

  • userId_operator

String

  • equals (default)

  • notEquals

  • in

  • CurrentUser

  • NotCurrentUser

Aliases: user; Set userId_operator to the desired operator if changing from the default

Event

  • eventId

  • eventId_operator

String

  • InEvent (default)

  • InSubEvent

  • InEventOrSubEventOrGlobal

  • InActiveEvent

  • ActiveParticipating

  • Active

  • Any

Aliases: event; Set eventId_operator to the desired operator if changing from the default

Since

  • since

  • since_operator

String

  • Equals

  • DateFuzzy

  • NotEquals

  • IsBlank

  • IsNotBlank

  • DateBefore

  • DateBeforeEquals

  • DateAfter (default)

  • DateAfterEquals

  • DateBeforeRel

  • DateAfterRel

Set since_operator to the desired operator if changing from the default

Until

  • until

  • until_operator

String

  • Equals

  • DateFuzzy

  • NotEquals

  • IsBlank

  • IsNotBlank

  • DateBefore (default)

  • DateBeforeEquals

  • DateAfter

  • DateAfterEquals

  • DateBeforeRel

  • DateAfterRel

Set until_operator to the desired operator if changing from the default

Is a template item

  • isTemplate

String

None



Counter ID

  • counter

String

None

Aliases: counterId



  • eventImplicit

  • eventImplicit_operator

String

  • InEvent (default)

  • InSubEvent

  • InEventOrSubEventOrGlobal

  • InActiveEvent

  • ActiveParticipating

  • Active

  • Any

Set eventImplicit_operator to the desired operator if changing from the default

Output

Example output of all active fpn items.  Note, the first item has an attached asset and shows how the extra fields are returned.

The external identifier for the item assets depends on what code field is configured for the site.  Prior to 2019 this was exposed via the asset_code field. From 2019, one of the sub-fields from asset_extra should be used as appropriate e.g asset_extra.propnum.

Example

POST|PUT|PATCH

Creating (POST) and updating (PUT or PATCH) items uses a similar structure to the GET response, but only sends one item.

For example:

Matching assets 

When linking an asset to an item, you have three approaches:

  • set assetId to the Crisisworks internal ID for the asset,

  • set asset_friendly to a name, and have Crisisworks look up the asset using a its search algorithm, or

  • set asset_lookup to look up a foreign key for the asset, that will match one of the stored foreign keys in the asset's extra property. For example, you can look up by propnum or crefno, if those foreign keys are in your asset dataset. To determine which code to look up, you can specify asset_codefield.

Example: looking up a property by propnum.

Example: looking up a property by a name search:

Audit Log

This fetches a collection of audit logs, either for a given object (with itemId specified), a given event (with eventId specified) or across the system.

GET Parameters

Filter

Keys

Type

Operators

Details

Filter

Keys

Type

Operators

Details

limit

Limit

Number

-

When paginating, how many records to return

offset

Offset

Number

-

When paginating, which record to start from

token

Token

String

-

The API token to authenticate

ID

  • id

  • id_operator

String

  • Equals (default)

  • NotEquals

  • Contains

  • NotContains

  • BeginsWith

  • IsBlank

  • IsNotBlank

Set id_operator to the desired operator if changing from the default

Event

  • eventId

  • eventId_operator

String

  • InEvent (default)

  • InSubEvent

  • InEventOrSubEventOrGlobal

  • InActiveEvent

  • ActiveParticipating

  • Active

  • Any

Aliases: event; Set eventId_operator to the desired operator if changing from the default

Scope

  • scope

String

None



Item

  • itemId

String

None

Aliases: item

Organisation

  • organisationId

String

None

Aliases: organisation

Participant

  • participantId

String

None

Aliases: participant

Position

  • positionId

String

None

Aliases: position

Register

  • registerId

String

None

Aliases: register

User

  • userId

  • userId_operator

String

  • equals (default)

  • notEquals

  • in

  • CurrentUser

  • NotCurrentUser

Set userId_operator to the desired operator if changing from the default

User Object

  • userObjectId

String

None



Assignment

  • assignmentId

String

None

Aliases: assignment

Event (Implicit)

  • eventImplicit

  • eventImplicit_operator

String

  • InEvent (default)

  • InSubEvent

  • InEventOrSubEventOrGlobal

  • InActiveEvent

  • ActiveParticipating

  • Active

  • Any

Set eventImplicit_operator to the desired operator if changing from the default

 

Example

Register Item Media (REST)

Ping (RPC)

This command provides simple diagnostics, and is the "hello world" of API connectivity.

Example

 

Device Registration (RPC) — Authentication

This command authenticates a username/password, registers the device and returns an API token for that device.

This command is an RPC command that supports the POST method.

Example

Resource (REST)

This command provides a RESTful way to access and manage resources within the system.

GET Parameters

Filter

Keys

Type

Operators

Details

Filter

Keys

Type

Operators

Details

limit

Limit

Number

-

When paginating, how many records to return

offset

Offset

Number

-

When paginating, which record to start from

token

Token

String

-

The API token to authenticate

ID

  • id

  • id_operator

String

  • equals (default)

  • notEquals

  • in

Set id_operator to the desired operator if changing from the default

Contains

  • fulltext

  • fulltext_operator

String

  • Contains (default)

  • NotContains

Set fulltext_operator to the desired operator if changing from the default

Type

  • type

  • type_operator

String

  • Equals (default)

  • In

  • NotIn

  • IsNotBlank

  • IsBlank

Set type_operator to the desired operator if changing from the default

Status

  • status

  • status_operator

String

  • Equals (default)

  • In

  • NotIn

  • IsNotBlank

  • IsBlank

  • IsStatusActive

  • IsStatusInactive

Set status_operator to the desired operator if changing from the default

Organisation

  • organisationId

  • organisationId_operator

String

  • In (default)

  • NotIn

Set organisationId_operator to the desired operator if changing from the default

Category

  • categoryId

  • categoryId_operator

String

  • Equals (default)

  • In

  • NotIn

  • IsNotBlank

  • IsBlank

Set categoryId_operator to the desired operator if changing from the default

Tagged

  • tag

  • tag_operator

String

  • Tagged (default)

  • NotTagged

Set tag_operator to the desired operator if changing from the default



Example

User (REST)

Provides a RESTful way to access and manage users.

GET Parameters

Filter

Keys

Type

Operators

Details

Filter

Keys

Type

Operators

Details

limit

Limit

Number

-

When paginating, how many records to return

offset

Offset

Number

-

When paginating, which record to start from

token

Token

String

-

The API token to authenticate

Word Search

  • fulltext

  • fulltext_operator

String

  • Contains (default)

  • NotContains

Set fulltext_operator to the desired operator if changing from the default

ID

  • id

  • id_operator

String

  • equals (default)

  • notEquals

  • in

Aliases: id; Set id_operator to the desired operator if changing from the default

Online

  • online

Boolean

None



On Duty

  • onduty

Boolean

None



Active

  • active

Boolean

None



On Call

  • oncall

Boolean

None



Tags

  • tag

  • tag_operator

String

  • Tagged (default)

  • NotTagged

Set tag_operator to the desired operator if changing from the default

Organisation

  • organisationId

  • organisationId_operator

String

  • In (default)

  • NotIn

Set organisationId_operator to the desired operator if changing from the default

Competencies

  • roleId

  • roleId_operator

Number

  • RelatedTo (default)

  • NotRelatedTo

Set roleId_operator to the desired operator if changing from the default

Receive SMS

  • receiveSMS

Boolean

None



Receive Email

  • receiveEmail

Boolean

None




Example

Participant (RPC)

A read-only command to search for participants by event, type, and optional query string (eg users name)

GET Parameters

Key

Type

Required?

Default

Details

Key

Type

Required?

Default

Details

event

Number

Yes

(None)

The ID of the event.

query

String

No

(None)

The full name of a participant.

types[]

String

No

(None)

The type of participants to return, including 'User', 'Resource' and 'Position'.

This key may be repeated to return multiple participant types.

Import (POST)

An RPC command to schedule an import job, or to check the status of an existing import job.

To learn about importing, see the section Importing Data into Crisisworks. This API provides an endpoint to replace the user interface version of the import process described in that support article.

Scheduling an import

Parameters

Key

Type

Required

Default

Notes

Key

Type

Required

Default

Notes

General settings

mode

string

Y



Must be set to schedule

importType

string

Y



One of itemuser or asset. Most types are "item" imports.

importRule

string

Y



The rule name.

See the inline import documentation in the Crisisworks Import user interface for details, or contact Datalink's service desk for information.

Data

data

string

Y



Either plaintext or a base64-encoded string of import data

dataType

string

N



Not usually required, but can help the import system determine the file type in the event it cannot automatically determine the file type.

Advice can be provided by Datalink's service desk if needed.

encoding

plain|base64



plain

Sets the type of data. For CSV imports use plain, otherwise base64 encode the file.

Rule processing

matchingId

string

N



This is the name of the field used to match existing records. Valid field names are based on the record being imported.

Examples for importing register items:

  • id: is the Crisisworks ID of the record

  • code: for register items, this is the asset's configured code (e.g. PROPNUM). This configuration is system-wide, so consult Datalink's service desk for your system's configuration. 

  • assetId: for register items, this is the linked Crisisworks Asset ID of the record

overwriteRule

string

N



Defines the rule used for overwriting matched records:

  • updateOnly: If a record matches then update it. If it doesn't match, do not insert it.

  • insertOnly: If a record matches then skip it. If it doesn't match, insert it.

  • updateAndInsert: If a record matches then update it. If it doesn't match, insert a new record.

  • deleteAndInsert: Delete all existing records and insert all records as new records.

eventId

integer

Depends



Required for import types that are stored within events (e.g. items, contacts, cases, documents). Not required for import types such as users, assets and resources.

regionId

integer

Depends



Required for import types that are stored within events (e.g. items, contacts, cases, documents). Not required for import types such as users, assets and resources.

Import settings

dryRun

integer (0 or 1)

N

0

Set to 1 to have the system perform a dry run

rollbackOnError

integer (0 or 1)

N

0

Set to 1 to have the import system roll back the changes if any error occurs

importTag

string

N



If set, all records will be tagged with this tag.

message

string

N



If set, the audit log will contain this message.











Supported data types

This API receives its data in a JSON payload, however imports are generally accepted in different formats such as Shapefile or CSV. The API accepts its data by specifying the parameters datadataType and encoding.

The two most common file formats are CSV and Shapefile. 

For CSV

  1. prepare the data by escaping special characters as per the JSON specification (e.g. backslash quotes, carriage returns, etc),

  2. supply the escaped data in data

  3. set encoding to plain 

  4. set dataType to csv

For Shapefile

  1. zip the shapefile files into a single zip file

  2. base64 encode the zip file

  3. supply the base64 encoded string as data

  4. Set encoding to base64 

  5. Set the dataType to zip

The API will return an ID on success. This ID can be used to query the progress of the import job.

Checking import progress

If called without an id parameter, the API will return a summary of all import jobs. If called with an id parameter, it will return specifics about that job.

You will typically poll this API once a job has been submitted, until the job completes. Please poll no more than once per 60 seconds to not disrupt the user experience.

Key

Type

Description

Key

Type

Description

code

integer

An HTTP result code. Expect 200 for success.

id

integer

The process ID

status

string

A simplified process status, one of NOT_STARTEDRUNNINGCOMPLETE or FAILED

dateCreated

date

The date in GMT that the job was scheduled

dateCompleted

date

The date in GMT that the job finished processing

userId

string

The user that the job ran as

result

string

The result of the import job, as an HTML formatted string

Report (POST)

The /api/json/report API provides report run automation, and allows users to run a report, check its run status and download the results.

To run a report and retrieve the results:

  1. run it — triggers the report to run asynchronously

  2. check status — monitor the report execution via polling to know when it has completed

  3. fetch it — pull down the report results in a number of formats

Running a report

To enqueue a report to run, call the following API.

This API call accepts a JSON document with either a reportId of a known report in the system, or a reportInstanceId of a previous run to repeat. It also optionally allows params to be specified to provide detailed configuration of the report.

Example 1: run a report by its ID

Example 2: run a report based on a previous run

This method is most convenient because you can set up a report’s parameters via the reporting user interface, and then re-run it with the same set of filters, columns and format options. If params are provided, they will overwrite any params of the report instance being re-run.

Results

If successful, the result will return the report instance ID scheduled to run.

Checking a report status

Reports run asynchronously and some can take a while to run, so you can poll this API to check the job’s status.

Results

When initially queued the results will return a QUEUED status:

When complete it will return additional data:

Note the params attribute which will show the params used to run the report. This is useful to return a structured set of parameters from a previous report run, which you can then modify when crafting your own API calls.

Fetching report data

To fetch report data, call the API in fetch mode and specify the reportInstanceId and a format.

Example: fetching a report in JSON

The results of the /api/json/report call with the fetch mode is a JSON document of the same shape as for the status mode, but with an additional contents property.

This contents property contains one of the following:

  • for the json format, the report data in a nested JSON format

  • for all other formats, the binary file is returned in Base-64 encoding

For example, the above example will return the following:

This JSON format provides a tabular (e.g. two-dimensional) data structure in a parsable format, along with a built-in data dictionary for each field.

  • $schema — a JSON Schema document URL to validate the content

  • name — the name of the report

  • meta — a series of metadata values indicating the data quality of the report (as set in the report instance at run-time)

  • filter — all available report filters and their set values for this report

  • spec — a data dictionary of all the fields contained in each data row

  • data — the rows of data

By changing the format to any other supported format, the data is encoded into Base-64 and returned.

Example: fetching data using the binary adapter

Use the binary API adapter to download the report file in its raw format.

Available formats:

Format

Description

Format

Description

csv

A CSV representation of the data

html

A formatted HTML report (compatible reports only)

json

The JSON representation above

xlsx

An Excel spreadsheet

Example: downloading the CSV format directly

A response may look like this:

Different file types will have different Content-Type headers, and will contain binary data. To fetch these, use a tool such as wget or curl like any other HTTP resource of that type:

Further Examples

The following examples provide quick integrations for popular requirements.

Displaying all Fire Prevention Notices on a map using GeoJSON

This example displays a set of icons for each fire prevention notice record in Crisisworks on an OpenLayers map.

Steps

  1. Obtain your authentication token

  2. Prepare and test a URL to fetch the data

  3. Add the URL into OpenLayers

Step 1

First, fetch an API token based on a user account with credentials that provide access to the FPN registers and event.  This is described above in the section Working with Authentication.

Step 2

The following URL will fetch a live list of all FPN records for a given event. Replace site, token and event with your own values.

URL
Example: Testing the URL

Step 3

Add the URL above into your system as a GeoJSON layer.  If developing on OpenLayers, this tutorial explains how to add a GeoJSON layer.

Fetching all Fire Prevention Notices to import into another system using CSV

This example downloads CSV data for import into another system

Steps:

  1. Obtain your authentication token

  2. Prepare and test a URL to fetch the data

  3. Add the URL into OpenLayers

Step 1

First, fetch an API token based on a user account with credentials that provide access to the FPN registers and event.  This is described above in the section Working with Authentication.

Step 2

The following URL will fetch a live list of all FPN records for a given event. Replace sitetoken and event with your own values.

Example

 

Step 3

Now consume the URL in your application. 

Example

Importing asset contacts via the API

Example of importing asset contacts from a CSV file.

Note the data used in this example is embedded CSV within the JSON data. If you have a CSV file, look at the next example.

 

Uploading an import file

The following example shows how you may upload a CSV file to the import API, using BASH.