Share via

Using the Data Connector

  • Article

The ISPWDataConnector is the connection between your add-in's dataset and the underlying tool data.

SPWDataConnector

ISPWDataConnector provides a data bridge between an add-in tool and the tool’s underlying data storage. ISPWDataConnector provides the following capabilities:

  1. Fill a dataset with all records in a set from the tool's underlying data storage.

  2. FillSchema a dataset with the structure in a set from the tool's underlying data storage.

  3. Query a table in the underlying data storage and fill a dataset with all records that match the query.

  4. Update the underlying data storage based on the changes in one or more datasets.

  5. Provides create, read, update, and delete support for one or more attachments on a data record.

  6. Provides events that enable you to track changes in the underlying data storage.

ISPWDataConnector operates on datasets. A dataset contains one or more user tables and an attachment table. If you fill a dataset, the dataset contains the tables and rows defined in the views contained in the set in the manifest that matches the dataset name. If you fill the schema in a dataset, the dataset contains the tables defined by the set with the matching name but will not have any rows in the tables. If you create a dataset with a query, the dataset is assigned a name equal to the query name and has a table that contains the query results. The attachment table contains read-only attachment metadata. It contains the attachments for all user tables in the dataset.

The datasets created by ISPWDataConnector are copies of the underlying data and do not have a dynamic connection to it. If the underlying data is updated, the datasets are not automatically updated.

System Columns in DataRows and Attachments

Each user table contains the following read-only system columns:

  • _RecordID—record identifier that is unique for the add-in tool instance.

  • _Created—date-time that specifies when the record was created.

  • _CreatedBy—name of the workspace member who created the record.

  • _CreatedByURL—identity URL of the workspace member who created the record.

  • _Modified—date-time that specifies when the record was last modified.

  • _ModifiedBy—name of the workspace member who last modified the record.

  • _ModifiedByURL—identity URL of the workspace member who last modified the member.

  • _HasConflicts—specifies whether any conflict records exist for the record.

When you add a new row to a table in the dataset, the _RecordID column is assigned a temporary value and the other system columns are not assigned values. When you call the Update method, the _RecordID and other system columns are assigned values that are based on the values in the new records in the underlying data storage. When you update an existing row in the dataset, the system columns are left unchanged until you call Update when they are updated if the corresponding system field in the underlying data is changed.

Each attachment table contains the following read-only system columns:

  • _AttachmentID—attachment identifier that is unique to the add-in tool instance.

  • _FileName—file name and extension of the attachment.

  • _FileSize—file size in bytes of the attachment.

  • _Tag—tag defined by the add-in developer.

  • _HasConflicts—specifies whether any conflict attachments exist.

  • _CreatedDate—date that specifies when the attachment was created.

  • _CreatedBy—name of the workspace member who created the attachment.

  • _CreatedByURL—identity URL of the workspace member who created the attachment.

  • _ModifiedDate—date that specifies when the attachment was last modified.

  • _ModifiedBy—name of the workspace member who last modified the attachment.

  • _ModifiedByURL—identity URL of the workspace member who last modified the attachment.

  • _ContentState—indicates whether the contents of the attachment were current when the dataset was filled or created by a query.

  • _ParentID—RecordID of the DataRow that contains the attachment.

Create, Read, Update, and Delete Operations on Data

The following are the supported Create, Read, Update, and Delete (CRUD) operations for data; each operation is bound inside a single transaction in the underlying data storage. The transaction guarantees that there are no changes in the underlying data storage during the operation. But there can be changes in the underlying data storage between operations. There is no other mechanism for an add-in to place a transaction lock on the underlying data storage.

  • FillSchema—enables a tool developer to fetch schema for dataset tables. The FillSchema method is shown in the following example:

    DataTable[] dts = dataConnector.FillSchema(dataSet1);

  • Fill—fetches data based on the dataset name. After the method has successfully finished, the dataset contains table data and an attachment table. The Fill method is shown in the following example:

    int rowsRead = dataConnector.Fill(m_PhotosSet);

  • Query—executes the specified query and returns a dataset that contains the query results and an attachment table. Query is shown in the following example:

    DataSet queryResults = dataConnector.Query(Query);

  • Update—persists the data and attachment changes from the dataset to the tool’s underlying data storage.