Entity

Last updated on 22-Aug-2024 by Jakob Jakobsen Boysen

On this page

Get entities
Get entity
Create/update entities
Clone entity

Get entities

GET /api/entity/{eClass}

Get entities of class. Returns first 500 entities. The nextSkip value can be used as input for next $skip query parameter.

Request

Path parameters

eClass The entity class to query

Query parameters

The following query parameters are documented in detail in the OData specification:

$top Number. Limits result count.
$skip Number. Requests the number of results to be skipped. $top and $skip can be used in conjunction to page results, e.g. ?$skip=20&$top=10 will request 10 items after the first 20 are skipped, i.e. page 3.
$select Strings, split by a comma. Returns only properties specified. E.g. ?$select=Prop1,Prop2.
$orderby Strings, split by comma. Sort result by property. E.g. $orderby=Prop1,Prop2 desc sorts ascending by Prop1 and then descending by Prop2.
$filter String, split by and. Filters the result. See supported filters here

Response

{
    "data": [],         // entities
    "total": number,    // total amount of entities matching filter    
    "nextSkip": number  // then number to put in the next $skip parameter if more than 500 entities are matching
}

Example 1

Get all InProgress and Completed Experiments created by JJB sorted by last modified:

/api/entity/Experiment?$filter=status in ('InProgress', 'Completed') and createdBy eq 'JJB'&$orderby=modifiedUtc

Example 2

Get all experiments with paging:

1. call:
/api/entity/Experiment
Returns {"data": 500 experiments, "total": 1230, "nextSkip": 500 }

2. call:
/api/entity/Experiment?$skip=500
Returns {"data": 500 experiments, "total": 1230, "nextSkip": 1000 }

3. call:
/api/entity/Experiment?$skip=1000
Returns {"data": 230 experiments, "total": 1230, "nextSkip": 1500 }

A fourth call is not necessary.

Get entity

GET /api/entity/{eClass}/{id}

Get a specific entity based on entity class and id.

Request

Path parameters

eClass The entity class
id The ID of the entity

Response

{
    "id": string,   
    "eClass": string,
    "accessType": "Read" | "Write" | "None",
    "canWrite": boolean,

    // related entities
    "files": [],
    "events": [],
    "auditEvents": [],

    "prop1": any,     // all properties related to this entity
}

Create/update entities

POST /api/entity

Create new entities or update existing entities.

Request

Body

{
    "entities": [{
        "id": string,
        "eClass": string,
        ...
    },...]
}

entities The entities to create or update. The eClass is required. If id is set and is found in the database, an existing entity will be updated with the given property values.

Functional notation:

# Used for referencing an id, name, or barcode variable. The variable will be replaced with auto-generated IDs by backend, or the alias it refers to.
# in conjunction with ., e.g. #idReq.name refers to the name of a entity with id #idReq.
! Used for switching eClass prefix. Can only be used on id variables. Changes auto-generated ID from default eClass prefix to written eClass prefix.

# and ! can be used together in ID fields, e.g. "id": "#idRef!nameSeq".

Special properties:

notes: A list of notes that will have the entity in question as subject.
files: A list of files that will have the entity in question as subject.
input for Step: StepInput associated records are created based on this.

Default values:

The following properties have defaults:

name: fallback to ID
userID: fallback to currently logged in user
departmentID: fallback to currently logged in user's department
status: Initial, unless datamodel states differently
type: Other

These audit properties are not editable and set automatically: createdBy, createdUtc, modifiedBy, modifiedUtc, version.

Response

The created entities:

{
    "entities": [{
        "id": string,
        "eClass": string,
        ...
    },...]
}

Example 1

Reference a new entity in a foreign key field parentID:

{
    "entities": [{
        "id": "#stringA",
        ...
    },
    {
        "parentID": "#stringA",
        ...
    },...]
}

Example 2

Use a sequence with the ID "nameSeq" for generating the id:

{
    "entities": [{
        "id": "!nameSeq",
        ...
    },...]
}

Example 3

Upload files and add notes:

{
    "entities": [{
        "id": "#idReq",
        "eClass": "Request",
        "files": [{
            "name": "myname.csv",
            "content": "base64encoded",
            "mediaType": "text/csv",
            "type": "AttachedFile"
        }],
        "notes": [{
            "content": "Some notes from our customer",
            "type": "CustomerNotes"
        }]
        ...
    },...]
}

Example 3

Use same name in a new entity in a field:

{
    "entities": [{
        "id": "#stringA",
        "name": "someName",
    },
    {
        "refName": "#stringA.name",
        ...
    },...]
}

Clone entity

POST /api/entity/{eClass}/{id}

Clone existing entity.

Request

Path parameters

eClass The entity class of the entity to clone
id The ID of the entity to clone

Body

{
    "key1": any,
    "key2": any,
    "attributes.key3": any,
    "attributes": {
        "key4": any,
    },
    ...
}

Where key1, key2, etc. refers to keys of the entity to clone. The keys are overrides. E.g. if the entity has a name property, you can override it with a new value.

Notice attributes can be set both with a dot-notation and as an object. The attributes of the entity to clone are merged with the overrides.

Response

The cloned entity:

{
    "id": string,
    "eClass": string,
    ...
}

Example 1

Clone a Sample and refer the new Sample to the cloned Sample:

Request: POST /api/entity/Sample/S0001

{
    "name": "New Sample",
    "parentID": "S0001"
}

Response:

{
    "id": "S0002",
    "eClass": "Sample",
    "parentID": "S0001",
    ...
}

On this page

Get entities
Get entity
Create/update entities
Clone entity