3. Background
• BS Computer Science, Math, Business
• 5 years at IBM in Sales and Distribution
• 10 years in Seattle at various startups
– Large volume transaction processing (Credit, Debit, Loyalty)
• Microsoft Certified Trainer (MCT) since 2007
– CISSP, CCNP, JAVA, MCSD, SharePoint 4x
• CEO ACS, leading SharePoint courseware provider to
Microsoft Certified Training centers
– Top selling titles in Development, BI and Search
• SharePoint Sr. Architect
– eBay
– General Atomics
4. What led to this session?
• MOC Course 20489
– Advanced Development with SP2013
• Module 9 – “Working with Business
Connectivity Services”
– No documentation (“that works”)
– No one has ever done this (outside PG)
• Also led to posts on this subject on
MSDNMSPress and my blog
5. Business Connectivity Services
• Service application that allows
– External lists
– BDC Columns
– Indexing search content
• Custom BCS Connectors allow SharePoint to
index ANYTHING
– Yes, anything!
6. ODataREST
• A simple approach at exposing APIs using
common standard such as HTTP and REST
– http://developer.cbssports.com/documentation
• End points define the entities and methods
you want to call
– /stats
– /add_drop
• Parameters typically passed in the query string
– POST data will be in body
7. Subscriptions
• Subscriptions allow SharePoint to be notified
when external data changes
– Adding
– Modifying
– Deleting
• Event receivers have been around since 2003
– 2003 – only one - Recycle Bin
– 2007 - Event Receivers
– 2010 – More receivers added (no support for external
lists)
8. Subscription Methods
• Two new BDC stereotyped methods
– EventSubscriber
– EventUnsubscriber
• Methods can be implemented in various ways:
– Database (Scot Hillier was 1st)
– OData (CJG was 1st )
• These are in addition to the CRUD methods
– CRUD methods easily created using SP Designer
for database or Visual Studio with REST wizard
9. BDC Model Method
Properties
• Subscription
– IsDeliveryAddress – the delivery address to send
to the external system
– IsEventType – the type of event
• Unsubscribe
– SubscriptionIdName – The external systems
subscription id
10. BDC Model Method
Attributes
• ODataEntityUrl
– Suffix of rest end point
• ODataHttpMethod
– GET, POST
• ODataPayloadKind
– http://msdn.microsoft.com/en-
us/library/microsoft.data.odata.odatapayloadkind%28v=vs.113%29.aspx
• ODataFormat
– Content-type header (application/json;odata=verbose)
– Based on the external system end point json support
– OData Version 2 vs 3 (visual Studio wizard)
• ODataServiceOperation
– ???
• NotificationParserType
– Defines the class that will handle the parsing of the external message
11. Implementing
External System Support
• OData generated services will not have the
methods necessary to support notifications
– You must add them (Subscribe and Unsubscribe)
• This is tricky
– OData Service uses its own HTTP request handling
mechanism
– Request body is not available in your method
– Expect to pass method parameters in the query
string, not via the body
12. The Subscription Process
• Subscription list (External Subscription Store)
must be created first
– Created via External Events feature
(BCSEvents, ExternalSubscription)
– Hidden list in _private/ExtSubs
• SharePoint calls subscribe method
– Method returns SubscriptionId
• Subscription list item is created with
subscription information
13. Creating Subscriptions
• You can do this in three main ways
– Explicitly call the Subscribe method
(Server, Client, JSOM)
– Create an alert
• Very easy to do this for testing
• Ensure you setup the outgoing email settings
– Create an event receiver
• Some things get cached in the event receiver
registration
• Requires you to remove and re-add
14. Watch Out!
• You web method code may execute
successfully, but the http response may fail!
– In this case, you have to handle the exception and
remove the subscription in your code
• OData DataService implemented as custom
IRequestHandler
– Override HandleException method
• Also prevents getting the httprequest body
15. Supported Event Receivers
• Subscriptions can be one of three types
– ItemAdded (1)
– ItemUpdated (2)
– ItemDeleted (3)
• Cancel events are not supported
– ItemAdding, ItemUpdating, ItemDeleting
– No application domain that would wrap the two
systems (EAI concepts)
16. Message Formats
• NotificationParserType
– IdentityParser
• /a:feed/a:entry/a:content/m:properties/b:BcsItemIdentity
• Very simply event has occurred…no changed data
– ODataEntryContentNotificationParser
• /a:entry/a:link/m:inline/a:entry
• Includes changed data
– Custom
• Inherit from abstract class NotificationParser
• Implement the Initialize method
• Why? Change the format to JSON rather than ATOM
• Except for the XPath, everything is ignored!
17. Getting the Message
• Event receivers will expose the message sent
from the external system
– Allows for custom processing in your event
receiver
• Property called NotificationMessage
• NOTE: Attempts to get item properties will fail
if the message is improperly formatted
– No parsing on message receive
18. Demo
• Create a subscription
• Change data
• Debug the event
• Analyze the message
19. Summary
• It does work!
• External system must support sending
notifications back to SharePoint
• Message format is very specific
• Ensure subscriptions get created in list
• MSDN Blog
• MSDN Code
