Information submitted through the support site is private but is not hosted within your secure CDD Vault. Please do not include sensitive intellectual property in your support requests.

ELN Entries [GET, PUT, POST]

For security purposes, the GET and POST ELN Entries CDD Vault API commands documented here are only available for Vault Administrators.

API calls related to ELN Entries:

Retrieve

Update

Create 

Change Status 

 

Retrieve


GET /api/v1/vaults/<vault_id>/eln/entries


Returns a summary of all available ELN entries for the Vault specified


GET /api/v1/vaults/<vault_id>/eln/entries?async=true


Returns a zip file containing the export of all available ELN entries


Query Parameters (all optional):

 
eln_entries Comma-separated list of ELN entry IDs
author Comma separated list of ELN author IDs
Note: Must be users' IDs, users' names cannot be used
status

Returns ELN entries that have the status specified

Note: Status values are case-sensitive and are: open, submitted, or finalized

async

Boolean
If true, do an asynchronous export (see Async Export)
Use if you wish to retrieve a zip file containing exports of the actual ELN entries along with any files attached within the ELN entries. Note: any page_size parameter used in an API GET call that also uses the async=true parameter will be ignored. The GET call will return all valid data for the given GET call.

only_ids

Boolean
If true, only the ELN Entry IDs are returned, allowing for a smaller and faster response. (Async should still be used when many IDs are expected.)

 

Note: any page_size parameter used in an API GET call that also uses the only_ids=true parameter will be ignored. The GET call will return all valid data for the given GET call.


Default: false

only_summary

Boolean
If true, only a csv Summary file will be returned. This Summary csv file will include all system ELN metadata fields plus all user-defined ELN Fields. Async is still recommended.
Default: false

created_before Date (YYYY-MM-DDThh:mm:ss±hh:mm)
created_after Date (YYYY-MM-DDThh:mm:ss±hh:mm)
modified_before

Date (YYYY-MM-DDThh:mm:ss±hh:mm)

Note: Uses date the ELN entry was last modified

modified_after

Date (YYYY-MM-DDThh:mm:ss±hh:mm)

Note: Uses date the ELN entry was last modified

submitted_date_before Date (YYYY-MM-DDThh:mm:ss±hh:mm)
submitted_date_after Date (YYYY-MM-DDThh:mm:ss±hh:mm)
finalized_date_before Date (YYYY-MM-DDThh:mm:ss±hh:mm)
finalized_date_after Date (YYYY-MM-DDThh:mm:ss±hh:mm)
offset The index of the first object actually returned. Defaults to 0.
page_size The maximum number of objects to return in this call when not using the async parameter. Default is 50, maximum is 1000. Note: any page_size parameter used in an API GET call that also uses the async=true parameter will be ignored. The GET call will return all valid data for the given GET call.
projects Comma-separated list of project IDs
Defaults to all available projects
Limits scope of query

 

Notes on Date/Time 

The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20".

You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

 

Examples

curl -H "X-CDD-Token: $TOKEN" https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/eln/entries?eln_entries=<elnid>,<elnid>

Returns:

{
    "count"2,
    "offset"0,
    "page_size"50,
    "objects": [
        {
            "id": <elnid>,
            "name""Entry: Principles of Early Drug Discovery",
            "status""open",
            "author": {
                "id": 123,
                "first_name""Given-Name",
                "last_name""Surname"
            },
            "url""https://app.collaborativedrug.com/vaults/<vault_id>/eln/entries/<elnid>"
        },
        {
            "id": <elnid>,
            "name""Entry: Data for synthesis",
            "status""finalized",
            "author": {
                "id": 987,
                "first_name": First",
                "last_name""Last"
            },
            "url""https://app.collaborativedrug.com/vaults/<vault_id>/eln/entries/<elnid>"
        }
    ]
}

 

To retrieve a zip file containing the full exports of ELN entries:

curl -H "X-CDD-Token: $TOKEN" https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/eln/entries?eln_entries=<elnid>,<elnid>&async=true

Returns:

{
"id": 2980457,
"created_at": "2020-08-10T19:51:03.000Z",
"modified_at": "2020-08-10T19:51:03.000Z",
"status": "new"
}

 

Noteworthy Tips

  • To include the “author” parameter in your API call, you must provide the user ID, not a user name. Vault Administrators may discover the available user IDs in your CDD Vault using the GET Users API call.

curl -H "X-CDD-Token: $TOKEN" https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/users

  • The “async” parameter is required to retrieve a ZIP export of your ELN entries. As an example, this GET ELN Entries API call, when used with the async=true parameter, will return an Export ID that can subsequently be retrieved using the GET Exports API call.

Update

Updates an existing ELN entry

The PUT ELN Entries API call can be used to modify the content of existing ELN Entries. Update the title, project, ELN fields and even the body; adding links, text, and files using the append_to_body parameter.

This append_to_body parameter is an array of JSON objects, each with a specific type and associated parameters:

  • TEXT: { "type": "text", "text": "required text goes here" }
  • LINK: { "type": "link", "url": "required URL goes here, same scheme rules as frontend", "label": "optional label override goes here" }
  • FILE: { "type": "file", "file": <file id> }
 
append_to_body Adds text, links and files into the canvas of an exsiting ELN Entry
status

Returns ELN entries that have the status specified

Note: Status values are case-sensitive and are: open, submitted, or finalized

title Modifies the Title of the ELN Entry
project Modifies the Project association of the ELN Entry
eln_fields

Modifies the values of the customer-defined ELN Fields. Syntaz resembles:

"eln_fields":

   {"field1":"new value for field1",

     "field2":"new value for field2"}

 

 

This API call:

PUT .../vaults/<vault_id>/eln/entries/<entry_id>

 

... using this JSON:

{
{"append_to_body": [
{"type": "text", "text": "Description of this experiment"},
{"type": "link", "url": "https://www.collaborativedrug.com", "label": "This is a link to CDD"},
{"type": "file", "file": 12345}
]}

... will append the content to the existing ELN Entry.

Create

Creates a new ELN entry

POST /api/v1/vaults/<vault_id>/eln/entries

The body of the POST must contain a JSON structure specifying the desired ELN entry attributes.

 

Note: Files may be inserted into existing ELN entries using the POST Files API call.

 

Allowed JSON keys for creating new ELN Entries:

title

Provide the title of the new ELN entry

project

The project id and/or name where the new ELN Entry will be created

eln_fields

Each vault has its own specific set of ELN Fields that are created and managed by the Vault Administrator (for a Vault Administrator, see Settings > Vault > ELN Fields, to change which ELN fields are available and/or required).

{<eln_field_name>: <eln_field_value>, ... }

 

Example JSON for creating new ELN Entries:

{
    "title":"New ELN Entry Creation",
    "project":"Internal Data",
    "eln_fields":{
        "Institute":"Graceland CRO",
        "PI":"Elvis Presley",
        "Date":"2021/06/15"}
}

Note: Files may be inserted into ELN entries using the POST Files API call.

Change the Status of an ELN Entry

Assigns an ELN entry to be witnessed, then approved or rejected.

 

The POST ELN Entries API call can be used to modify the status of existing ELN Entries. Assign the ELN Entry to a witness, accept or reject the witness, and finalize an ELN Entry.

 

POST /api/v1/vaults/<vault_id>/eln/entries/12345/status

Example JSON for changing the Status of an ELN Entry - Submit for witnessing:

 {"status_action":"submit",
"witness":"10276"}

 

POST /api/v1/vaults/<vault_id>/eln/entries/12345/status

Example JSON for changing the Status of an ELN Entry - approve for finalization:

 {"status_action":"approve"}

 

POST /api/v1/vaults/<vault_id>/eln/entries/12345/status

Example JSON for changing the Status of an ELN Entry - reject witnessing:

 {"status_action":"reject",
"reason":"Not enough data"}

 

POST /api/v1/vaults/<vault_id>/eln/entries/12345/status

Example JSON for discarding an ELN Entry:

 {"status_action":"discard"}