ELN Entries [GET, PUT, POST] – CDD Support

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
`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.

Remember, to modify the status of an ELN Entry, use this POST Entries API call.

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"}