saveMappedItems() — Entity Service

General Description

The saveMappedItems operation saves or updates mapped items (related entities) for a parent entity.

Detailed Description

This operation allows you to add or update related entities for a parent entity through a reference property. It's particularly useful for managing many-to-many or one-to-many relationships. The operation can create new related entities, update existing ones, and maintain the relationship between them and the parent entity.

Like the save and saveMulti operations, saveMappedItems supports complex JSON structures with nested objects and arrays. GSB automatically processes the data, performing inserts or updates for all nested entities and managing relationships based on the presence of primary keys.

Input Parameters

Parameter	Type	Required	Description
request	object	Yes	The mapped save 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 map to the parent entity. Each item can be a complex object with nested entities.
entityId	string	Yes	ID of the parent entity to which the items will be mapped.
propName	string	Yes	Property name in the parent entity that holds the mapped items.

Response

Success Response

{
    "success": true,
    "ids": [
        "string",  // ID of the first mapped item
        "string",  // ID of the second mapped item
        // Additional IDs in the same order as the input items
    ]
}

Error Response

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

Example Usage

Add Items to an Order

const result = await saveMappedItems({
  request: {
    entDefName: "OrderItem",
    entityId: "order-123",
    propName: "items",
    items: [
      {
        productName: "Smartphone",
        quantity: 1,
        unitPrice: 999.99
      },
      {
        productName: "Phone Case",
        quantity: 1,
        unitPrice: 29.99
      }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log("Added items with IDs:", result.ids);
} else {
  console.error("Error:", result.error);
}

Update Existing Mapped Items

const result = await saveMappedItems({
  request: {
    entDefName: "OrderItem",
    entityId: "order-123",
    propName: "items",
    items: [
      {
        id: "item-456",  // Existing item - will be updated
        quantity: 2,     // Updating quantity
        unitPrice: 999.99
      }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log("Updated item with ID:", result.ids[0]);
}

Add Users to a Group

const result = await saveMappedItems({
  request: {
    entDefName: "User",
    entityId: "group-789",
    propName: "members",
    items: [
      { id: "user-123" },  // Reference to existing user
      { id: "user-456" }   // Reference to existing user
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log("Added users to group");
}

Save Mapped Items with Complex Nested Data

const result = await saveMappedItems({
  request: {
    entDefName: "OrderItem",
    entityId: "order-123",
    propName: "items",
    items: [
      {
        productName: "Gaming Console",
        quantity: 1,
        unitPrice: 499.99,
        product: {
          id: "product-789", // Existing product - will be referenced
          name: "Next-Gen Console",
          category: "Electronics"
        },
        options: [
          {
            // New option will be created and linked to the order item
            name: "Extended Warranty",
            price: 49.99
          },
          {
            id: "option-456", // Existing option - will be updated
            name: "Premium Controller",
            price: 69.99
          }
        ],
        shippingDetails: {
          // New shipping details will be created and linked
          method: "Express",
          estimatedDelivery: "2023-06-20",
          tracking: {
            // Nested object within shipping details
            carrier: "FastShip",
            number: "FS123456789"
          }
        }
      }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log("Added complex order item with ID:", result.ids[0]);
}

Additional Information

• The saveMappedItems operation can both create new related entities and update existing ones.
• When an item has an ID, the system will update the existing entity if it exists.
• When an item doesn't have an ID, a new entity will be created.
• The operation maintains the relationship between the parent entity and the mapped items.
• For many-to-many relationships, the operation updates the join table appropriately.
• For one-to-many relationships, the operation updates the foreign key in the child entities.
• For removing mapped items, use the removeMappedItems operation instead.
• Access permissions are enforced based on the provided token.
• The operation returns an array of IDs for all saved mapped items, in the same order as the input items.

Complex Data Handling

• Each item in the items array can include complex nested objects and arrays.
• GSB automatically processes nested objects and arrays as related entities.
• For each nested entity:
  • If an ID is provided and exists in the database, the entity will be updated.
  • If no ID is provided or the ID doesn't exist, a new entity will be created.
• Nested entities execute their configured workflow and serverless save triggers just like entities saved directly.
• Relationships between entities are automatically maintained at all levels of nesting.
• One-to-many and many-to-many relationships are handled through arrays of objects.
• One-to-one relationships are handled through nested objects.
• The system intelligently determines whether to perform inserts or updates based on the presence of primary keys.
• All operations are performed in a single transaction, ensuring data consistency across all entities and their related data.
• If any part of the complex save operation fails, the entire transaction is rolled back.