TDXApi

TDXApi

new TDXApi(config)

Source:

Create a TDXApi instance

Example

standard usage

import TDXApi from "nqm-api-tdx";
const api = new TDXApi({tdxServer: "https://tdx.acme.com"});
Parameters:
Name Type Description
config object

the TDX configuration for the remote TDX

Properties
Name Type Attributes Description
tdxServer string <optional>

the URL of the TDX auth server, e.g. https://tdx.nqminds.com. Usually this is the only host parameter needed, as long as the target TDX conforms to the standard service naming conventions e.g. https://[service].[tdx-domain].com. In this case the individual service hosts can be derived from the tdxHost name. Optionally, you can specify each individual service host (see below). Note you only need to provide the host for services you intend to use. For example, if you only need query services, just provide the query host.
commandServer string <optional>

the URL of the TDX command service, e.g. https://cmd.nqminds.com
queryServer string <optional>

the URL of the TDX query service, e.g. https://q.nqminds.com
databotServer string <optional>

the URL of the TDX databot service, e.g. https://databot.nqminds.com
accessToken string <optional>

an access token that will be used to authorise commands and queries. Alternatively you can use the authenticate method to acquire a token.
accessTokenTTL number <optional>

the TTL in seconds of the access token created when authenticating.
doNotThrow boolean <optional>

set to prevent throwing response errors. They will be returned in the CommandResult object. This was set by default prior to 0.5.x

Methods

abortDatabotInstance(instanceId)

Source:

Aborts a running databot instance.

Parameters:
Name Type Description
instanceId string

The id of the instance to abort.

addAccount(options, waitopt) → {CommandResult}

Source:

Adds an account to the TDX. An account can be an e-mail based user account, a share key (token) account, a databot host, an application, or an account-set (user group).

Parameters:
Name Type Attributes Default Description
options object

new account options

Properties
Name Type Attributes Description
accountType string

the type of account, one of ["user", "token"]
approved boolean <optional>

account is pre-approved (reserved for system use only)
authService string <optional>

the authentication type, one of ["local", "oauth:google", "oauth:github"]. Required for user-based accounts. Ignored for non-user accounts.
displayName string <optional>

the human-friendly display name of the account, e.g. "Toby's share key"
expires number <optional>

a timestamp at which the account expires and will no longer be granted a token
key string <optional>

the account secret. Required for all but oauth-based account types.
owner string <optional>

the owner of the account.
scratchAccess boolean <optional>

indicates this account can create resources in the owners scratch folder. Ignored for all accounts except share key (token) accounts. Is useful for databots that need to create intermediate or temporary resources without specifying a parent resource - if no parent resource is given when a resource is created and scratch access is enabled, the resource will be created in the owner's scratch folder.
settings object <optional>

free-form JSON object for user data.
username string <optional>

the username of the new account. Required for user-based accounts, and should be the account e-mail address. Can be omitted for non-user accounts, and will be auto-generated.
verified boolean <optional>

account is pre-verified (reserved for system use only)
whitelist Array.<string> <optional>

a list of IP addresses. Tokens will only be granted if the requesting IP address is in this list
wait boolean <optional>
 false

flag indicating this method will wait for the account to be fully created before returning.
Returns:
Type
CommandResult

addAccountApplicationConnection(accountId, applicationId, waitopt)

Source:

Adds the application/user connection resource. The authenticated token must belong to the application.

Parameters:
Name Type Attributes Default Description
accountId string

the account id
applicationId string

the application id
wait boolean <optional>
 true

whether or not to wait for the projection to catch up.

addData(datasetId, data, doNotThrowopt)

Source:

Add data to a dataset resource.

Examples

create an individual document

// Assumes the dataset primary key is 'lsoa'
tdxApi.addData(myDatasetId, {lsoa: "E0000001", count: 398});

create multiple documents

tdxApi.addData(myDatasetId, [
 {lsoa: "E0000001", count: 398},
 {lsoa: "E0000002", count: 1775},
 {lsoa: "E0000005", count: 4533},
]);
Parameters:
Name Type Attributes Default Description
datasetId string

The id of the dataset-based resource to add data to.
data object | array

The data to add. Must conform to the schema defined by the resource metadata.
doNotThrow boolean <optional>
 false

set to override default error handling. See TDXApi. Supports creating an individual document or many documents.

addResource(options, waitopt)

Source:

Adds a resource to the TDX.

Example

usage

// Creates a dataset resource in the authenticated users' scratch folder. The dataset stores key/value pairs
// where the `key` property is the primary key and the `value` property can take any JSON value.
tdxApi.addResource({
  name: "resource #1",
  schema: {
    dataSchema: {
      key: "string",
      value: {}
    },
    uniqueIndex: {key: 1}
  }
})
Parameters:
Name Type Attributes Default Description
options object

