Entity
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 Entity API is available in an interactive console that includes Try it functionality and allows you to download the OpenAPI definition file.
The following additional method is supported.
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
}
]
}
-
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 structure of the requests is 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"
}