Working with External Content Types in SharePoint 2010 and Microsoft Office

A Collaboration Feature
This document will explore the creation of External Content Types in SharePoint 2010 and then using them in SharePoint lists and libraries and also showing how to pass this data back to several Microsoft Office applications. Antonovich, Michael P. 3/21/2011

Contents
Create an External Content Type .................................................................................................................. 2 Steps to Create an External Content Type ................................................................................................ 2 Display the External Content Type in an External List ................................................................................ 15 10 Things You Cannot Do with an External List ...................................................................................... 19 Using External Content Type in a Custom List ........................................................................................ 19 Features of a Custom List with External Data ......................................................................................... 25 Steps to Edit the Lists Edit Form ............................................................................................................ 26 Using External Data with Outlook 2010 .................................................................................................. 27 Using External Data in Libraries .............................................................................................................. 43 Next you will create the Document Library ............................................................................................ 50 Upload Documents into the Library ........................................................................................................ 54 Using External Data in your Word Document ......................................................................................... 57

Create an External Content Type

This entry is the first of a series of entries that will talk about how to work with the new BCS in SharePoint 2010 to access External data. To kick things off, Im going to show how to connect to a SQL Server table and use it within SharePoint as an External List. To begin, you need to define an External Content Type. To do this, we are going to use two tools. The first tool is SharePoint Designer 2010. We will use this tool to create the basic definition of the external content type. Then after saving our new content type, we will switch to Central Administrator to set permissions for the content type so we can use it in our web page. Although an External Content Type once defined can be used anywhere within your SharePoint farm, you have to start by referencing one of your web sites from within SharePoint Designer. Although Im going to use my own site and data file, Im going to list the steps you need to follow so you can try out this simple no-code technique.

Steps to Create an External Content Type

1. First you need to make sure that that the Business Data Connectivity Service is running. a. Click Manage Service Application in the Application Management group.

b. Locate the Business Data Connectivity Service and make sure that it is started.

If it is not running, start it now. 2. Open SharePoint Designer 2010 from your Start menu. a. From the File menu, click on Sites in the left navigation.

b. Click the Open Site button if you havent opened the site before in SharePoint Designer. c. Enter the URL of your site in the Site Name text box and click Open.

d. After SharePoint Designer opens the site, click External Content Types in the left navigation.

e. If you have not yet defined an External Content Type, the list in the center will be empty. Click External Content Type from the New group of the External Content Types ribbon to begin the definition of a new content type.

f.

In the External Content Type Information group, define a name for your content type. Pick a name that clearly identifies the content type. Spaces are allowed when defining the name.

g. The value you enter in the Name text box is automatically copied to the Display Name. However, you can change the Display Name if you want. h. The only other field we will change here is for the External System. Click on the link to define the connection to the database. If you already have connections defined, you can reuse one of the existing one. However, for this part of the exercise, lets assume that you need to create a new connection.

i. j.

Click the Add Connection button as shown in the previous screen. You next need to define the External Data Source Type. SharePoint Designer provides three choices. To use a SQL Server database, select SQL Server from the Data Source Type and click OK.

k. The next dialog will ask for the Connection properties including the name of the database server and the database itself. You can then provide a name for the connection. I often use the name of the table or view that I will be using.

l.

Finally, you need to specify how you want to connect to the server. By default, Web Services recommends using Connect with Users Identity before clicking OK.

m. SharePoint Designer validates the connection and displays the database name. You can expand this into three items: Tables, Views, and Routines (these are stored procedures).

n. If you want to use a table, click the square with the plus sign to expand the table branch to show all the tables. o. Locate the table you want and right click on it. At this time you need to define the operations that you want to allow through this connect. You must define at least once operation. In the dropdown list, you will see operations that include:

p. If you want to add, edit, and delete items from this table through your SharePoint list, you should select Create All Operations from this dropdown list. q. This will open another dialog window, the first will show the selected Operation Properties.

r.

On the second screen of this dialog, Parameters, you can select or deselect the columns you want to include. You can modify the display names of the columns. But most important, this page probably displays several warnings and perhaps even a few errors. The most common warning is to select a column as the field to be used when this content type is used in a drop down list.