details of the resource to be added.

Properties
Name Type Attributes Default Description
basedOnSchema string <optional>
 dataset

the id of the schema on which this resource will be based.
derived object <optional>

definition of derived filter, implying this resource is a view on an existing dataset.

Properties
Name Type Attributes Description
filter object <optional>

the (read) filter to apply, in mongodb query format, e.g. {"temperature": {"$gt": 15}} will mean that only data with a temperature value greater than 15 will be available in this view. The filter can be any arbitrarily complex mongodb query. Use the placeholder "@@_identity_@@" to indicate that the identity of the currently authenticated user should be substituted. For example, if the user bob@acme.com/tdx.acme.com is currently authenticated, a filter of {"username": "@@_identity_@@"} will resolve at runtime to {"username": "bob@acme.com/tdx.acme.com"}.
projection object <optional>

the (read) projection to apply, in mongodb projection format, e.g. {"timestamp": 1, "temperature": 1} implies only the 'timestamp' and 'temperature' properties will be returned.
source string <optional>

the id of the source dataset on which to apply the filters and projections.
writeFilter object <optional>

the write filter to apply, in mongodb query format. This controls what data can be written to the underlying source dataset. For example, a write filter of {"temperature": {"$lt": 40}} means that attempts to write a temperature value greater than or equal to 40 will fail. The filter can be any arbitrarily complex mongodb query.
writeProjection object <optional>

the write projection to apply, in mongodb projection format. This controls what properties can be written to the underlying dataset. For example, a write projection of {"temperature": 1} means that only the temperature field can be written, and attempts to write data to other properties will fail. To allow a view to create new data in the underlying dataset, the primary key fields must be included in the write projection.
description string <optional>

a description for the resource.
id string <optional>

the requested ID of the new resource. Must be unique. Will be auto-generated if omitted (recommended).
name string

the name of the resource. Must be unique in the parent folder.
meta object <optional>

a free-form object for storing metadata associated with this resource.
parentId string <optional>

the id of the parent resource. If omitted, will default to the appropriate root folder based on the type of resource being created.
provenance string <optional>

a description of the provenance of the resource. Markdown format is supported.
queryProxy string <optional>

a url or IP address that will handle all queries to this resource
schema object <optional>

optional schema definition.
shareMode string <optional>

the share mode assigned to the new resource. One of ["pw", "pr", "tr"], corresponding to "public read/write", "public read/trusted write", "trusted only".
tags Array.<string> <optional>

a list of tags to associate with the resource.
textContent string <optional>

the text content for the resource. Only applicable to text content based resources.
wait boolean | string <optional>
 false

indicates if the call should wait for the index to be built before it returns. You can pass a string here to indicate the status you want to wait for, default is 'built'.

addResourceAccess(resourceId, accountId, sourceId, access)

Source:

Adds read and/or write permission for an account to access a resource. Permission is required equivalent to that which is being added, e.g. adding write permission requires existing write access. Note access as a result of group membership is not included in determining permissions, in this case add the account to the group instead.

Example

add access to an account

tdxApi.addResourceAccess(myResourceId, "bob@acme.com/tdx.acme.com", myResourceId, ["r"]);
Parameters:
Name Type Description
resourceId string

The resource id
accountId string

The account id to assign permission to
sourceId string

The id of the resource acting as the source of the access. This is usually the same as the target resourceId, but can also be a parent resource. For example, if write access is granted with the sourceId set to be a parent, then if the permission is revoked from the parent resource it will also be revoked from this resource.
access Array.<string>

The access, one or more of ["r", "w"]. Can be an array or an individual string.

addTrustedExchange(options)

Source:

Adds a data exchange to the list of trusted exchanges known to the current TDX.

Parameters:
Name Type Description
options object
Properties
Name Type Description
owner string

the account on this TDX to which the trust relates, e.g. bob@mail.com/tdx.acme.com
targetServer string

the TDX to be trusted, e.g. tdx.nqminds.com
targetOwner string

the account on the target TDX that is trusted, e.g. alice@mail.com/tdx.nqminds.com.

addZoneConnection(options)

Source:

Adds a zone connection to a remote TDX. The details for the connection should be retrieved by a call to the certificate endpoint for the TDX, e.g. https://tdx.nqminds.com/certficate.

Parameters:
Name Type Description
options object

The zone connection details

Properties
Name Type Attributes Description
owner string

The owner of the zone connection. Must be the same as the authenticated account.
tdxServer string

The URL of the target TDX auth server, e.g. https://tdx.nqminds.com
commandServer string <optional>

The URL of the target TDX command server, e.g. https://cmd.nqminds.com
queryServer string <optional>

The URL of the target TDX query server, e.g. https://q.nqminds.com
ddpServer string <optional>

