Sharepoint 2013 : Building a BCS-enabled Business Solution : Building an Integrated BCS Solution with an App for SharePoint Containing an App for Office

- How To Install Windows Server 2012 On VirtualBox
- How To Bypass Torrent Connection Blocking By Your ISP
- How To Install Actual Facebook App On Kindle Fire
6/28/2014 9:29:43 PM

A common practice in SharePoint is to use document libraries that have prebuilt Office document templates associated with them as the content type. When the user clicks in the SharePoint ribbon to create a new document, the assigned document template can be created by default. The user can quickly fill in the template and save it back to the document library.

Historically, you could have document templates that also included a Visual Studio Tools for Office (VSTO) add-in that loaded into a task pane when the document opened. This add-in could virtually do just about anything that any Windows rich-client applications could do, including call Web services, retrieve data from back-end databases, and more. Data retrieval and the ability to then place the retrieved data into the document was a common pattern.

In the following exercise you create a SharePoint-hosted app that has a number of components: an app-level ECT that retrieves employees from an OData source, a document library that has a custom document template for employee referrals, and a document template content type that is a TaskpaneApp for Office and reads the employees in the app-level external list so users can click an employee and load their data into the Word document template.

TRY IT OUT: Building an Integrated BCS Solution with an App for SharePoint Containing an App for Office

This exercise shows you how to build an integrated solution where the app for SharePoint is SharePoint-hosted and contains an app-level ECT for its data source and an app for Office that consumes the external list data using REST.

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: C13EmpReferralBCSAppForOffice. Click OK.

3. In the New App for SharePoint dialog, set your Office 365 SharePoint Online Developer or Enterprise Preview 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 C13EmpReferralBCSAppForOffice project node in Solution Explorer and select Add ⇒ Content Types for an External Data Source.

5. In the Specify OData Source dialog, enter

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; this should all be familiar to you from the last exercise.

9. Open Word (2013) but before opening a document enter the phrase employee referral in the search bar and click the search icon. When the employee referral form is found, click it and then click Create.

10. Click on Your Logo Here, delete it, and change the Company Name to Company Inc.

11. If the Develop tab is not showing above your ribbon, click File ⇒ Options. Click Customize Ribbon and on the far right click the Developer check box. Click OK to close the dialog.

12. To add a content control to the document so the JavaScript in your app for Office can interact with a named object on the form, click the left side of the line beside the Employee Name. Click the Developer tab and click on the leftmost Aa in the Controls group. This is the Rich Text content control.

13. With the content control highlighted in the document (if it is not then click it), click the Properties button in the Controls group in the ribbon. In the Title text box, enter ccSPUserTitle and click OK.

14. Repeat the previous step three more times, placing your cursor in the leftmost position on the line beside E-Mail Address (in the Employee Information section), and Candidate Name and Phone No (in the Referral Information section), and provide these respective Title values for each of the content controls: ccSPUserEmail, ccEmployeeName, and ccEmployeePhone.

15. Select File ⇒ Options ⇒ Computer and browse to a location of choice to save this file. If prompted to Save, click OK, but you do not want to maintain compatibility. Close Word.

16. Return to Visual Studio, right-click the project, and click Add ⇒ New item. Select App for Office, name it EmployeeReferralForm and click Add.

17. In the Choose the type of app you want to create and where you want it to appear dialog, uncheck Excel and PowerPoint and click Next.

18. In the Choose a document for your app for Office dialog, select Insert the app into an existing document and click Browse to go to the location where you just saved the Word document. Select the document you saved and click Finish.

19. Right-click the project, and click Add ⇒ New item. Select List, name it EmployeeReferralLibrary, and click Add.

20. In the Choose List Settings dialog, drop-down the Default (Blank) list, select Document Library and click Next.

21. In the Choose a template for this document library dialog, select Use the following document as the template for this library, and click Browse. The Open file dialog opens with files showing from within your project. Open the OfficeDocuments folder, select the Word document, click Open and then click Finish. It’s important that you select the file that is within your project and not the original file you saved. The file within your project has been prepared to be an App for Office template.

22. Visual Studio opens the new document library in the list designer. Click on the Columns tab if it is not selected and click the Content Types button.

23. Click the Document row to select the entire row, right-click it and select Del to delete it. Click OK. This allows your content type to be the only one presented to the user of the list.

24. Click the List tab at the top of the list designer and copy the entire List URL.

25. In Solution Explorer, navigate to the AppManifest.xml file, right-click, and select View Code. Replace just the Pages/Default.aspx portion of the URL with Lists/EmployeeReferralLibrary. When you deploy the app for SharePoint, the list will be the default location to which the app opens.