Typically the picker needs to uniquely identify each row in the table, but you do not want to use a numeric id because most people will not associate that numeric value with the data they want. Fortunately, you can have a multi-field picker. Simply click on the first field you want to use in the picker and then select the checkbox in the right side of the dialog next to Show in Picker.

Then repeat this process for each additional field you want to appear in the picker. You may also get warnings for fields that are read-only and required such as auto-generated id fields. You can safely ignore these warnings with one exception. If a field is marked Read-Only, it cannot be marked Required. Uncheck the Required option. s. On the third page of this dialog, Filter Parameters, you can field the number of rows that you want to include. Obviously, the more rows you include the more time it can take to display the list or dropdown. However, this is again just a warning and you can ignore it if you are using the content type as a lookup dataset from a relatively small table.

t. Click the Finish button to complete the definition. u. At this point, you can save your new content type by right clicking on the tab of the page in the center section and selecting Save. This will save your definition to the metadata store for the web farm.

v. Right click on the tab of the content type a second time and click Close to exit this portion of SharePoint Designer. You can also close SharePoint Designer at this time. While you have defined an External Content Type at this point, you still cannot use it. You can try, but you will find that it will not retrieve data from your external data source. That is because you have not defined permissions to use the content type yet. To do this, follow these steps: 1. Open Central Administration and select Manage Service Applications from the Application Management group again.

2. This time when you click on Business Data Connectivity Service, you will see your external content type listed. To assign permissions to the content type follow these steps: 3. Hover over the external content type name and click the arrow to open the dropdown menu when it appears.

4. Select Set Permissions from the list of options. 5. In the dialog that appears enter the accounts (individual or group accounts) to which you want to initially assign permissions. Like adding users to groups in a SharePoint site, use the Check Names option to make sure that SharePoint recognizes the names or groups that you enter.

6. Click the Add button to add your accounts or groups. 7. If not selected in the second list box, select the accounts or groups that you want to assign permissions to. 8. In the third list box are four permission options: Edit, Execute, Selectable in Clients, and Set Permissions. For an administrator I normally would select all four permissions. Two of the permissions are especially interesting. Selectable in Clients allows you to use the external data in clients running within SharePoint such as Word documents, Outlook, and InfoPath. The Set Permissions option allows the selected user to add permissions to others.

9. Click OK to complete the setting of permissions. You can now also close Central Administration.

Display the External Content Type in an External List

Your External Content Type is now ready to use. Next go back to your site and select Site ActionsMore Options.

1. Select List from the Filter By selections in the left menu.

2. Select External List as your list type and click Create.

3. As with all list, you need to define a Name, an optional description, and navigation. You have seen this probably hundreds of times. The new addition is the Data Source Configuration. Here you want to click on the second icon after the text box (with the tool tip: Select External Content Type).

4. From the list displayed, select the external content type you want to use. Note that all external content types defined in the entire farm appear in this list.

5. Click Create to create the list. It may take a few seconds, but you will shortly see your list displaying data from the SQL Server table defined in this connection.

The next section covers more about how this list works.

10 Things You Cannot Do with an External List

Now that you have a SharePoint list (See post from March1st) populated with external data from a SQL Server table, what can you do with it and what limitations do you have to deal with? Perhaps it is easier to say that the External List works just like any other SharePoint list except for the following: 1. You cannot switch to datasheet mode to edit the data in the list. However, given the edit operation permission, you can edit individual records by using the record dropdown and selecting Edit. 2. You cannot create new columns for the list. If you need to add columns, you must update the SQL Server table and rebuild the External Content Type and the External List. On the other hand, if you want to remove some of the column or filter the rows, you can either modify the default view or create additional views to meet that need. (Next time we will look at adding external data columns to a custom list so that you can have columns unique to the SharePoint side of the list.) 3. You cannot export the data to Excel or open the data with Access. Of course, both of these Microsoft tools support the use of data connections which could directly connect to the same SQL tables without the extra stop of going through a SharePoint list. 4. You cannot define an RSS Feed to notify someone when a change occurs to the list. 5. You cannot assign a workflow to the list. 6. You cannot create folders and store items in individual folders. This limitation makes sense if you remember that the data coming from a table or view in SQL Server is essentially a flat file. 7. You cannot have attachments to individual records. 8. There is no version history for changes to items in an External List. 9. You cannot define item level permissions to items in an External List. 10. Surprisingly and disappointingly, External Lists do not let you modify the form used to edit the list items. This limitation is the one that bothered me the most. Next, we will look at using External Content Types in conjunction with Custom Lists to see how well they work there.