The URL of the target TDX ddp server, e.g. https://ddp.nqminds.com
databotServer string <optional>

The URL of the target TDX databot server, e.g. https://databot.nqminds.com
displayName string <optional>

The friendly name of the TDX.

approveAccount(username, approved)

Source:

Set account approved status. Reserved for system use.

Parameters:
Name Type Description
username string

the full TDX identity of the account.
approved boolean

account approved status

authenticate(id, secret, ttlopt) → {string}

Source:

Authenticates with the TDX, acquiring an authorisation token.

Examples

authenticate using a share key and secret

tdxApi.authenticate("DKJG8dfg", "letmein");

authenticate using custom ttl of 2 hours

tdxApi.authenticate("DKJG8dfg", "letmein", 7200);
Parameters:
Name Type Attributes Default Description
id string

the account id, or a pre-formed credentials string, e.g. "DKJG8dfg:letmein"
secret string

the account secret
ttl number <optional>
 3600

the Time-To-Live of the token in seconds, default is 1 hour. Will default to config.accessTokenTTL if not given here.
Throws:

Will throw if credentials are invalid or there is a network error contacting the TDX.

Returns:

The access token.

Type
string

createTDXToken(username, ipopt, ttlopt) → {object}

Source:

Creates a client user token (e.g. bound to the browser IP) for an application-user token bound to the given IP or the currently authenticated token IP. The currently authenticated token must be an application token, whereby the application has been authorised by the user and the user has permission to access the application. The returned token will be bound to the given IP or the IP of the currently authenticated token (i.e the application server IP).

Examples

create token bound to server ip with default TDX ttl

tdxApi.createTDXToken("bob@bob.com/acme.tdx.com");

create for specific IP

tdxApi.createTDXToken("bob@bob.com/acme.tdx.com", newClientIP);
Parameters:
Name Type Attributes Description
username string

The users' TDX id.
ip string <optional>

The optional IP address to bind the user token to.
ttl number <optional>

The ttl in seconds.
Returns:
  • The new application-user token, bound to the given IP.
Type
object

deleteAccount(username)

Source:

Delete an account

Parameters:
Name Type Description
username string

the full TDX identity of the account to delete.

deleteData(datasetId, data, doNotThrowopt)

Source:

Deletes data from a dataset-based resource.

Parameters:
Name Type Attributes Default Description
datasetId string

The id of the dataset-based resource to delete data from.
data object | array

The primary key data to delete.
doNotThrow boolean <optional>
 false

set to override default error handling. See TDXApi.

deleteDatabotHost(payload)

Source:

Deletes one or more hosts, depending on the given parameters. E.g. if just a hostId is given, all hosts will be deleted with that id. If an ip address is also given, all hosts with the id on that ip address will be deleted and so on. Note that hosts can only be deleted if they are in the offline status.

Parameters:
Name Type Description
payload object

The definition of the host(s) to delete. Can be an array of objects or a single object

Properties
Name Type Attributes Description
hostId string

The id of the hosts to be deleted.
hostIp string <optional>

The optional ip of the hosts to be deleted.
hostPort number <optional>

The optional port number of the host to be deleted.

deleteDatabotInstance(instanceId)

Source:

Deletes a databot instance and all output/debug data associated with it.

Parameters:
Name Type Description
instanceId Array.<string>

The id(s) of the instances to delete. Can be an array of instance ids or an individual string id

deleteDataByQuery(datasetId, query, doNotThrowopt)

Source:

Deletes data from a dataset-based resource using a query to specify the documents to be deleted.

Example
// Delete all documents with English lsoa.
tdxApi.deleteDataByQuery(myDatasetId, {lsoa: {$regex: "E*"}});
Parameters:
Name Type Attributes Default Description
datasetId string

The id of the dataset-based resource to delete data from.
query object

The query that specifies the data to delete. All documents matching the query will be deleted.
doNotThrow boolean <optional>
 false

set to override default error handling. See TDXApi.

deleteManyResources(resourceList) → {CommandResult}

Source:

Permanently deletes a list of resources. Will fail all deletes if any of the permission checks fail.

Parameters:
Name Type Description
resourceList Array.<Resource>

The list of resources to delete. Note only the id property of each resource is required.
Returns:
Type
CommandResult

deleteResource(resourceId)

Source:

Permanently deletes a resource.

Parameters:
Name Type Description
resourceId string

the id of the resource to delete. Requires write permission to the resource.

deleteZoneConnection(id)

Source:

Deletes a zone connection. The authenticated account must own the zone connection.

Parameters:
Name Type Description
id string

The id of the zone connection to delete.

downloadResource(resourceId) → {object}

Source:

