Records

A record object stores no additional data nor has any additional API methods beyond those described for all entities and classes. A record object can be used to store data in its details, that is, as a base object containing only metadata and links to other objects.

Record API Method Specifications

API method: /record/new

Specification

Creates a new record object. If initializeFrom is set to a hash specifying a record object, then all metadata fields of the new record created are initialized to be the same as the specified record (except for any other specified fields).

Inputs

• project string (required) ID of the project or container to which the record should belong, such as the string "project-xxxx".

• name string (optional) The name of the object. Defaults to the new ID.

• tags array of strings (optional) Tags to associate with the object.

• types array of strings (optional) Types to associate with the object. See the Types page for details on valid input.

• hidden boolean (optional) Whether the object should be hidden. Defaults to false.

• properties mapping (optional) Properties to associate with the object.

  • key — the property name.

  • value string — the property value.

• details mapping or array (optional) JSON object or array that is to be associated with the object. See the Object Details section for details on valid input. Defaults to {}.

• folder string (optional) Full path of the folder that is to contain the new object. Defaults to "/".

• close boolean (optional) Whether the record should be closed immediately after creation. Defaults to false.

• parents boolean (optional) Whether all folders in the path provided in folder should be created if they do not exist. Defaults to false.

• initializeFrom mapping (optional) Indicate an existing record from which to use the metadata as default values for all fields that are not given:

  • project string (required) ID of the project or container containing the record to use.

  • id string (required) ID of the record to use.

• nonce string (optional) Unique identifier for this request. Ensures that even if multiple requests fail and are retried, only a single record is created. For more information, see Nonces.

Outputs

• id string ID of the created record object, for example, a string in the form "record-xxxx".

Errors

• InvalidInput

  • A reserved linking string ("$dnanexus_link") appears as a key in a hash in details but is not the only key in the hash

  • A reserved linking string ("$dnanexus_link") appears as the only key in a hash in details but has value other than a string

  • The id given under initializeFrom is not a valid record ID

  • For each property key-value pair, the size, encoded in UTF-8, of the property key may not exceed 100 bytes and the property value may not exceed 700 bytes

  • A nonce was reused in a request but other inputs had changed signifying a new and different request

  • A nonce may not exceed 128 bytes

• InvalidType (project is not a project ID)

• SpendingLimitExceeded

  • The billTo has reached its spending limit

• OrgExpired

  • The billTo organization has expired

• PermissionDenied (UPLOAD access required, VIEW access required for the project specified under initializeFrom if a record was specified)

• ResourceNotFound (the specified project is not found, the path in folder does not exist while parents is false, or the specified project and/or record ID specified in initializeFrom are not found)

API method: /record-xxxx/describe

Specification

Describes a record. A project ID can be given to request user-provided metadata from a particular project and serves as a hint. If the specified project doesn't contain the object but another accessible project does (with user having VIEW permissions), that other project's metadata is returned instead. The response includes the project ID used for the metadata, whether it matches the hint or not. Details can also be requested via this method, but require VIEW access to be returned.

Alternatively, you can use the /system/describeDataObjects method to describe many data objects at once.

Inputs

• project string (optional) Project or container ID to be used as a hint for finding the object in an accessible project.

• defaultFields boolean (optional) Whether to include the default set of fields in the output (the default fields are described in the "Outputs" section below). The selections are overridden by any fields explicitly named in fields.

  • Defaults to false if fields is supplied, true otherwise.

• fields mapping (optional) Include or exclude the specified fields from the output. These selections override the settings in defaultFields.

  • key — the desired output field. See "Outputs" below for valid values.

  • value boolean — whether to include the field.

The following options are deprecated (and are ignored if fields is present):

• properties boolean (optional, deprecated) Whether the properties should be returned. Defaults to false.

• details boolean (optional, deprecated) Whether the details should also be returned. Defaults to false.

Outputs

• id string The object ID, such as "record-xxxx".

The following fields are included by default (but can be disabled using fields or defaultFields):

• project string ID of the project or container in which the object was found.

• class string The value "record".

• types array of strings Types associated with the object.

• created timestamp Time at which this object was created.

• state string Either "open" or "closed".

• hidden boolean Whether the object is hidden or not.

• links array of strings The object IDs that are pointed to from this object.

• name string The name of the object.

• folder string The full path to the folder containing the object.

• sponsored boolean Whether the object is sponsored by DNAnexus.

• tags array of strings Tags associated with the object.

• modified timestamp Time at which the user-provided metadata of the object was last modified.

• createdBy mapping How the object was created.

  • user string ID of the user who created the object or launched an execution which created the object.

  • job string ID of the job that created the object.

    • Only present when a job created the object.

  • executable string ID of the app or applet that the job was running.

    • Only present when a job created the object.

The following field (included by default) is available if the object is sponsored by a third party:

• sponsoredUntil timestamp Indicates the expiration time of data sponsorship. This field exists only for sponsored objects and specifies a future timestamp.

The following fields are only returned if the corresponding field in the fields input is set to true:

• properties mapping Properties associated with the object.

  • key — the property name.

  • value string — the property value.

• details mapping or array Contents of the object's details.

Errors

• ResourceNotFound (the specified object does not exist or the specified project does not exist)

• InvalidInput (the input is not a hash, project (if supplied) is not a string, or the value of properties (if supplied) is not a boolean)

• PermissionDenied (VIEW access required for the project provided (if any), and VIEW access required for some project containing the specified object (not necessarily the same as the hint provided))