Using External Content Type in a Custom List

In my earlier blog entries, you saw how to create an External Content Type to connect to a SQL Server table and how to display that data in an External List. Did you know that you can also use that external data in a custom list? I'm going to assume you still have your external content type and begin by going to any site in the web farm. Remember that the external content types you define are stored in Central Administrator and work across the entire web application. 1. Open your site and create a new custom list (This will also work for libraries). With your list open, click on List Settings.

2. In the Columns section, you see all the defined columns for the list/library. Beneath the list are several options that you can perform by clicking on them. The first option is: Create Column.

3. Clicking this option opens the New Column dialog. For the column name, you can use any name unique to your list/library. The important part is to select the column type: External Data. When you select this type, the properties in the Additional Column Settings include the field External Content Type that lets you select, by clicking the second button to the right of the field from the available External Content Types you have defined so far.

4.

Select one of the External Content Types that you have previously defined.

5. After selecting an external content type, the settings page updates to display beneath the selected content type a set of properties related to the selected content type. First you must select a field from the content type to associate with the external data column you are adding. You can select the field from a dropdown list of the fields in the external content type. SharePoint displays this field in this column when you select a record from the external content type. Below this property is a checkbox where you can add all fields from the External Content Type to the list. Alternately, you can use the checkboxes to the left of each field name to custom select which fields you want to include in the custom list. Why do this? When you select a record from the external data for this column, SharePoint populates the other fields chosen to appear in the list with data values from the same record.

6. Clicking OK at the bottom of the column properties page saves the definition of the external data column. 7. Now if you return to your custom list and open it, you will see that the default view includes not only the custom columns defined for the list (if any), but also all the external columns selected from the external content type.

8. Go to the items ribbon and add a new item. The default form that SharePoint builds for the list/library appears in a popup window. You will notice that all of the standard custom fields

appear in this dialog, but only the field for the external data column defined in the column definition appears.

9. You can directly enter a value into the external data column field directly and then click the first icon to the right of the text box to check if the external data table has a record with that value, or you can click the second button to display a list of records from the external data source. Note that this list uses a horizontal scroll bar to let you see all the columns in the external data. To select a record, click anywhere within it and then click the OK button. This returns you to the New Item dialog which you can click 'SAVE' if you have entered all the data for this item.

10. When SharePoint displays your list again, you will see not only the data you just entered, but also the data for all the associated fields.

In the next section, we examine the pros and cons of using a custom list with external data and how to build a custom Edit Item form for this list.

Features of a Custom List with External Data

Just like we looked at the limitations of a 100% External List, lets look at the limitations of a custom list that uses as one of its columns an external data element. Note that these observations apply no matter if you only have the one external data element or if you include additional fields from the external content type to include in your new list. First, lets get out of the way some things that are missing in a custom list when it includes external data.

1. Folders are still not allowed. Im sticking with the theory that when beginning with an external flat file (table) that there is no easy way to map the hierarchy concept of folders. 2. No version history. Since SharePoint has no way to track changes to data in the backend database, version history does not make sense, no? 3. No workflows. I suppose this limitation also relates to the inability to track changes to data in the external data source. 4. As with an External List, you cannot connect this custom list to Outlook. Now lets look at some of the things you can do with a custom list that you cannot do with the External List version of the same external content type. 1. You can open the custom list in Datasheet mode. True, you cannot change any of the external data fields by just typing in new values, but you can update any of the custom fields created through SharePoint. 2. You can add more custom columns to the list and if you want, you can even edit the column that connects your custom list to the external content type to add or remove additional columns from the external data source. 3. You can export the custom list to Excel which will include not only the custom columns, but all of the selected columns from the External Content Type. In fact, you could link your External Content Type to a minimal custom list with just the Title column to transfer all of the data to Excel. You can also copy the custom list as a table in Access and it too will include the external data. However, if you link the SharePoint list to the Access table you will not be able to edit the external data fields, but you can edit the other custom list field columns. 4. The custom list also lets you define an RSS feed for the list. However the feed only contains the custom fields and the column used to link to the external content type. 5. You can attach a file to each custom list item. This is true probably because the custom list has a physical presence in SharePoint while the External List which did not support attachments did not have a physical presence in which to store that link. 6. Item Permissions are allowed again due to a physical list presence from the custom columns of the custom list. 7. Finally, you can modify the list item edit form by using the InfoPath button on the List ribbon. Interestingly, when InfoPath opens, it tells you that the connecting field from the external content type is not supported and will not be available. If you click OK, the resulting form includes all of the custom fields you added to the list and the additional columns included from the external content type even though you will not be able to edit the external content type fields. If you decide you no longer want to use the custom InfoPath form, you must go through List SettingsForm Settings (in the General Settings group) and select the radio button: Use the default SharePoint form. If you do not click the Delete the InfoPath Form from the server, you will start from the existing form and will need to update all of the changed fields.