26. The StartPage element should look like this:
27. For the code, in Solution Explorer, expand the Pages node and open the EmployeeReferralForm.html file. Replace all the XML between the body tags with the following:
<h2>App for Office using External List Data</h2>
<div id="Content"></div>
<div id="showEmployeeInfo"></div>
28. Expand the Scripts node and open the EmployeeReferralForm.js file. Replace all the JavaScript with the following:
var user;
var appWebURL; // URL of the appWeb

Office.initialize = function (reason) {
$(document).ready(function () {

var $getExternalDataButton = $('<input type="button"
value="Retrieve Employee BCS Data from
$("#Content").append($('<div id="Result"></div>'));

initializeConnectionToSharePoint(function () {
$("#Result").append($("<div>SharePoint references loaded,
click to load data.<div>"));

// Bind to the named Content Controls in the document

// Automatically load SharePoint user information
// into the Employee Content Controls in the form"bindings#ccSPUserTitle")
.setDataAsync(user.get_title(), function () { });"bindings#ccSPUserEmail")
.setDataAsync(user.get_email(), function () { });

$ () {

$(document).on('click','.dataRow', function () {
var id= $(this).attr('id');
var empFirstName = $('.FirstName[data-identity="' + id + '"]').text();
var empLastName = $('.LastName[data-identity="' + id + '"]').text();
var empHomePhone = $('.HomePhone[data-identity="' + id + '"]').text();

// Get the bound Content Controls for the Employee referral candidate
// and load with the data from the clicked on row in the table."bindings#ccEmployeeName")
.setDataAsync(empFirstName + " " + empLastName, function () { });"bindings#ccEmployeePhone")
.setDataAsync(empHomePhone, function () { });

function createContentControlBindings() {

Office.context.document.bindings.addFromNamedItemAsync("ccSPUserTitle", "text",
{ id: "ccSPUserTitle" }, function () { });

Office.context.document.bindings.addFromNamedItemAsync("ccSPUserEmail", "text",
{ id: "ccSPUserEmail" }, function () { });

Office.context.document.bindings.addFromNamedItemAsync("ccEmployeeName", "text",
{ id: "ccEmployeeName" }, function () { });

Office.context.document.bindings.addFromNamedItemAsync("ccEmployeePhone", "text",
{ id: "ccEmployeePhone" }, function () { });

function initializeConnectionToSharePoint(functionToExecuteOnReady) {
// Because calling back into SharePoint,
// need to dynamically load SP JavaSript references
var scriptbase = "/_layouts/15/";
$.getScript(scriptbase + "SP.Runtime.js",
function () {
$.getScript(scriptbase + "SP.js", getAppWebAndUser);

function getAppWebAndUser() {
var context = SP.ClientContext.get_current();
var website = context.get_web();
user = website.get_currentUser();
context.executeQueryAsync(onGetAppWebUserSuccess, onGetURLFail);

function onGetAppWebUserSuccess() {
appWebURL = website.get_url();
function onGetURLFail(sender, args) {
$("#Content").append($("<div>Problems connecting to SharePoint: "
+ args.get_message() + "</div>"));

function getEmployees() {
url: appWebURL +
"/_api/lists/getbytitle('Employees')/items?" +
headers: {
"accept": "application/json;odata=verbose",
"X-RequestDigest": $("#__REQUESTDIGEST").val()
success: showEmployees

function showEmployees(data) {
var items = [];
// Build table for showing Employees
items.push("<tr><td>Emp ID</td>" +
"<td>Last Name</td>" +
"<td>First Name</td>" +
"<td>Phone Number</td></tr>");
// Make each row and cell uniquely identifiable
$.each(data.d.results, function (key, val) {
items.push('<tr class="dataRow" id="' + val.BdcIdentity + '">' +
'<td class="employeeId" data-identity="'
+ val.BdcIdentity + '">' + val.EmployeeID + '</td>' +
'<td class="LastName" data-identity="'
+ val.BdcIdentity + '">' + val.LastName + '</td>' +
'<td class="FirstName" data-identity="'
+ val.BdcIdentity + '">' + val.FirstName + '</td>' +
'<td class="HomePhone" data-identity="'
+ val.BdcIdentity + '">' + val.HomePhone + '</td></tr>');



29. Press F5 to start debugging.

30. Log in to the site when the browser opens. Above the ribbon, click Files ⇒ New Document and select EmployeeReferralLibraryContentType.

31. When Word opens, your document template and TaskpaneApp will load. Notice the document has already filled in your login employee information.

32. Click the Retrieve Employee BCS Data from SharePoint button. When the employee data loads in the task pane, click any employee in the list to see his data load into the template, as shown in Figure 1.



33. Save the document into the document library if you want to view it in the Word Web app or open it again in Word. Close Word.

34. In the browser, refresh the document library to see your newly saved file. View it if you choose to, and then close the browser to stop debugging.

How It Works

In this exercise you worked a number of components into an integrated solution. Along with knowing how to stitch a solution like this together, the key part is seeing how to write the JavaScript code to retrieve data from SharePoint from an app for Office when its HTML page is also hosted on SharePoint. Because the document template is opened in Word from within the context of a logged-in Office 365 user, you don’t need to be concerned about authentication to SharePoint. Therefore, after the TaskpaneApp HTML page is loaded, you can construct the URL for $.getScript() to reach into the /_layouts/15/ directory in your SharePoint site to load and execute the SP.Runtime.js. Upon its success, you load and execute the SP.js. With these loaded, the stage is set for both JavaScript client-side object (CSOM) calls and REST-based calls to retrieve the desired data from SharePoint. First, the Web and user information are retrieved via CSOM and loaded into variables for later use. Then, when the user clicks the button in the TaskpaneApp to load the employee data, a REST call is made to retrieve and display the employee information.
Because the table to display the employee data is being added to the DOM after the DOM has been loaded, you need a way to late-bind a click event to the table so when the users click a row in the table, the appropriate data can be inserted into the desired document content control. To accomplish this you added a class named datarow to the <tr> element and an id attribute with the unique BdcIdentity value from the external list data item. Then for each cell in the row, you added a class for the name of the <td> element and a custom data- attribute so the cell data value can be retrieved directly.

These steps all come together in the $(document).on() function. This function essentially late-binds a click event to the data row (identified by the datarow class) so when any row is clicked, the data values are retrieved and can be appropriately loaded into the document content controls. To do this, you use the method passing in the binding name for the content control and then use .setDataAsync() passing in the data retrieved from the data row — and that’s it. The user has a form automatically populated with data based on her user login retrieved via CSOM and employee data from an OData source retrieved via REST from the SharePoint external list and presented in a clickable table.

Although this exercise focuses on an app for Office reading data from an app-level external list, the pattern for loading the SP.Runtime.js and SP.js is one you can use extensively when building your SharePoint-hosted apps. By definition, if a user is using your SharePoint-hosted solution, you have an authenticated context and your code has permissions to access any artifacts that you installed into the appWeb, lists, libraries, app-level BCS ECTs, and so on. However, sometimes you want your app to reach up a level and read/write data in the host Web. This, too, is easy enough to do: simply open the AppManifest.xml file in the Manifest Designer and under the Permissions tab select a scope of Web and the permission level you desire. On the install of your app, you then receive the “Trust It” prompt to verify that you will allow this app for SharePoint to have the level of access it is requesting. After the app is trusted, your CSOM or REST calls will have access to the SharePoint site within the scope designated.

  •  Business Connectivity Services in Apps for SharePoint 2013 : Building an App-level BCS Solution for Office 365 SharePoint Online
  •  Business Connectivity Services in SharePoint 2013 : Adding a Business Data Connectivity Model to Office 365 SharePoint Online
  •  Remote Event Receivers in Sharepoint 2013 : Introducing Remote Event Receivers
  •  InfoPath with SharePoint 2010 : Apply Rich Text to the Entry
  •  InfoPath with SharePoint 2010 : Add Changed Event Code for Tracking Changes
  •  InfoPath with SharePoint 2010 : Set Up the Form for Tracking Changes
  •  Sharepoint 2013 : Farm Management - Rename a Server on the Farm, Display the Configured Managed Paths
  •  Sharepoint 2013 : Farm Management - Retrieve the System Accounts, Retrieve Managed Accounts
  •  Sharepoint 2013 : Farm Management - Refresh Installed Products,Change the Port of Central Admin,Change the Farm Passphrase
  •  Sharepoint 2013 : Farm Management - Review Farm Configuration Values,Set the Farm Configuration Values
    Top 10
    - Microsoft Visio 2013 : Adding Structure to Your Diagrams - Finding containers and lists in Visio (part 2) - Wireframes,Legends
    - Microsoft Visio 2013 : Adding Structure to Your Diagrams - Finding containers and lists in Visio (part 1) - Swimlanes
    - Microsoft Visio 2013 : Adding Structure to Your Diagrams - Formatting and sizing lists
    - Microsoft Visio 2013 : Adding Structure to Your Diagrams - Adding shapes to lists
    - Microsoft Visio 2013 : Adding Structure to Your Diagrams - Sizing containers
    - Microsoft Access 2010 : Control Properties and Why to Use Them (part 3) - The Other Properties of a Control
    - Microsoft Access 2010 : Control Properties and Why to Use Them (part 2) - The Data Properties of a Control
    - Microsoft Access 2010 : Control Properties and Why to Use Them (part 1) - The Format Properties of a Control
    - Microsoft Access 2010 : Form Properties and Why Should You Use Them - Working with the Properties Window
    - Microsoft Visio 2013 : Using the Organization Chart Wizard with new data
    - First look: Apple Watch

    - 3 Tips for Maintaining Your Cell Phone Battery (part 1)

    - 3 Tips for Maintaining Your Cell Phone Battery (part 2)
    programming4us programming4us