Data Access in SharePoint-hosted Apps

Introduction

SharePoint-hosted apps can access data from other SharePoint websites and even from external data sources using client side APIs (REST or JSOM). Depending on where the data sits specific methods from these APIs should be used. These methods, e.g.: cross-domain library or web-proxy, circumvent cross-domain browser policies or SharePoint API restrictions.

Find here a summary of data access methods to be applied in several scenarios. Note the examples use the REST API when possible, but the same could be achieved with JSOM. There is a download package with all examples at the end of this post.

Quick index:

Accessing Data within App Web
Accessing Data from Host Web
Accessing Data from Same Site Collection
Accessing Data from Other Site Collections
Accessing Data from External Data Sources
Other Data Access Options
Conclusion
Downloads
References

Accessing Data within App Web

This is the simplest scenario, because the app is in its own domain, just the user has to have permissions to read or write in the host web; this right will be inherited by the app web (a part if inheritance has been broken).

SharePoint-hosted Apps

Red arrow: data access from the app to its data in the app web.

Accessing Data from Host Web

In order for SharePoint-hosted apps to access data in their host webs, app permissions have to be set and the cross-domain library has to be used. The cross-domain library is needed because the app is in its own app domain and not in the SharePoint domain. Also, as always, the user has to have the proper permissions on the respective sites.

SharePoint-hosted Apps

Red arrow: data access from the app to its host web.

In regard of app permissions, the required permission request has to be set in the AppManifest.xml during development. In this case, the permission of writing to the list Test or to the whole host web content:

SharePoint-hosted Apps

Editing the AppManifest.xml in Visual Studio: setting the permission request to write in host web.

Observation about Direct Ajax Calls

It is also possible to perform operations to the host web by using Ajax (e.g., $.ajax) without using the cross-domain library, i.e., SP.RequestExecutor. In this case, just make the Ajax call as usual passing a URL as in the examples above (i.e., by including the SP.AppContextSite and respective @target). You can find an example implementing this here.

A note of caution: this technique is not officially documented and eventual problems or restrictions derived from its use are mostly unknown. At least these calls fail when trying to access other websites than the host web.

Accessing Data from Same Site Collection

A SharePoint-hosted app can access data from any web in the same site collection where it has been installed.

SharePoint-hosted Apps

Red arrow: data access from the app to another web in the same site collection.

It is required: the cross-domain library, the app permission has to be set at least to site collection read or write and the user has to have as well permissions to access the desired sites.

SharePoint-hosted Apps

 Editing the AppManifest.xml in Visual Studio: setting the permission request to write in the site collection.

The example code bellow is basically the same as of accessing data in the host web, just the host web URL has to be replaced by the target web URL.

Observation about Direct Ajax Calls

It is not supported Ajax (e.g., $.ajax) calls to other sites by just setting the SP.AppContextSite and respective @target – this just seems to work when accessing the host web.

Accessing Data from Other Site Collections

A SharePoint-hosed app can access data from another site collection in the same way as accessing data from a site in the same site collection.

SharePoint-hosted Apps

Red arrow: data access from the app to another web in another site collection.

In this case, the app has to use the cross-domain library as seen before, the app permissions have to be set for tenancy permissions (this is required because we want our app to access the site collections of this SharePoint tenancy) and the app has to be deployed as tenant scoped (see details about this below). As usual, the user has to have the proper permissions to access the required websites.

access-permission-another-site-collection

Editing the AppManifest.xml in Visual Studio: setting the permission request to write in the SharePoint tenancy.

The sources were omitted from here because the JavaScript code would be the same as of the previous example – just the target URL would be of a web in another site collection.

What is a Tenant Scoped App?

The scoping of an app is determined by where it is installed. There are two scope possibilities:

The web scoped app is the most common case, the app is installed into a website (any site belonging to a site collection).

The tenant scoped app is an app installed in the app catalog. Indeed, there is no metadata, project property or programming in an app which makes it tenant scoped. The app has simply to be deployed to the app catalog in order to be a tenant scoped app.

In order to deploy an app to the app catalog, first it has to be uploaded to the app catalog and then added to the app catalog itself as it would be added to any other site (through Site Contents – “add an app”).

Why a Tenant Scoped App is Required?

Because it is not possible to access other site collections from a web scoped app. The SharePoint APIs block the calls making them fail.