Streams the contents of a resource. For dataset-based resources this will stream the dataset contents in newline delimited JSON (NDJSON). For raw file resources this will stream the raw file contents (zip, raw JSON etc).

Parameters:
Name Type Description
resourceId string

The id of the resource to be downloaded.
Returns:
  • Response object, where the response body is a stream object.
Type
object

exchangeTDXToken(token, validateIPopt, exchangeIPopt, ttlopt) → {object}

Source:

Exchanges a client user token (e.g. bound to the browser IP) for an application-user token bound to the given IP or the currently authenticated token IP. The currently authenticated token must be an application token, whereby the application has been authorised by the user and the user has permission to access the application. The returned token will be bound to the given IP or the IP of the currently authenticated token (i.e the application server IP).

Examples

validate against current IP

tdxApi.exchangeTDXToken(clientToken);

validate against different IP

tdxApi.exchangeTDXToken(clientToken, newClientIP);

validate against current IP, bind to a new IP

tdxApi.exchangeTDXToken(clientToken, null, serverIP);
Parameters:
Name Type Attributes Description
token string

The users' TDX auth server token to validate.
validateIP string <optional>

The optional IP address to validate the user token against.
exchangeIP string <optional>

The optional IP address to bind the new token to.
ttl number <optional>

The ttl in seconds.
Returns:
  • The new token application-user token, bound to the server IP.
Type
object

fileUpload(resourceId, file, streamopt, compressedopt, base64Encodedopt)

Source:

Upload a file to a resource.

Parameters:
Name Type Attributes Default Description
resourceId string

The id of the destination resource.
file object

The file to upload, obtained from an <input type="file"> element.
stream boolean <optional>
 false

Flag indicating whether the call should return a stream allowing callees to monitor progress.
compressed boolean <optional>
 false

Flag indicating the file should be decompressed after upload. ZIP format only.
base64Encoded boolean <optional>
 false

= Flag indicating the file should be decoded from base64 after upload.

getAccount(accountId) → {Zone}

Source:

Gets the details for a given account id.

Parameters:
Name Type Description
accountId string

the id of the account to be retrieved.
Returns:

zone

Type
Zone

getAccounts(filter) → {Array.<Zone>}

Source:

Gets the details for all peer accounts.

Example

Get all databots owned by bob

api.getAccounts({accountType: "host", own: "bob@nqminds.com"})
Parameters:
Name Type Description
filter object

query filter.

Properties
Name Type Description
accountType string

the account type to filter by, e.g. "user", "token", "host" etc.
Returns:

zone

Type
Array.<Zone>

getAggregateData(datasetId, pipeline, ndJSONopt) → {DatasetData}

Source:

Performs an aggregate query on the given dataset resource.

Parameters:
Name Type Attributes Description
datasetId string

The id of the dataset-based resource to perform the aggregate query on.
pipeline object | string

The aggregate pipeline, as defined in the mongodb docs. Can be given as a JSON object or as a stringified JSON object.
ndJSON boolean <optional>

If set, the data is sent in newline delimited json format.
Returns:
Type
DatasetData

getAggregateDataStream(datasetId, pipeline, ndJSONopt) → {object}

Source:

Performs an aggregate query on the given dataset resource, returning a response object with stream in the body

Parameters:
Name Type Attributes Description
datasetId string

The id of the dataset-based resource to perform the aggregate query on.
pipeline object | string

The aggregate pipeline, as defined in the mongodb docs. Can be given as a JSON object or as a stringified JSON object.
ndJSON boolean <optional>

If set, the data is sent in newline delimited json format.
Returns:
  • Response object, where the response body is a stream object.
Type
object

getAuthenticatedAccount() → {object}

Source:

Gets details of the currently authenticated account.

Returns:
  • Details of the authenticated account.
Type
object

getData(datasetId, filteropt, projectionopt, optionsopt, ndJSONopt) → {DatasetData}

Source:

For structured resources, e.g. datasets, this function gets all data from the given dataset resource that matches the filter provided.

For non-structured resources such as text-content or raw files etc only the datasetId argument is relevant and this method is equivalent to downloadResource.

Parameters:
Name Type Attributes Description
datasetId string

The id of the dataset-based resource.
filter object <optional>

A mongodb filter object. If omitted, all data will be retrieved.
projection object <optional>

A mongodb projection object. Should be used to restrict the payload to the minimum properties needed if a lot of data is being retrieved.
options GetDataOptions <optional>

A mongodb options object. Can be used to limit, skip, sort etc. Note a default limit of 1000 is applied if none is given here.
ndJSON boolean <optional>

If set, the data is sent in newline delimited json format.
Returns:
Type
DatasetData

getDatabotInstance(instanceId)

Source:

Gets databot instance data for the given instance id.

Parameters:
Name Type Description
instanceId string