Steps to Edit the Lists Edit Form

Using External Data with Outlook 2010

To see what happens when you connect your external data to Outlook, lets create a new external content type. Why begin with a new external content type rather than edit an existing one? The best reason is that you or someone else in your organization might be using the current external content type and changing it could break another process. Another reason is that for many external content types, you may have created several operations. When making changes, each operation has to be reviewed and changed individually whereas creating a new external content type can generate all of the operations with a single pass through the parameters as we will see below. In order to integrate the External Content Type with Outlook, you also need to associate your external data with an Office item type. Outlook supports four primary item types into which you can map your external data including: Appointment, Contact, Task, and Post. After selecting an item type, you need to map each of your external fields into one of the fields supported by that item type. For instance, if you have a table of names along with contact information, you may want to map the external data to a Contact item type. Lets assume you have such a table in one of your SQL Server databases and see what steps you need to follow to display and manage the data from Outlook. 1. Open SharePoint Designer. 2. Open the site where you want to store the external list of the data. Since you probably have been in SharePoint Designer to perform the above tasks, you should see your site in the list of Recent Sites. Simply click the name of recent site you want to work with as shown below.

3. Select External Content Type from the left navigation menu.

4. If you have any existing external content types, you will see their names in the main content panel, but assume you want to create a new external content type, not just modify an existing one. 5. Select External Content Type from the New group of the External Content Type ribbon.

6. In the External Content Type Information group, click New External content type to the right of Name and enter a name for you content type. Although SharePoint Designer automatically copies this value to the Display Name field, you can enter a different display name if you want.

7. Next, select an Office Item Type (such as Contact).

8. Since we want to use our external data with other office products like Outlook, make sure that the value for Office Sync for external list is set to Enabled. 9. Next, click the link to the right of External System to define the connection to the external data. 10. If you have defined previous connections, you may be able to reuse the connection. The connection applies to the database, not to a specific table in the database, so reusing a connection could save system resources if you need to use several tables from the same external data source. If you do not have a connection to use, you can create a new one by first identifying the data source type (such as SQL Server other types include .NET and WCF or web services). If you select SQL Server, you must then identify the Database Server, the Database Name, a user-friendly name for the connection, and how you want to validate the user against the data source. Lets assume you want to reuse a previous connection. 11. Drill down through the connection by first clicking on the plus sign before the connection name and then on the plus sign before the Tables group to select a specific table you want to use as

the data source. (You could also have selected a view or stored procedure.) Remember if you want to modify the data, you may not be able to use a view or a stored procedure as your data source. Views can be defined as updatable, but these are limited to single table views anyway.

