Docs
Start typing to search…

Data Collections

Data is represented as a set of Data Collections that contain Data Records.

Data collections provide useful abstraction on top of the underlying API. They let you do the following:

  • Get schema of data record fields, including custom fields configured for a particular connection.
  • Perform CRUD operations on data records using a consistent API.
  • Understand which operations are possible and not possible for a given collection.
  • Subscribe to data change events even if webhooks are not supported by the underlying API.

List Data Collections

To get a list of data collections provided by the connector, do the following:

await integrationApp
  .integration('hubspot')
  .getDataCollections()

The result is a list of records with the following fields:

  • key – unique identifier of the data location.
  • name – human-readable name of the data location.

Get Data Collection Details

To get detailed information of a specific collection, do the following:

await integrationApp
  .integration('hubspot')
  .getDataCollection('{DATA_COLLECTION_KEY}')

To get collection for a specific connection (with all the custom fields and other connection-specific information), do the following:

await integrationApp
  .connection('hubspot')
  .dataCollection('{DATA_COLLECTION_KEY}')
  .get()

Parameters

Some Data Collections can be parametrized (if parametersSchema is provided in the specification).

Parameters are needed to navigate complex data collections, for example:

  • Salesforce has objects collection, and you need to specify objectType parameter to work with it in a meaningful way.
  • GitHub has issues collection, but you need to select a repository before doing anything with it (including getting a structure of the issue fields).

Adding parameters to a collection may change:

  • List of records in the collection (for example, adding a parameter like projectId for a collection containing tasks).
  • Fields schema for Data Records (for example, if projectId is added as a collection parameter, you can't add projectId field when creating a data record).
  • Available methods (for example, an application can search for all tasks, but not for tasks in a specific project).
  • Method of retrieving events (for example, webhooks may be available only for a task in a specific project, but not for all tasks in the application).

In integration.app API, parameters are specified as query parameters to any request to a Data Collection like this:

https://api.integration.app/connections/github/data/issues?repo=octocat/Hello-World

or this:

https://api.integration.app/connections/github/data/issues/create?repo=octocat/Hello-World

For most purposes, you can treat two collections with the same key but different parameters as two different collections.

To conveniently work with parametrized collections, we recommend using Data Sources.
They store collection parameters as a part of their configuration and automatically apply them to every request to a collection (among other convenient things).

Methods

Collections may provide any number of the methods listed below to perform actions on its data records.

find-by-id

Returns one data record by its id.

await integrationApp
  .connection('hubspot')
  .dataCollection('{DATA_COLLECTION_KEY}')
  .findById('{INPUT}')

Input:

  • id – id of the record to return.

list

Get a list of data records. For large collections, the results are paginated. In such cases, cursor is returned in the response to retrieve the next page.

await integrationApp
  .connection('hubspot')
  .dataCollection('{DATA_COLLECTION_KEY}')
  .list('{INPUT}')

Input:

  • cursor – cursor returned from the previous page of the results. If not provided, the first page is returned.

search

Search records by a substring. Supports type-ahead whenever underlying API supports it.

await integrationApp
  .connection('hubspot')
  .dataCollection('{DATA_COLLECTION_KEY}')
  .search('{INPUT}')

Input:

  • query – a string to search by.
  • cursor – cursor returned from the previous page of the results. If not provided, the first page is returned.

match

Returns a single record that matches provided fields. Uses whichever matching algorithm is supported by the underlying API.

await integrationApp
  .connection('hubspot')
  .dataCollection('{DATA_COLLECTION_KEY}')
  .match('{INPUT}')

Input:

  • fields – fields to match by. You can find the list of fields that can be used for matching in the collection specification.

create

Creates a record in the collection and returns its id.

await integrationApp
  .connection('hubspot')
  .dataCollection('{DATA_COLLECTION_KEY}')
  .create('{INPUT}')

Input:

  • fields – fields of the record to create. Must be present in the fieldsSchema of the collection. You can find the list of fields that can be used to create a record in the collection specification.

update

Updates one record by its id.

await integrationApp
  .connection('hubspot')
  .dataCollection('{DATA_COLLECTION_KEY}')
  .update('{INPUT}')

Input:

  • id – id of the record to update
  • fields – fields of the record to update. Must be present in the fieldsSchema of the collection. You can find the list of fields that can be used to create a record in the collection specification.

delete

Deletes one record by its id.

await integrationApp
  .connection('hubspot')
  .dataCollection('{DATA_COLLECTION_KEY}')
  .delete('{INPUT}')

Input:

  • id – id of the record to delete.

Events

We recommend using Data Sources to work with data collection events.
They provide a much simpler and more consistent interface than working with data collections directly.

Updated 16 days ago