This exercise shows you how to create
an app-level scoped BCS connection and then access the external list
for the app for SharePoint via a REST call.
1. Run Visual Studio 2012 as Administrator. Select New Project.
2. In the New
Project dialog, expand the Templates ⇒ Visual C# Office/SharePoint Apps
nodes. Select App for SharePoint 2013 and provide the Name: C13EmployeeBCSApp. Click OK.
3. In the New
App for SharePoint dialog, set the Office 365 SharePoint Online site
URL to use for debugging and choose SharePoint-hosted as the location
to host your app for SharePoint. Click Finish.
4. Right-click the C13EmployeeBCSApp project node in Solution Explorer and select Add Content Types for an External Data Source.
5. In the Specify OData Source dialog, enter http://services.odata.org/Northwind/Northwind.svc/.
6. In the Data Source Name, enter Northwind OData Producer. Click Next.
7. In the Select the Data Entities dialog, select Employees and confirm that the Create list instances for the selected data entities check box is checked. Click Finish.
8. Visual Studio creates an External Content Types node in the Solution Explorer. Expand the nodes until you see Employee.ect,
and then double-click the node to open the ECT designer. In the
designer you can select individual rows to delete data elements, and
you can also add filters in the designer; a filter limit of 100 is set
by default.
9. In the Solution Explorer, open the Pages node, right-click Default.aspx, and select View Markup.
10. Locate the
<asp:Content...> element, and replace the entire
<div>...</div> containing the
id="message" paragraph with the following elements:
<h1>App-level BCS OData Connection</h1>
<div id="showEmployeeInfo"></div>
11. In the Solution Explorer expand the Scripts node and click on the App.js file to open it.
12. Replace all the code with the following:
$(document).ready(function () {
window.C13EmployeeBCSApp = window.C13EmployeeBCSApp || {};
C13EmployeeBCSApp.Grid= function (hostElement, spWebURL) {
this.hostElement = hostElement;
// Verify proper structure for SharePoint Web URL for REST call.
if (spWebURL.length > 0 &&
spWebURL.substring(spWebURL.length - 1, spWebURL.length) != "/")
spWebURL += "/";
this.spWebURL = spWebURL;
}
C13EmployeeBCSApp.Grid.prototype = {
init: function () {
//Retrieve data from app-level External List via REST
$.ajax({
url: this.spWebURL +
"_api/lists/getbytitle('Employee')/items?" +
"$select=BdcIdentity,EmployeeID,LastName,FirstName,Title,HomePhone",
headers: {
"accept": "application/json",
"X-RequestDigest": $("#__REQUESTDIGEST").val()
},
success: this.showEmployees
});
},
showEmployees: function (data) {
var items = [];
// Build table for showing Employees
items.push("<table>");
items.push("<tr><td>Employee ID</td>" +
"<td>Last Name</td>" +
"<td>First Name</td>" +
"<td>Title</td>" +
"<td>Phone Number</td></tr>");
$.each(data.d.results, function (key, val) {
items.push('<tr id="' + val.BdcIdentity + '">' +
'<td>' + val.EmployeeID + '</td>' +
'<td>' + val.LastName + '</td>' +
'<td>' + val.FirstName + '</td>' +
'<td>' + val.Title + '</td>' +
'<td>' + val.HomePhone + '</td></tr>');
});
items.push("</table>");
$("#showEmployeeInfo").html(items.join(''));
}
}
ExecuteOrDelayUntilScriptLoaded(getEmployees, "sp.js");
});
function getEmployees() {
var gridEmployee = new C13EmployeeBCSApp.Grid($("#showEmployeeInfo"),
_spPageContextInfo.webServerRelativeUrl);
gridEmployee.init();
}
13. Press F5 to start debugging. When the Site Contents page loads, click the C13EmployeeBCSApp tile.
14. After the app loads, your page should look like Figure 1.
15. While the app for SharePoint is running you can go back to Visual Studio and set breakpoints in the App.js file and then refresh the browser page to track your way through the code.
16. But just
as important, knowing how to find out where SharePoint is putting
things and how to access them when at the app-level is always good. To
take a look, in the browser trim the URL in the address bar from the
tail end back to just after the / following C13EmployeeBCSApp/. This preserves the root appWeb URL where your app for SharePoint is installed. Now you can use the REST _api for SharePoint to look at your appWeb structure in the browser.
17. Following the root appWeb URL, type _api/web/ to see the base information about your appWeb.
18. Following _api/web/, type lists/ to see the lists that were deployed to your appWeb. There are several, but the two key lists are the Employee and BusinessDataMetadataCatalog lists.
19. To view the Employee list, you can use the same syntax you used in your App.js file to retrieve the Employee list data, so use _api/lists/getbytitle('Employee')/items in your browser. You can further refine your return payload by appending ?$select=BdcIdentity,EmployeeID, LastName,FirstName,Title,HomePhone to the previous URL.
20. Navigate to the BusinessDataMetadataCatalog via _api/web/lists/BusinessDataMetadataCatalog/; notice that it’s just a document library inside your appWeb.
21. To make this a little more concrete so that your .bdcm
file is stored in a standard document library, you can navigate to this
list and display it natively within your appWeb, too. Trim your base
URL back to the root again as called out in step 16 and append BusinessDataMetadataCatalog/Forms/allitems.aspx to see your BDCMetadata file in its appWeb document library. Since this is a standard document library, you can download the .bdcm file if you choose.
22. Navigate to the external list created for your app for SharePoint by appending Lists/Employee/ to your root appWeb URL.
23. Close the browser and the app for SharePoint will be retracted.
In this exercise you worked through
how nicely Visual Studio tooling helps you to create an external
content type by connecting to an OData producer (data source). Although
SharePoint supports a number of connection methods for tenancy-wide BDC
Models, Apps for SharePoint only support OData connections. Also, an
app for SharePoint can only have one BDCMetadata.bdcm
file associated with it; however, multiple entities can exist within
the external content type for the app for SharePoint. If you download
the BDCMetadata.bdcm file from its document library location in the appWeb and open it in Notepad, you can map it to the Property Values in the external content type Elements.xml file. Using the BDCMetadata.bdcm
file in an app for SharePoint is essentially an extension of the
file-based metadata catalog capability introduced in SharePoint 2010.
It is just being put to practical use here in a document library inside
an app for SharePoint.
The modifications to the HTML were
minimal and the JavaScript did all the work. The primary work of the
JavaScript was to use the relative URL retrieved from the SharePoint
page context, and ensure it was properly formed to serve as the basis
for building out the REST URL. Essentially the code just checks to see
whether the URL has a trailing slash and if it doesn’t, one gets
appended. From that point on the process is pretty straightforward: if
the REST URL access is successful then an HTML table will be built and
the returned data will be added in accordingly as the SharePoint page
is displayed. This simple example should get your creative juices
flowing when considering the wealth of possibilities in accessing OData
data sources in Apps for SharePoint and being able to retrieve any data
you want to display via REST!
The last part of the exercise was to mainly show that by simply using the REST-based _api
against your appWeb you can discover and get eyes on anything that is
being deployed in your app for SharePoint. A developer always feels at
a disadvantage when he or she can’t get visibility into something. The _api provides the way for you to interrogate your appWeb just as if it were any other site in SharePoint.