The id of the instance to retrieve.

getDatabotInstanceOutput(instanceId, processIdopt)

Source:

Get databot instance output.

Parameters:
Name Type Attributes Description
instanceId string

The instance id to retrieve output for.
processId string <optional>

Optional process id. If omitted, output for all instance processes will be returned.

getDatabotInstanceStatus(instanceId)

Source:

Get databot instance status.

Parameters:
Name Type Description
instanceId string

The id of the databot instance for which status is retrieved.

getDataCount(datasetId, filteropt)

Source:

Gets a count of the data in a dataset-based resource, after applying the given filter.

Parameters:
Name Type Attributes Description
datasetId string

The id of the dataset-based resource.
filter object <optional>

An optional mongodb filter to apply before counting the data.

getDatasetData(datasetId, filteropt, projectionopt, optionsopt, ndJSONopt) → {DatasetData}

Source:
Deprecated:
  • use TDXApi#getData Gets all data from the given dataset resource that matches the filter provided.
Parameters:
Name Type Attributes Description
datasetId string

The id of the dataset-based resource.
filter object <optional>

A mongodb filter object. If omitted, all data will be retrieved.
projection object <optional>

A mongodb projection object. Should be used to restrict the payload to the minimum properties needed if a lot of data is being retrieved.
options GetDataOptions <optional>

A mongodb options object. Can be used to limit, skip, sort etc. Note a default limit of 1000 is applied if none is given here.
ndJSON boolean <optional>

If set, the data is sent in newline delimited json format.
Returns:
Type
DatasetData

getDatasetDataCount(datasetId, filteropt)

Source:
Deprecated:
  • use TDXApi#getDataCount Gets a count of the data in a dataset-based resource, after applying the given filter.
Parameters:
Name Type Attributes Description
datasetId string

The id of the dataset-based resource.
filter object <optional>

An optional mongodb filter to apply before counting the data.

getDatasetDataStream(datasetId, filteropt, projectionopt, optionsopt, ndJSONopt) → {object}

Source:
Deprecated:
  • use TDXApi#getDataStream Gets all data from the given dataset resource that matches the filter provided and returns a response object with stream in the body.
Parameters:
Name Type Attributes Description
datasetId string

The id of the dataset-based resource.
filter object <optional>

A mongodb filter object. If omitted, all data will be retrieved.
projection object <optional>

A mongodb projection object. Should be used to restrict the payload to the minimum properties needed if a lot of data is being retrieved.
options GetDataOptions <optional>

A mongodb options object. Can be used to limit, skip, sort etc. Note a default limit of 1000 is applied if none is given here.
ndJSON boolean <optional>

If set, the data is sent in newline delimited json format.
Returns:
  • Response object, where the response body is a stream object.
Type
object

getDataStream(datasetId, filteropt, projectionopt, optionsopt, ndJSONopt) → {object}

Source:

Gets all data from the given dataset resource that matches the filter provided and returns a response object with stream in the body.

Parameters:
Name Type Attributes Description
datasetId string

The id of the dataset-based resource.
filter object <optional>

A mongodb filter object. If omitted, all data will be retrieved.
projection object <optional>

A mongodb projection object. Should be used to restrict the payload to the minimum properties needed if a lot of data is being retrieved.
options GetDataOptions <optional>

A mongodb options object. Can be used to limit, skip, sort etc. Note a default limit of 1000 is applied if none is given here.
ndJSON boolean <optional>

If set, the data is sent in newline delimited json format.
Returns:
  • Response object, where the response body is a stream object.
Type
object

getDistinct(datasetId, key, filteropt) → {Array.<object>}

Source:

Gets a list of distinct values for a given property in a dataset-based resource.

Parameters:
Name Type Attributes Description
datasetId string

The id of the dataset-based resource.
key string

The name of the property to use. Can be a property path, e.g. "address.postcode".
filter object <optional>

An optional mongodb filter to apply.
Returns:
  • The distinct values.
Type
Array.<object>

getNDData()

Source:

Sugar for newline delimited data. See getData for details.

getResource(resourceId, noThrowopt) → {Resource}

Source:

Gets the details for a given resource id.

Example
api.getResource(myResourceId)
 .then((resource) => {
   console.log(resource.name);
 });
Parameters:
Name Type Attributes Default Description
resourceId string

The id of the resource to retrieve.
noThrow boolean <optional>
 false

If set, the call won't reject or throw if the resource doesn't exist.
Throws:

Will throw if the resource is not found (see noThrow flag) or permission is denied.

Returns:
Type
Resource

getResourceAccess(resourceId) → {Array.<ResourceAccess>}

Source:

Gets all access the authenticated account has to the given resource id.