Considering that normally site owners can install SharePoint-hosted apps, it seems to make sense of having this security restriction to add a bit more control over apps which can access many site collections.

Installing Tenant Scoped Apps in Other Websites

It is possible to add a tenant scoped app into other sites in the same SharePoint tenancy. In this case, there will be just one app instance for all websites – the instance of the app catalog. The app will be just referred from the other websites where it has been installed.

Therefore, the URL and all data stored in the app are really the same (shared, if you’d like to think so) across all websites.

This is a big difference if compared with deploying a web scoped app where each app instance is independent from each other (each one has its own domain and app web).

To install a tenant scoped app in other websites, go to the app catalog, Site Contents, select the app instance and choose Deployment, as seen below. From there, enter the site collection URLs or managed paths or site templates where you would like to have the app batch installed.

See this MSDN post for more details.

SharePoint-hosted Apps

The deployment option to install tenant scoped apps in other websites.

About Accessing Data from Another SharePoint Tenancy

The above explanation just applies for accessing data in the same tenancy. It is unknown a way of accessing data in another SharePoint tenancy using the cross-domain library or any other library / API.

Accessing Data from External Data Sources

A SharePoint-hosed app can also access data external from SharePoint, i.e., web services from other domains than the one of SharePoint or of the app web.

SharePoint-hosted Apps

Red arrow: data access from the app to an external web service.

The app has to have the remote endpoint registered in the AppManifest.xml, as seen below, and the web proxy used to make calls to this endpoint. The web proxy is a server component provided by SharePoint which can be reached by apps using client side APIs or its own REST endpoint. The web proxy will do the required call to the remote domain and return the result to the app.

No special app permissions have to be requested in this scenario. The user permissions have to be the minimal to access the app as well.

SharePoint-hosted Apps

Editing the AppManifest.xml in Visual Studio: setting the remote endpoint (now “http://echo.jsontest.com”).

Accessing Intranet Web Services

It is possible to access intranet web services from apps, but a configuration has to be changed in the SharePoint farm to allow these calls. The following PowerShell performs this configuration change, run it from a SharePoint Management Shell:

Also, there are just specific port ranges which can be accessed; for details verify the web proxy documentation, under “Troubleshooting the solution”.

Open Points Regarding the Web Proxy

The use of the web proxy to access data with authentication has not been verified and might depend on your specific web service implementation.

The example provided can only access anonymous web services from the Internet or an intranet.

Other Data Access Options

Workflows

A SharePoint-hosted app to implement workflows to communicate with other web services. This option can solve many authentication and cross-domain issues and seems quite flexible, however the app might not perform so well as when doing calls in JavaScript because workflows can take longer to execute.

BCS

Another option could be the use of the BCS REST API to access external data in a SharePoint-hosted app.

Conclusion

Data access using JavaScript has many pros and cons which have to be considered during design and implementation of an app. The points summarized here should help in clarifying which options are available for many situations.

Please drop a comment if you find another way of accessing data from SharePoint-hosted apps or if there are improvements on this text (e.g., web proxy with authentication or anything else)!

Never miss an update by following us and subscribing to our monthly newsletter!

Downloads

References

Summary
Data Access in SharePoint-hosted Apps
Article Name
Data Access in SharePoint-hosted Apps
Description
SharePoint-hosted apps can access data from other SharePoint websites and even from external data sources using client side APIs (REST or JSOM).
Author
Publisher Name
Atos Consulting CH
Publisher Logo

5 thoughts on “Data Access in SharePoint-hosted Apps

  1. Avatar
    Sven Reply

    I want to thank you for this nice wrap up. One of the best app resources I’ve found.

  2. Avatar
    ziyad Reply

    really i would like to thank you about this resources , but i have question… are these solution work on SharePoint online like (office 365) ?

  3. Avatar
    Andres Reply

    Hi, great article. One question, what if I need to deploy a SharePoint Hosted App in O365 and access an On-Premise webservice? In this case I believe the web proxy won’t work….

  4. Avatar
    Adrian Ganea Reply

    Nice article, though, it is unclear if you can access data from a different site collection residing in a separate web app using  the cross-domain library – this doesn’t seem to work. Moreover, accessing data from a host-named site collection residing in the same web app doesn’t seem to work either.

Leave a Reply

Your email address will not be published. Required fields are marked *