Add-in-scoped external content types in SharePoint
Learn about external content types that are installed or scoped at the add-in level in SharePoint and enable you to create data-rich SharePoint Add-ins using external data sources.
Overview of add-in-scoped external content types in SharePoint
In SharePoint 2010, you can install and use external content types only at the farm level. This often causes problems for developers because even for simple applications, an administrator had to be involved because of the access rights that are needed to install at the farm level.
In SharePoint, applications are basically isolated into more autonomous units called add-ins. Add-ins contain all the resources they need to run. This approach enables a running application to be insulated from other applications. The benefits of this architecture are as follows:
You can create add-ins that are aligned with the new application model of SharePoint.
You can create add-ins that access external data from SAP, Netflix, and proprietary and other types of data without involving the tenant administrator.
Access to external applications is maintained through Business Connectivity Services (BCS), which provides a consistent and uniform interface that can be used by other SharePoint applications.
Add-in-scoped external content types provide access to external data within an app.
Prerequisites for working with add-in-scoped external content types
The following are the requirements for developing external content types that are scoped at the add-in level:
Visual Studio 2012
Office Developer Tools for Visual Studio 2012
SharePoint
For information about setting up your SharePoint development environment, see Set up a general development environment for SharePoint.
Add-in-scoped external content type essentials
Table 1 contains some core concepts that you should be familiar with when working with add-in-scoped external content types.
Table 1. Core concepts for understanding add-in-scoped external content types
| Article | Description |
|---|---|
| External content types in SharePoint |
Learn how to create BCS external content types. |
| SharePoint Add-ins |
Learn about the new add-in model in SharePoint that enables you to create add-ins, which are small, easy-to-use solutions for end users. |
| Get started creating SharePoint-hosted SharePoint Add-ins |
Learn how to create a basic SharePoint-hosted add-in by using the Office Developer Tools for Visual Studio 2012. |
What can you do with add-in-scoped external content types?
The primary reason for adding an add-in-scoped external content type is to provide access to external data from an individual add-in. This allows you to do the following:
Limit access to external content types to a particular app.
Deploy external content types within an app.
Create add-in-scoped external content types
The concept of a file-based metadata catalog was introduced in SharePoint 2010. It enables you to specify a file that contains the XML needed to define external content types. This file can be deployed within a WSP package and pertains only to the application that it is scoped for. By using this metadata file, external content types can be restricted to the add-in level.
In SharePoint, SPListDataSource has been modified to add a property that indicates the scope of the application.
This class serves as the bridge between SPList and an external list. Use the associated SPList to retrieve entity fields and data. Retrieve an instance of SPListDataSource from the HasExternalDataSource property. When HasExternalDataSource is not null, the SPList object's data is external to SharePoint.
When you want to add an add-in-scoped external content type, this property is set to Add-in.
The MetadataCatalogFileName property is used to define the BDC model file that contains the external content type definition. This property can be defined declaratively or programmatically, but not in the SharePoint user interface (UI).
The following example shows how to set the MetadataCatalogFileName property declaratively.
<DataSource>
<Property Name="Entity" Value="Customer" />
<Property Name="EntityNamespace" Value="SAP" />
<Property Name="LobSystemInstanceName" Value="SAPClient1" />
<Property Name="SpecificFinder" Value="ReadCustomer" />
<Property Name=" MetadataCatalogFileName" Value="BDCMetadata.bdcm" />
</DataSource>
Note
Site administrators can install add-ins that use App-Scoped-ECTs, but only SiteCollection administrators can grant permissions for Apps to Use BCS Connections.
Deploy an add-in-scoped external content type in a custom Feature in a WSP file
You can include a BDC model in a WSP file for deployment. The following example shows how to include a BDC model in the app.
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<BdcModel Path="BDCMetadata.bdcm">
</BdcModel>
</Elements>
Important
Only one BDC model file can be included per add-in. While the file name in this example is BDCMetadata.bdcm, the model file can actually be any name you choose as long as the file name matches that is in the Path attribute of the BDC model file.
Note
Only Open Data protocol (OData) connections are allowed for add-in-scoped external content types.
Set security credentials for an external system
In order to access data on a secured external system, you must configure the BDC model with the appropriate credentials.
The following example shows how to set security credentials for an external system in add-in-scoped external content types by modifying the Elements.xml file of the app.
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<BdcModel Path="BDCMetadata.bdcm">
<LobSystem Name="SAP">
<LobSystemInstance Name="SAPInst" RequireCredentials="true" CredentialsDescription="Credentials to connect to SAP"/>
</LobSystem>
<LobSystem Name="SQL">
<LobSystemInstance Name="App Database" DataSource="SQL-Azure" RequireCredentials="true" />
</LobSystem>
</BdcModel>
</Elements>