Layer2 Data Provider for SharePoint (CSOM): Specifications for Business Data List Connector
Business Data List Connector (BDLC) can be used to connect
almost any external data source to native SharePoint lists, even external
SharePoint data - on-premise, internally or externally hosted, or in the
Microsoft SharePoint Online / Office 365 cloud. This FAQ gives the full
specifications of the CSOM-based Layer2 Data Provider for
The Layer2 Data Provider for SharePoint (CSOM) connects your
current SharePoint list to lists and libraries of external
- Microsoft SharePoint Server 2010 including free Foundation,
- Microsoft SharePoint Server 2013 including free Foundation,
- Microsoft SharePoint 2016 and
- Microsoft SharePoint Online / Office 365
to retrieve data from SharePoint lists (e.g. contacts, tasks, events or
custom), calendars and document libraries (metadata only, no files) and
optionally write-back changes.
Fig.: Sample connection string for the Layer2 Data Provider for SharePoint (CSOM) to connect to a
Microsoft Office 365 list view.
The following parameters can be used in the connection string:
- Url: This is the URL of the SharePoint site collection
where the list or document library is located or the full URL to the list or
view on a SharePoint site. When full URL is used then List and
View information is automatically parsed from connection
string. In all other cases the List parameter must be
given.The View parameter optionally can be
provided separately in the connection string. The URL information is mandatory.
It is recommended to use view, e.g. the AllItems view, to reduce the amount of
fields transferred and created in BDLC. Using a view is relevant for
- Authentication: This setting specifies how the BDLC
authenticates against the SharePoint server. By default it is Anonymous. It can
also be one of the following:
- Windows: This authentication method is using a Windows
Active Directory account to authenticate against a SharePoint server. If this
method is used, it is necessary to define both parameter, User
and Password, whereas the user is specified in the
format DOMAIN\username. If the provider is used in the context of an automatic
background synchronization, the user that will be used to perform Windows
integrated authentication is the service account of the Windows
SharePoint Services Timer. Please note that the accounts must have the required
permissions on the Sharepoint server given with URL, means read for read-only
operations, create and delete (normally contribute) for using
Sample: ...; Authentication=Windows; User Id=domain\user;
- Anonymous: If the SharePoint server given by URL is
configured to support anonymous authentication, this method can be used to
connect to this SharePoint server without any authentication. Default.
- Office365: This is the default authentication method to
access Microsoft Office365 / SharePoint Online. If this is configured as the
authentication method, User and Password must
be provided. Please use the same values as in browser-based dialog, e.g. for
- IECookie: Not supported for BDLC.
- ADFS: This is the authentication method for accessing
Office 365 using ADFS. For this authentication type OnlineUser,
User and Password must be provided.
- ADFSIntegratedWindows: This is the authentication method
for accessing Office 365 using ADFS with current user credentials. For this
authentication type OnlineUser parameter is
Please note: Authentication setting is optional. If not
provided, IntegratedWindows is used by default.
- User: This part of the connection string specifies the
username for the account which is used to authenticate against the external
SharePoint. This information must be provided if one of the
authentication-methods Windows or Office365 is used.
- Password: This parameter defines the password for the
account which is used to authenticate. It needs to be specified if Windows or
Office365 is used as the authentication method.
- OnlineUser: This Parameter is used for ADFS authentication
types. Please use the mapped user id used as online id for Office 365
authentication. This parameter is mandatory for ADFS authentications.
- List: The list parameter specifies the SharePoint list,
calendar or document library to be used as the data source. This could be the
internal name, the display name or the ID/GUID of the list or document library.
This setting parameter is mandatory if full Url to the list or view is not used
in connection string.
- View: The view parameter is optional and can be used to
define a specific data subset of a list or document library to be synchronized.
The view can be created and configured on the SharePoint portal as usual. The
view parameter will accept the name of the view as well as the URL of the view
aspx site or just the name of the view aspx site. It is recommended to use view,
e.g. the AllItems view, to reduce the amount of fields transferred and created
in BDLC. Using a view is relevant for performance.
- SecureTokenService: This setting is optional and should not
be specified in most cases. It is of relevance only in case Office365
authentication is being used. It defines the URL of the secure token service
which is used for authentication. In most cases this should be
https://login.microsoftonline.com/extSTS.srf which is the default.
- SignInUrl: This setting is optional and should not be
specified in most cases. It is of relevance only in case Office365
authentication is being used. It is the site collection relative URL which is
used to sign in after the authentication token has been retrieved from the
secure token service. If omitted, it will be by default:
- Realm: This setting is of relevance only in case the
Office365 authentication is being used. It needs to be specified, if the URL
which is used to access the SharePoint Online instance is not the default URL.
SharePoint Online default URL´s have the format
https://myCompany.sharepoint.com. This URL is used in two different contexts:
First it is used to identify the SharePoint instance to the secure token server
(STS). In this context, the URL is called a Realm. Second, it is used to locate
and access the SharePoint instance, for example in a browser, as a normal URL .
If a different URL than the SharePoint Online default URL has been established
to access the SharePoint Online instance, the URL will be for example
https://mySharepoint.myCompany.com, but the realm will still be
https://myCompany.sharepoint.com. In this case the BDLC will no longer be able
to infer the realm from the URL. In this case the realm needs to be defined
explicitly through this setting.
- Office365UserRealm: This parameter is used to query online
user id information like it is a valid adfs user, adfs server url. Parameter is
optional. Default value is
- WsTrustVersion: This parameter is used to set WS-Trust
version which defines message format of the Secure Token Server authentication
token. Possible values are :"WSTrustFeb2005" or "WSTrust13". Default value is
"WSTrustFeb2005". Parameter is optional and specific to the ADFS
- ADFSEndpointUrl: This parameter is used to define the local
adfs server endpoint url for issuing adfs token. By default it is queried from
Office365UserRealm by online user id. It is something like
Parameter is optional and specific to the ADFS authentication.
- BatchReadItems: This setting is optional and specifies how
many SharePoint items will be committed together to the server in one update /
insert / delete request. By default SharePoint allows committing up to 5000
items together during one request. The default value for this parameter is 5000.
This setting is relevant to performance and can be adapted to
FilterPath: This setting is the optional and specifies, how
items in a list or library with folders should be read. Value “Recursive” tells
that all items will read including subfolders, and folders are not listed in
results. Value “RecursiveAll” gets all items plus folders. Default value is
Select Statement / Query
- The provider does not support any query / select statement. Querying can be
done by setting up an appropriate SharePoint list view externally and use it