removeMappedItems() — Entity Service

General Description

The removeMappedItems operation removes mapped items from a parent entity, with options for cascade deletion based on relationship type.

Detailed Description

This operation allows you to remove the relationship between a parent entity and its mapped items. Depending on the relationship type and cascade settings, this operation may:

1. Simply break the reference between entities (for most relationships)
2. Delete the mapped items completely (if the relationship is marked as cascade or is a ManyToOne relationship)
3. Update the reference properties in both entities to maintain data integrity

Input Parameters

Parameter	Type	Required	Description
request	object	Yes	The mapped remove request object containing the mapping details.
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.

Request Object Structure

Property	Type	Required	Description
entDefName	string	Yes*	Name of the entity definition for the mapped items. Required if entDefId is not provided.
entDefId	string	Yes*	ID of the entity definition for the mapped items. Required if entDefName is not provided.
entityDef	object	No	Optional entity definition object with id and/or name properties.
items	array	Yes	Array of items to unmap from the parent entity. Typically contains IDs or identifying properties of the mapped items.
entityId	string	Yes	ID of the parent entity from which the items will be unmapped.
propName	string	Yes	Property name in the parent entity that holds the mapped items.

Response

Success Response

{
    "success": true,
    "deletedCount": number  // Number of removed mapped items
}

Error Response

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

Example Usage

Remove Items from an Order

const result = await removeMappedItems({
  request: {
    entDefName: "OrderItem",
    entityId: "order-123",
    propName: "items",
    items: [
      { id: "order-item-456" },
      { id: "order-item-789" }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log(`Removed ${result.deletedCount} items from the order`);
} else {
  console.error("Error:", result.error);
}

Remove Users from a Group (Reference Only)

// This will only break the reference between users and the group,
// not delete the user entities
const result = await removeMappedItems({
  request: {
    entDefName: "User",
    entityId: "group-456",
    propName: "members",
    items: [
      { id: "user-123" },
      { id: "user-456" }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log(`Removed ${result.deletedCount} users from the group`);
}

Remove Child Entities with Cascade Delete

// This will delete the comment entities completely because
// the relationship is marked as cascade
const result = await removeMappedItems({
  request: {
    entDefName: "Comment",
    entityId: "post-789",
    propName: "comments",
    items: [
      { id: "comment-111" },
      { id: "comment-222" }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log(`Deleted ${result.deletedCount} comments from the post`);
}

Additional Information

• The removeMappedItems operation handles different behaviors based on the relationship type:
  • For standard references (OneToMany, ManyToMany), it typically just breaks the reference
  • For ManyToOne relationships, it may delete the mapped items completely
  • For relationships marked with cascade delete, it will delete the mapped items
• The operation returns the number of affected items (removed mappings or deleted entities).
• When removing items from a relationship:
  • Reference properties in both entities are updated to maintain data integrity
  • If the reference is bidirectional, both sides of the relationship are updated
  • If cascade delete is enabled, dependent entities are also deleted
• For adding mapped items, use the saveMappedItems operation instead.
• Access permissions are enforced based on the provided token.
• The operation is permanent and cannot be undone, so it should be used with caution.
• Be particularly careful when working with relationships that have cascade delete enabled, as this will permanently delete the mapped entities.