Example
api.getResourceAccess(myResourceId)
 .then((resourceAccess) => {
   console.log("length of access list: ", resourceAccess.length);
 });
Parameters:
Name Type Description
resourceId string

The id of the resource whose access is to be retrieved.
Returns:
  • Array of ResourceAccess objects.
Type
Array.<ResourceAccess>

getResourceAncestors(resourceId) → {Array.<Resource>}

Source:

Gets all resources that are ancestors of the given resource.

Parameters:
Name Type Description
resourceId string

The id of the resource whose parents are to be retrieved.
Returns:
Type
Array.<Resource>

getResources(filteropt, projectionopt, optionsopt) → {Array.<Resource>}

Source:

Gets the details of all resources that match the given filter.

Examples

filtering by explicit id

tdxApi.getResources({"id": "rygq8DNEPw"});

filtering by set of ids

tdxApi.getResources({"id": {"$in": ["rygq8DNEPw", "xmm1z-D8d"]}});

filtering by name

tdxApi.getResources({"name": {"$regex": "test"}});

filtering by name, returning only id and name

tdxApi.getResources({"name": {"$regex": "test"}}, {"id": 1, "name": 1});
Parameters:
Name Type Attributes Description
filter object <optional>

A mongodb filter definition. Note, filtering on id is restricted to an explicit string match or a $in clause to match against a list of ids.
projection object <optional>

A mongodb projection definition, can be used to restrict which properties are returned thereby limiting the payload.
options object <optional>

A mongodb options definition, can be used for limit, skip, sorting etc.
Returns:
Type
Array.<Resource>

getResourcesWithSchema(schemaId) → {Array.<Resource>}

Source:

Retrieves all resources that have an immediate ancestor of the given schema id.

Parameters:
Name Type Description
schemaId string

The id of the schema to match, e.g. "geojson".
Returns:
Type
Array.<Resource>

getTDXToken(tdx) → {string}

Source:

Retrieves an authorisation token for the given TDX instance

Parameters:
Name Type Description
tdx string

The TDX instance name, e.g. "tdx.acme.com".
Returns:
Type
string

getZone(accountId) → {Zone}

Source:

Gets the details for a given zone (account) id.

Parameters:
Name Type Description
accountId string

the id of the zone to be retrieved.
Returns:

zone

Type
Zone

isInGroup(accountId, groupId) → {boolean}

Source:

Determines if the given account is a member of the given group. Note that accurate visibility of group members requires one or more of the following to be true:

  • the authenticated account added accountId to the group
  • the authenticated account owns the group
Parameters:
Name Type Description
accountId string

the id of the account
groupId *

the id of the group
Returns:
  • true if accountId is a member of the group and visible to the authenticated account.
Type
boolean

moveResource(id, fromParentId, toParentId)

Source:

Move resource from one folder to another. Requires write permission on the resource, the source parent and the target parent resources.

Parameters:
Name Type Description
id string

the id of the resource to move.
fromParentId string

the current parent resource to move from.
toParentId string

the target folder resource to move to.

patchData(datasetId, data, doNotThrowopt)

Source:

Patches data in a dataset resource. Uses the JSON patch format, which involves defining the primary key data followed by a flexible update specification.

Examples

patch a single value in a single document

tdxApi.patchData(myDatasetId, {lsoa: "E000001", __update: [{path: "/count", op: "replace", value: 948}]});

patch a more than one value in a single document

tdxApi.patchData(myDatasetId, {lsoa: "E000001", __update: [
  {path: "/count", op: "replace", value: 948}
  {path: "/modified", op: "add", value: Date.now()}
]});
Parameters:
Name Type Attributes Default Description
datasetId string

The id of the dataset-based resource to update.
data object

The patch definition.

Properties
Name Type Description
__update object | array

An array of JSON patch specifications.
doNotThrow boolean <optional>
 false

set to override default error handling. See TDXApi.

rebuildResourceIndex(resourceId)

Source:

Resets the resource index. This involves deleting existing indexes and rebuilding them. May take a while depending on the size of any associated dataset and the number and complexity of indexes.

Parameters:
Name Type Description
resourceId string

the id of the resource, requires write permission.

registerDatabotHost(payload)

Source:

Registers a databot host with the TDX. Once registered, a host is eligible to receive commands from the TDX.

Example

register a databot host

tdxApi.registerDatabotHost({version: "0.3.11", port: 2312, hostStatus: "idle"});
Parameters:
Name Type Description
payload object

The databot host identifier payload.

Properties
Name Type Attributes Description
port number

the port number the host is listening on.
version string

the databot host software version.
hostStatus string

the current status of the host, "idle" or "busy".
ip string <optional>

optional ip address of the host. Usually the TDX can deduce this from the incoming request.

removeResourceAccess(resourceId, accountId, addedBy, sourceId, access)

