getCopy() — Entity Service

General Description

The getCopy operation retrieves a copy of an entity with its related entities based on cascade reference rules.

Detailed Description

This operation creates a deep copy of an entity, including all its properties and related entities based on cascade reference rules defined in the entity properties. Unlike the standard getById operation, getCopy follows reference relationships and includes related entities in a multilevel JSON structure. This is particularly useful when you need to copy an entity along with its related entities or when you need to retrieve a complete object graph for display or processing.

Input Parameters

Parameter	Type	Required	Description
request	object	Yes	Object containing the entity identifier. It should have definitionType (string, name of the entity definition) and id (string, ID of the entity to copy).
token	string	No	Authentication token for your request. If not provided, the system will use the default API key from environment variables.
tenantCode	string	No	Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables.

Response

Success Response

{
    "success": true,
    "entity": {
        "id": "string",
        "title": "string",
        "createDate": "string",
        "lastUpdateDate": "string",
        // All other properties of the entity
        // Related entities as nested objects based on cascade references
        "relatedEntity1": {
            "id": "string",
            "title": "string",
            // Properties of the related entity
            // Potentially more nested related entities
        },
        "relatedEntities": [
            {
                "id": "string",
                "title": "string",
                // Properties of each related entity in the collection
            }
        ]
    }
}

Error Response

{
    "success": false,
    "error": "Error message describing what went wrong"
}

Example Usage

Get a Copy of an Entity with Related Entities

const result = await getCopy({
  request: {
    definitionType: "Order",
    id: "order-id-123"
  },
  token: "your-auth-token"
});

if (result.success) {
  const order = result.entity;
  console.log("Order:", order.title);
  
  // Access related customer entity (assuming a cascade reference)
  if (order.customer) {
    console.log("Customer:", order.customer.name);
  }
  
  // Access related order items (assuming a cascade reference)
  if (order.orderItems && Array.isArray(order.orderItems)) {
    console.log("Order Items:", order.orderItems.length);
    order.orderItems.forEach(item => {
      console.log(`- ${item.title}: ${item.quantity} x ${item.unitPrice}`);
      
      // Access product information if cascaded
      if (item.product) {
        console.log(`  Product: ${item.product.title}`);
      }
    });
  }
} else {
  console.error("Error:", result.error);
}

Copy an Entity for Duplication

// First, get a copy of the entity with related entities
const copyResult = await getCopy({
  request: {
    definitionType: "Product",
    id: "product-id-456"
  },
  token: "your-auth-token"
});

if (copyResult.success) {
  const productCopy = copyResult.entity;
  
  // Modify the copy as needed
  delete productCopy.id; // Remove ID to create a new entity
  productCopy.title = `Copy of ${productCopy.title}`;
  
  // Save the modified copy as a new entity
  const saveResult = await save({
    entDefName: "Product",
    entity: productCopy,
    token: "your-auth-token"
  });
  
  if (saveResult.success) {
    console.log("Created copy with ID:", saveResult.id);
  }
}

Additional Information

• The getCopy operation follows cascade reference rules defined in the entity properties.
• Cascade references are determined by the property's refType and additional cascade settings.
• All the data is returned with newly generated ids or no id set, except for the references where copyAction is set to reference.
• The title field is return as title + " Copy"
• You can use the save operation to save the copy.
• copyAction filed in property definition determines what happens with the related entities.(include, exclude, reference)
• The operation returns a multilevel JSON object with nested related entities, not just a flat entity.
• This operation is particularly useful for:
  • Creating duplicates of complex entities with related data
  • Retrieving a complete object graph for display or processing
  • Implementing copy functionality in user interfaces
• Unlike the standard getById operation, getCopy includes related entities directly in the response.
• The depth of cascading is determined by the entity definition's reference properties.
• For references marked as cascade, the related entities are included in the result.
• For references not marked as cascade, only the reference ID is included.
• Access permissions are enforced for both the main entity and all related entities.
• Performance may be impacted for entities with many cascade references or deep object graphs.