logo
logo

Entity resource

Each entity in the system is represented by an Entity Resource. This resource can be used to retrieve the state of the entity, to create an entity, to update it or to delete it.

The following methods are supported: POST, GET, HEAD, PUT, DELETE. The methods LOCK and UNLOCK are no longer supported.

POST /api/entities

Adds a new entity. The link to the associated Entity Definition Resource is required. The self property is ignored and may be omitted. The request body may contain either an id or an identifier. If so the request will be treated as a possible UPSERT. The existence of the entity will be checked and if it does the entity will be updated based on the provided body elements.

Success is indicated by returning a 201 Created response, where a Location header contains the URL of the newly created resource. When UPSERT functionality was triggered the response will be dependent on the provided details. When an id is present the header will contain the same Location property as with a normal POST response. When an identifier is used the header will contain an X-Global-Identifier property with the updated identifier as its value.

![TIP] It is not possible to set relations while creating an entity unless the relations are nested. Additionally, this functionality is available only through the REST API and not through the Web Client SDK. For non-nested relations one call shall be made for each relation that shall be updated.

Example Request:

POST http://hostname/api/entities
Host: hostname
Content-Type: application/json

{
    "properties":{
        "Property1":"Some value",
        "Property2":42
    },
    "relations": {
        "FinalLifeCycleStatusToAsset": {
            "parent": {
                "href": "http://hostname/api/entities/{id}"
            }
        }
    },
    "entitydefinition":{
        "href":"http://hostname/api/entitydefinitions/EntityDefinition1"
    }
}

Example response:

HTTP/1.1 201 Created
Location: http://hostname/api/entities/2

GET /api/entities/id

Returns an Entity Object that contains the state of the entity.

Example request:

GET http://hostname/api/entities/1
Host: hostname
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Length: content length
Content-Type: application/json; charset=utf-8
ETag: "hash string"

{
    "id":100,
    "identifier": "00amyWGct0y_ze4lIsj2Mw",
    "properties":{
        "Property1":"Some value",
        "Property2":42
    },
    "relations":{
        "Parent":{
            "href":"http://hostname/api/entities/1/relations/Parent"
        }
    },
    "self":{
        "href":"http://hostname/api/entities/1"
    },
    "entitydefinition":{
        "href":"http://hostname/api/entitydefinitions/EntityDefinition1"
    }
}

GET /api/entities/identifier/uniqueid

Gets an entity by its unique identifier. The response is identical to the one from GET /api/entities/id.

Example request:

GET http://hostname/api/entities/identifier/00amyWGct0y_ze4lIsj2Mw
Host: hostname
Accept: application/json

PUT /api/entities/identifier/uniqueid

Updates an entity with the state submitted in the request. If successful, the server responds with 204 No Content. The request body must contain an Entity Object and its entity definition. The id, relations and self properties are ignored, and may be omitted.

Example request:

PUT http://hostname/api/entities/identifier/00amyWGct0y_ze4lIsj2Mw
Host: hostname
Content-Type: application/json
{
    "properties":{
        "Property2":43
    },
    "entitydefinition":{
        "href":"http://hostname/api/entitydefinitions/EntityDefinition1"
    }
}

Example response:

HTTP/1.1 204 No Content

DELETE /api/entities/identifier/uniqueid

Deletes the entity. If successful, the server responds with 204 No Content.

Example request:

DELETE http://hostname/api/entities/identifier/00amyWGct0y_ze4lIsj2Mw

Example response:

HTTP/1.1 204 No Content

PUT /api/entities/id

Updates an entity with the state submitted in the request. If successful, the server responds with 204 No Content. The request body must contain an Entity Object, and all properties are expected. The id, entitydefinition, relations and self properties are ignored, and may be omitted.

Example request:

PUT http://hostname/api/entities/2
Host: hostname
Content-Type: application/json
{
    "properties":{
        "Property2":43
    },
    "entitydefinition":{
        "href":"http://hostname/api/entitydefinitions/EntityDefinition1"
    }
}

Example response:

HTTP/1.1 204 No Content

DELETE /api/entities/id

Deletes the entity. If successful, the server responds with 204 No Content.

Example request:

DELETE http://hostname/api/entities/2

Example response:

HTTP/1.1 204 No Content

POST /api/entities/{entityId}/copy

Copies the entity with id=entityId into a target entity. The target entity can be a new entity or an existing one.

The general body structure of the request is:

{
  // Identifier of a copy profile that could be used for copying of an entity
  "copy_profile_identifier": string 

  // Id of an entity that will be updated by copying values from an original entity
  "copy_profile_id": long? 

  // Id of an entity that will be updated by copying values from an original entity
  "destination_entity_id": long? 

  // Relations copy options 
  "relation_copy_options": 
  [
    {
      // Relation name
      "relation": string 

      // Copy method
      "method": string 

      // Copy settings of related entities (the entire general structure)
      "related_copy_options": {} 
    }
  ]

  // Properties copy options: an array of properties configurations
  "property_copy_options": 
  [
    {
      // Property name
      "property": string 

      // Copy method
      "method": string

      // New property value
      "new_value": string 
    }
  ]
}
Important
  • All parameters are optional.
  • If you provide both the id and identifier of a copy profile, only the latter is considered.
  • If you provide either property or relation copy properties, the id and identifier of the copy profile are not taken into account.

The available relation copy methods are:

  • Keep: creates references to the same associated entities (keeps the same ids).
  • Remove: creates an empty relation (removes all ids).
  • Copy: creates references to copies of the associated entities (copies related entities and links them).
  • Overwrite: replaces all references with new ones (sets new ids).
  • Append: adds a new reference while keeping the existing ones (adds a new id to the existing ones).
  • Ignore: skips the relation and keeps the original values of the destination entity (in the case where the target entity is a new entity, the value is null).

The available property copy methods are:

  • Keep: applies the value of the source entity to the target entity (default method)
  • Remove: set the target property value to null.
  • Overwrite: overwrites the target property value with a new value.
  • Ignore: ignores the source entity value and keeps the value of the target entity.

The following examples illustrate different copy requests. The structures of the requests are identical, only their JSON payload changes.

POST http://hostname/api/entities/{entityId}/copy
Host: hostname
Content-Type: application/json

Example 1

{
  "property_copy_options": [
    {
      "property": "BlockName",
      "method": "Overwrite",
      "new_value": "Block A"
    }
  ],
  "relation_copy_options": [
    {
      "relation": "BlockToTask",
      "method": "Copy",
      "related_copy_options": {
        "property_copy_options": [
          {
            "property": "DoneDate",
            "method": "Remove"
          }
        ],
        "relation_copy_options": [
          {
            "relation": "TaskToAssetDeliverables",
            "method": "Remove"
          }
        ]
      }
    }
  ]
}

Example 2

{
  "copy_profile_id": 777,
  "destination_entity_id": 12345
}

Example 3

{
  "copy_profile_identifier": "M.EntityCopyProfile.SomeProfile"
}

Can we improve this article ? Provide feedback