Source:

Removes access for an account to a resource. Permission is required equivalent to that which is being added, e.g. adding write permission requires existing write access.

Example

usage

// Removes read access for account "john.trulove@nqminds.com/tdx.nqm-1.com" added by
// Toby via "ezh.ubiapps@gmail.com/tdx.nqm-1.com,toby.ealden@gmail.com/tdx.nqm-1.com".
tdxApi.removeResourceAccess(
 "rJg9ldNEwD",
 "john.trulove@nqminds.com/tdx.nqm-1.com",
 "ezh.ubiapps@gmail.com/tdx.nqm-1.com,toby.ealden@gmail.com/tdx.nqm-1.com",
 "rJg9ldNEwD",
 ["r"]
);
Parameters:
Name Type Description
resourceId string

The resource id.
accountId string

The account id to remove access from.
addedBy string

The full by path of the permission to be removed.
sourceId string

The source of the access, usually the resource itself.
access Array.<string>

The access, one or more of ["r", "w"].

resetAccount(username, key)

Source:

Change account secret.

Parameters:
Name Type Description
username string

the full TDX identity of the account.
key string

the new secret

rollbackCommand()

Source:

AUDIT COMMANDS

sendDatabotHostCommand(command, hostId, hostIpopt, hostPortopt, payloadopt)

Source:

Sends a command to a databot host. Reserved for system use.

Parameters:
Name Type Attributes Description
command string

The command to send. Must be one of ["stopHost", "updateHost", "runInstance", "stopInstance", "clearInstance"]
hostId string

The id of the host.
hostIp string <optional>

The ip address of the host. If omitted, the command will be sent to all host ip addresses.
hostPort number <optional>

The port number of the host. If omitted, the command will be sent to all host ports.
payload object <optional>

The command payload.

setResourceImporting(resourceId, importing) → {CommandResult}

Source:

Set the resource import flag.

Parameters:
Name Type Description
resourceId string

The id of the dataset-based resource.
importing boolean

Indicates the state of the import flag.
Returns:
Type
CommandResult

setResourcePermissiveShare(resourceId, allowPermissive)

Source:

Sets the permissive share mode of the resource. Permissive share allows anybody with acces to the resource to share it with others. If a resource is not in permissive share mode, only the resource owner can share it with others.

Parameters:
Name Type Description
resourceId string

The resource id.
allowPermissive boolean

The required permissive share mode.

setResourceSchema(resourceId, schema) → {CommandResult}

Source:

Set the resource schema.

Parameters:
Name Type Description
resourceId string

The id of the dataset-based resource.
schema object

The new schema definition. TODO - document
Returns:
Type
CommandResult

setResourceShareMode(resourceId, shareMode)

Source:

Set the share mode for a resource.

Parameters:
Name Type Description
resourceId string

The resource id.
shareMode string

The share mode to set, one or ["pw", "pr", "tr"] corresponding to 'public read/write', 'public read, trusted write', 'trusted only'.

setResourceStore(resourceId, store, storeSizeopt)

Source:

Sets the dataset store of the resource. Reserved for system use.

Parameters:
Name Type Attributes Description
resourceId string

The resource id.
store string

The name of the store.
storeSize number <optional>

The size in bytes of the store.

setResourceTextContent(resourceId, textContent)

Source:

Set the text for a text-content based resource.

Example

usage

// Sets the text content for a text-html resource.
tdxApi.setResourceTextContent(
  "HyeqJgVdJ7",
  "<html><body><p>Hello World</p></body></html>"
);
Parameters:
Name Type Description
resourceId string

The resource id.
textContent string

The text content to set.

startDatabotInstance(databotId, payload)

Source:

Starts a databot instance.

Parameters:
Name Type Description
databotId string

The id of the databot definition to start.
payload object

The instance input and parameters.

Properties
Name Type Attributes Default Description
id string <optional>

The id to assign to the new instance. This will be auto-generated if omitted. If there is an existing instance with this id the overwriteExisting flag must be set (see below).
authTokenTTL number <optional>

The time-to-live to use when creating the auth token, in seconds. Will default to the TDX-configured default if not given (usually 1 hour).
chunks number <optional>
 1

The number of processes to instantiate. Each will be given the same input data, with only the chunk number varying.
debugMode boolean <optional>
 false

Flag indicating this instance should be run in debug mode, meaning all debug output will be captured and stored on the TDX. n.b. setting this will also restrict the hosts available to run the instance to those that are willing to run in debug mode.
description string <optional>

The description for this instance.
inputs object <optional>

The input data. A free-form object that should conform to the specification in the associated databot definition.
name string <optional>

The name to associate with this instance, e.g. "Male population projection 2017"
overwriteExisting boolean <optional>

