> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # InsertDataItems # Package: externalDatabases # Namespace: ExternalDatabaseService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/external-databases/external-database-service-plugin/insert-data-items.md ## Introduction Adds one or more items to a collection. A data item object contains the `_id` and `_owner` fields. The response array must include the same items that were inserted, and each returned item must be added the `_createdDate` and `_updatedDate` fields. However, data items can also be inserted without an `_id` field. In that case, it is the service provider's responsibility to generate a unique ID for each item. --- ## REST API ### Schema ``` Method: insertDataItems Description: Adds one or more items to a collection. A data item object contains the `_id` and `_owner` fields. The response array must include the same items that were inserted, and each returned item must be added the `_createdDate` and `_updatedDate` fields. However, data items can also be inserted without an `_id` field. In that case, it is the service provider's responsibility to generate a unique GUID for each item. URL: null Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: collectionId, items Method parameters: param name: collectionId | type: collectionId | description: GUID of the collection in which to insert the items. | required: true param name: items | type: array | description: Items to insert. | required: true Return type: InsertDataItemsResponse - name: results | type: array | description: Response must include either the inserted item or an error. - ONE-OF: - name: item | type: object | description: Item that was inserted, updated or removed. - name: error | type: Error | description: Error indicating why the operation failed for a particular item. Learn more about [error types](https://dev.wix.com/docs/rest/assets/data/external-database-spi/understanding-error-types-in-the-external-database-connections-spi.md) in the External Database Connections service plugin. - name: errorCode | type: string | description: Error code. - name: errorMessage | type: string | description: Error description. - name: data | type: object | description: Additional error data specific to the error code. ``` ### Examples ### Insert items without an `_id` field Data items can be inserted without an `_id` field. In that case, it is the service provider's responsibility to generate a unique ID for each item. ```curl curl -X POST https://external-db.example.com/v3/items/insert \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Authorization: ' \ -d '{ "collectionId": "cities", "items": [{ "name": "New York", "_owner": "facda016-24ef-4909-a90e-70687f17f658" }] }' ``` ### Insert multiple items Inserts two data items to a collection. One insertion fails while the other succeeds. ```curl curl -X POST https://external-db.example.com/v3/items/insert \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Authorization: ' \ -d '{ "collectionId": "cities", "items": [{ "_id": "c285e77c-a86b-4361-a55f-c6b934d70187", "name": "New York", "_owner": "facda016-24ef-4909-a90e-70687f17f658" }, { "_id": "e831385d-d067-4905-a98a-456f5a526ca2", "name": "Paris", "_owner": "facda016-24ef-4909-a90e-70687f17f658" }] }' ``` ### Insert a single item into a collection ```curl curl -X POST https://external-db.example.com/v3/items/insert \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Authorization: ' \ -d '{ "collectionId": "cities", "items": [{ "_id": "c285e77c-a86b-4361-a55f-c6b934d70187", "name": "New York", "_owner": "facda016-24ef-4909-a90e-70687f17f658" }] }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.externalDatabases.ExternalDatabaseService.insertDataItems(request, metadata) Description: Adds one or more items to a collection. A data item object contains the `_id` and `_owner` fields. The response array must include the same items that were inserted, and each returned item must be added the `_createdDate` and `_updatedDate` fields. However, data items can also be inserted without an `_id` field. In that case, it is the service provider's responsibility to generate a unique GUID for each item. Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). - name: appId | type: string | description: GUID of an app. - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. - name: instanceId | type: string | description: The service provider app's instance GUID. param name: request | type: InsertDataItemsRequest - name: collectionId | type: string | description: GUID of the collection in which to insert the items. - name: items | type: array | description: Items to insert. Return type: PROMISE - name: results | type: array | description: Response must include either the inserted item or an error. - ONE-OF: - name: item | type: object | description: Item that was inserted, updated or removed. - name: error | type: Error | description: Error indicating why the operation failed for a particular item. Learn more about [error types](https://dev.wix.com/docs/rest/assets/data/external-database-spi/understanding-error-types-in-the-external-database-connections-spi.md) in the External Database Connections service plugin. - name: errorCode | type: string | description: Error code. - name: errorMessage | type: string | description: Error description. - name: data | type: object | description: Additional error data specific to the error code. ``` ### Examples ### Example of a `results` return value ```javascript import { externalDatabase } from '@wix/data/service-plugins'; externalDatabase.provideHandlers({ insertDataItems: async ( payload ) => { const {request, metadata} = payload; // Use the `request` and `metadata` received from Wix and // apply custom logic. return { // Return your response exactly as documented to integrate with Wix. // Return value example: results: [ { item: { name: "New York", _id: "c285e77c-a86b-4361-a55f-c6b934d70187", _owner: "facda016-24ef-4909-a90e-70687f17f658", _createdDate: { $date: "2021-01-02T03:04:05Z" }, _updatedDate: { $date: "2021-01-02T03:04:05Z" } } } ] } } }); ``` ### insertDataItems (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { externalDatabase } from '@wix/data/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { externalDatabase }, // Include the auth strategy and host as relevant }); async function insertDataItems(request,metadata) { const response = await myWixClient.externalDatabase.insertDataItems(request,metadata); }; ``` ---