12. To select a table, open the tables folder and right-click on the table you want to use. 13. Next, choose the operation you want to be able to perform against the data source. If you only want users to view data, choose the New Read List and the New Read Item operations. (Both are required to get data from the external list and display it. However, if you want to edit, delete and add records, the easiest thing to do is to select Create All Operations because you

can define the parameters for all operations at one time and SharePoint Designer applies them appropriately to each of the operations.

14. If you selected Create All Operations, the first page of the dialog shown next simply tells you that all operations will be created. There is nothing you need do on this page.

15. Clicking Next, you get to define the parameters of the operations. These are the fields and all field properties. 16. Deselect any fields from the table that you do not want to use. The following image shows and example where the email address and Web URL fields have not been selected.

17. Next, identify the columns used in the external item picker. This can be one or more columns that uniquely identify each record in the data source, but it does not have to be the primary key, especially if the primary key is a numeric ID field. Select each field you want to use and select the checkbox: Show in Picker.

18. Next identify any fields that have the Required and ReadOnly checkbox selected. Deselect the Required checkbox but leave the ReadOnly checkbox selected. If you do not do this, you will not be able to update the data when you display it.

19. Next, use the Office Property dropdown to map each of the external data fields to one of the Outlook item fields.

20. You might also want to change the Display Name to something that is more user-friendly.

21. When done, you can click the Next button to go to the last page of the dialog, the Filter Parameters. 22. You use filter parameters when reading large tables to keep the number of records returned to under 2000. Business Data Connectivity enforces this limit unless you raise it in Central Administrator. However, large values will degrade performance. Lets see how to create a filter for this content type based on the Work Location ID value. Begin by clicking the button Add Filter Parameter.

23. Next in the Properties dialog on the right side, you can define the filter. By default, SharePoint Designer assumes that you want to base the filter on the first field in the table. However, you can change the Data Source Element by opening its dropdown and selecting a different field. The option .NET Type automatically populates based on the selected field. To begin the filter definition, click the link to the right of the Filter property to open the following dialog:

24. To compare the Work Location ID be greater than a specific value, select Filter Type of Comparison, Operator of Greater than or Equals, and Filter Field as WorkLocationID.

25. Notice this dialog, does not have a place to define the comparison value for the filter. Click OK to close this dialog and place the comparison value in the Default Value field.

26. You can repeat this process to define additional filter criteria if necessary. You can also combine the individual filter conditions with AND or OR connectors. 27. Click Finish to complete the definition of the operations. 28. Right click the pages tab and select Save and right-click the tab a second time to Close the external data content type definition.

29. The External Data Type is not ready to use yet because you have not yet defined permissions. 30. Open Central Administrator (or ask your SharePoint Administrator) and select Manage service application in the Application Management group.

31. Click Business Data Connectivity Service. On the resulting page you should see your External Content Type.

32. Use the dropdown list associated with the type name and select Set Permissions. 33. In the dialog box, add the SharePoint users or groups you want to give rights to use this external content type.

34. For each user or group you add, you must select from the four permissions shown. The Edit and Execute permissions are necessary to simply use the external content type in an external list, but if you want to connect that external list to Outlook, you must select the permission: Selectable in Clients. You can also choose whether this user can set permissions (by using the Manage Permissions option of individual items in the list.)

35. Now open the site and create an external list from this external content type as described in a previous section on creating and external list. Open the list after creating it. 36. With the list open, click Connect to Outlook in the Connect & Export group of the List ribbon.

37. Some dialog boxes may appear as the Business Connectivity Service add-in starts, but eventually the data connects to Outlook and Outlook should open automatically if it is not already open. However, I have seen a case (my machine) where Outlook does not automatically open in which case the process may still work but you have to manually open Outlook. 38. If you open the Folder List or Contacts icons at the bottom of the left navigation of Outlook, you should see a SharePoint External List group in the Folder List Panel or you may just see the external list at the bottom of the Contacts panel (assuming you used the Contact Item Type when defining the External Content Type).

39. You can now click on the name of your external content type to open it and then update or delete contacts from within Outlook even though you store the data in SQL Server and pass it through SharePoint using an External Content Type.

Using External Data in Libraries

This time I will look at adding an External Content Type field to a library. One way you could use external data with a Word document might be to supply address information from an external SQL Server data table when the user selects a person. Some of the steps to accomplish this task you may have already done through previous topics, but I will include the steps here again for completeness. 1. Open SharePoint Designer. 2. Select the site you want to work in from the Recent Sites list or click the Open Site button to enter the address of your site.

3. Select External Content Types from the left navigation

4. If there is already a content type you can use, you can skip ahead to create the document library. Otherwise, click External Content Type in the New group of the External Content Types ribbon.

5. Supply a Name for the content type. You can use the same name as the display name or provide a more user friendly display name. 6. When working with external data in Microsoft Word, you can use the Generic List Office Item Type since we will not need to map fields to Outlook items.

7. Use the link for External System to define the connection to the external data and define the operations needed. If a connection already exists to the database, you can reuse it to save resources or you can define a new connection. A SQL Connection requires the name of the server, the database, and the user authentication method.

8. Next define the operations you need from: Create, Read Item, Update, Delete and Read List. If you only need to access data, you may be fine with just the Read Item and Read List operation.

9. Be sure to define which fields to display in the picker as this will be how you will select which record to use.

10. Save and Close the definition of the External Content Type.

11. Go to Central Administration.

12. Open the Business Data Connectivity Service configuration page by selecting Manage Service Application from the Application Management group and clicking Business Data Connectivity Service.

13. Add the users and/or groups that will need to use this content type by opening the Business Data Connectivity Services dropdown and selecting Set Permissions.

14. Exit Central Administrator.

15. Close Share Designer

Next, Create the Document Library

1. Create a standard document library with a name of your choice. 2. Go to Library Settings which can be found in the Settings group of the Library ribbon.

3. Add a new column of type External Data.

4. Clicking this option opens the New Column dialog. For the column name, you can use any name unique to your list/library. The important part is to select the column type: External Data. When you select this type, the properties in the Additional Column Settings include the field External Content Type that lets you select, by clicking the second button to the right of the field, from the available External Content Types you have defined so far.

5.

Select one of the External Content Types that you have previously defined using the Office Item Type: Contacts.

6. After selecting an external content type, the settings page updates to display beneath the selected content type a set of properties related to the selected content type. First you must select a field from the content type to associate with the external data column you are adding. You can select the field from a dropdown list of the fields in the external content type. SharePoint displays this field in this column when you select a record from the external content type. Below this property is a checkbox where you can add all fields from the External Content Type to the list. Alternately, you can use the checkboxes to the left of each field name to custom select which fields you want to include in the custom list. Why do this? When you select a record from the external data for this column, SharePoint populates the other fields chosen to appear in the list with data values from the same record.

7. Clicking OK at the bottom of the column properties page saves the definition of the external data column. 8. Return to the list by clicking the list name in the breadcrumbs at the top of the Library Settings page. 9. You see that the default view includes not only the custom columns defined for the list (if any), but also all the external columns selected from the external content type.

Upload Documents into the Library

1. Upload documents into the library using the Upload Document option in the New group of the librarys Document ribbon. Note that you can upload either single or multiple documents. Lets assume you upload a single document.

2. Enter the document name (and path) in the Upload Document dialog or use the Browse button to locate the document.

3. After selecting your document and clicking OK, the item properties dialog appears. You may have other fields defined for this library that you can fill in, but the important one for this discussion is the external content type field.

4. Use the Select External Item button (to the far right of the field) to display the picker dialog. Select an item from the picker and click OK.

5. Click Save in the properties dialog.

6. Notice the library now shows your uploaded document along with populated values for all of the external content type fields.

Using External Data in your Word Document The final section of this topic looks at
including external data in your Word documents created from a modified default template in a SharePoint library. 1. Open the library used in the last section and go to Library Settings in the Settings group of the Library ribbon.

2. In the General Settings section, select Advanced Settings.

3. On the Advanced Settings page, select Edit Template in the Document Template area. This action opens a blank Microsoft Word template.

4. In the template you can add any text that you want to appear on every instance of a new document in this library. By creating a form on this template, you can create a Word based form library. 5. To add external data to the template, position your cursor where you want the first field from your external data to appear. This field should be the field that you defined as a column in the library. When you use this template to create a new document instance, this field allows you to select from the picker list for the external data. With the cursor positioned, open Words Insert ribbon and expand the dropdown menu for Quick Parts. Choose the Document Property option and select the external field that you used to define the external data column.

6. Next add any of the additional external fields to the template.

7. Save and Close the template.

8. Return to the list view of the library and select New Document from the New group of the Documents ribbon.

9. When the template opens as a new document, you can click the first external content field to display the two option buttons to the right of the field. Click the Select External Item(s) button to display the pick list. It may take a few seconds to open.

10. Select an item from the pick list and click OK. Notice that the other external data fields populate with the corresponding values of the fields in the external content type.

11. Notice how Word populates the document properties displayed at the top of the document.

12. Save the Word document and close Word. Returning to the library, you should now see the newly saved document along with the external data populating the newly added row.