Set to allow existing instances to be overwritten (see the id property above). Note it is not possible to overwrite a running instance.
priority number <optional>

The priority to assign this instance. Reserved for system use.
shareKeyId string

The share key to run the databot under.
shareKeySecret string <optional>

The secret of the share key. Ignored if the share key id refers to a user-based account.

stopDatabotInstance(instanceId, mode)

Source:

Terminates or pauses a running databot instance.

Parameters:
Name Type Description
instanceId string

The id of the instance to terminate or pause.
mode string

One of ["stop", "pause", "resume"]

suspendResourceIndex(resourceId)

Source:

Suspends the resource index. This involves deleting any existing indexes. Requires write permission. When a resource index is in suspended status, it is not possible to run any queries or updates against the resource.

Parameters:
Name Type Description
resourceId string

the id of the resource. Requires write permission.

truncateResource(resourceId)

Source:

Removes all data from the resource. Applicable to dataset-based resources only. This can not be undone.

Parameters:
Name Type Description
resourceId string

The resource id to truncate.

updateAccount(username, options)

Source:

Updates account details. All update properties are optional. See createAccount for full details of each option.

Parameters:
Name Type Description
username string

the full TDX identity of the account to update.
options object

the update options

Properties
Name Type Attributes Description
displayName string <optional>
key string <optional>
scratchAccess boolean <optional>
settings object <optional>
whitelist Array.<string> <optional>

updateData(datasetId, data, upsertopt, doNotThrowopt, optsopt) → {CommandResult}

Source:

Updates data in a dataset resource.

Examples

update an existing document

tdxApi.updateData(myDatasetId, {lsoa: "E000001", count: 488});

upsert a document

// Will create a document if no data exists matching key 'lsoa': "E000004"
tdxApi.updateData(myDatasetId, {lsoa: "E000004", count: 288}, true);
Parameters:
Name Type Attributes Default Description
datasetId string

The id of the dataset-based resource to update.
data object | array

The data to update. Must conform to the schema defined by the resource metadata. Supports updating individual or multiple documents.
upsert boolean <optional>
 false

Indicates the data should be created if no document is found matching the primary key.
doNotThrow boolean <optional>
 false

set to override default error handling. See TDXApi.
opts object <optional>

reserved for system use.
Returns:
  • Use the result property to check for errors.
Type
CommandResult

updateDatabotHostStatus(payload)

Source:

Updates a databot host status.

n.b. the response to this request will contain any commands from the TDX that the host should action ( see commands).

Example

update databot host status

tdxApi.updateDatabotHostStatus({port: 2312, hostStatus: "idle"});
Parameters:
Name Type Description
payload object

The databot host status payload.

Properties
Name Type Attributes Description
port number

The port number on which the host is listening.
hostStatus string

The current host status, either "idle" or "busy".
ip string <optional>

optional ip address of the host. Usually the TDX can deduce this from the incoming request.

updateDataByQuery(datasetId, query, doNotThrowopt)

Source:

Updates data in a dataset-based resource using a query to specify the documents to be updated.

Example
// Update all documents with English lsoa, setting `count` to 1000.
tdxApi.updateDataByQuery(myDatasetId, {lsoa: {$regex: "E*"}}, {count: 1000});
Parameters:
Name Type Attributes Default Description
datasetId string

The id of the dataset-based resource to update data in.
query object

The query that specifies the data to update. All documents matching the
doNotThrow boolean <optional>
 false

set to override default error handling. See TDXApi. query will be updated.

updateResource(resourceId, update)

Source:

Modify one or more of the meta data associated with the resource.

Parameters:
Name Type Description
resourceId string

id of the resource to update
update object

object containing the properties to update. Can be one or more of those listed below. See the TDXApi#addResource method for semantics and syntax of each property.

Properties
Name Type Attributes Description
derived string <optional>
description string <optional>
meta object <optional>
name string <optional>
overwrite boolean <optional>

set this flag to overwrite existing data rather than merging (default). This currently only applies to the meta property.
provenance string <optional>
queryProxy string <optional>
tags array <optional>
textContent string <optional>

see also TDXApi#setResourceTextContent

validateTDXToken(token, ipopt) → {object}

Source:

Validates the given token was signed by this TDX, and returns the decoded token data.

Parameters:
Name Type Attributes Description
token string

The TDX auth server token to validate.
ip string <optional>

The optional IP address to validate against.
Returns:
  • The decoded token data.
Type
object

verifyAccount(username, approved)

Source:

Set account verified status. Reserved for system use.

Parameters:
Name Type Description
username string

the full TDX identity of the account.
approved boolean

account verified status

writeDatabotHostInstanceOutput(output)

Source:

Stores databot instance output on the TDX.

Parameters:
Name Type Description
output object

The output payload for the databot instance.