Knowledge Base

Browse our knowledge base articles to quickly solve your issue.

SharePoint Integration

SharePoint is a Microsoft business collaboration platform, which allows you to create sites, which can be used for sharing content and documents within an organisation.

SharePoint sites may be arranged hierarchically, the top parent site being
known as a 'Site Collection'. There may be several Site Collections.

sharepoint 1

Out of the box, SharePoint does not allow its sites to open within an external iFrame without some configuration. To allow a SharePoint site to be compatible for use within an iFrame, the following directive needs to be added to the HTML code for the site's pages:

<WebPartPage:AllowFraming runat="server" />

Fortunately, child sites can be configured to inherit settings from their parent site. If the changes are made to a Site Collection, it becomes much easier to make any child site of said Site Collection accessible to Workbooks. This in turn, means that configuration will be easier if all the sites that are required to be accessible from Workbooks descend from a single, or limited, number of Site Collections.

The remainder of this page describes step-by-step how to apply this modification to a site collection, how to configure its child sites to inherit the required settings, how to then set-up the necessary custom fields within Workbooks to interact with SharePoint, and any limitations which may occur.

1. Configure the Site Collection

For the site collection(s) you wish to become available to Workbooks, the 'SharePoint Server Publishing Infrastructure' must be enabled. To do this, navigate to the page 'Site Collection Features' using the following path:

Settings > Site Settings > Site Collection Administration > Site Collection Features

Once within the 'Site Collection Features' page, click the 'Activate' button next to 'SharePoint Sever Publishing Infrastructure', as highlighted in red below. (Click to enlarge.)

sharepoint 2

 Next, 'SharePoint Sever Publishing' needs to be enabled. To do this, navigate to the page 'Manage Site Features' using the following path:

Settings > Site Settings > Site Actions > Manage Site Features

Once within the 'Manage Site Features' page, click the 'Activate' button next to 'SharePoint Sever Publishing'.

Now, the default master file for the site collection needs to be located. To do this, navigate to the 'Master Page Gallery' using the following path:

Settings > Site Settings > Web Designer Galleries > Master Pages and Page Layouts

Once within the Master Page Gallery, page through until you find the file 'seattle.master', as highlighted below.

sharepoint 3

Select the 'seattle.master' file (using right click) and download a copy of the file. 

Rename the downloaded file to be 'seattle-allow-framing.master' and open it in your favourite text editor (eg, Notepad or TextEdit).

There will be a set of lines beginning <%@Register ... (highlighted below in green) near the top of the file.  Add the following line of code after these lines, as highlighted in the screenshot below (click to enlarge):

<WebPartPages:AllowFraming runat="server" />

sharepoint 4

Upload the modified master file to the appropriate site collection via its 'files' tab shown in the screenshots below (once within the site collection). 

sharepoint 5

sharepoint 6

Within the master page gallery right-click on the new file and select 'edit properties'. Set the content type to 'ASP NET Master Page' and the UI version to 15, and then save.

sharepoint 7

Again on the Master Page Gallery, right-click on the new file. Select to 'Publish a Major Version'.

sharepoint 8

Next, navigate to the master page settings via the following path:

Settings > Site Settings > Look and Feel > Master Page

Within the Site Master Page Settings, set both the site master page and the system master page to be 'seattle-allow-framing' and click 'OK'.

sharepoint 9


2. Set a Child Site to inherit the configuration of its Parent

The instructions below describe how to set up the configuration of a new child site. To configure a pre-existing child site the steps are the same, but step 2 can be discounted.

NOTE: Part 2 will not work without Part 1 being complete.

Open a Site Collection with the modification described in section 1 above.

Once within the Site Collection, create a new child site via the following path:

Settings > Site Contents > New Subsite

Once the sub-site has been created, its settings must be defaulted to that of the parent site. To do this, navigate to the page 'Manage Site Features' using the following path (from within the chosen child site):

Settings > Site Settings > Site Actions > Manage Site Features

Once within the 'Manage Site Features' page, click the 'Activate' button next to 'SharePoint Server Publishing'.

This has defaulted the settings of the child site to duplicate that of the parent site, and can be checked by going to the 'Master Page' under 'Site Settings', where the default should now be to inherit the master page from its parent.

These sites are now compatible with Workbooks iFrames.

3. Application of SharePoint within Workbooks

Now that the SharePoint sites have been configured, SharePoint can be integrated with Workbooks.

This section describes how to set up this integration through the use of custom fields as described in the following two examples.

Linking Workbooks to an organisation-specific folder based on a record's name

The following example explains step-by-step how to access a SharePoint's Site's folder within a Workbooks tab, based on a Workbooks record's name.

SharePoint has the ability to add documents and folders to a site. This is illustrated in the screenshot below (highlighted in red). The site shown in the screenshot is the customer's page of a given company, with the information about their customers saved within folders in the highlighted documents section. Each folder is named after a single customer.

sharepoint 10

To create a Document within SharePoint, either within the above-highlighted section, or the documents side-tab simply click on 'New Document'.

The steps below explain how to link the document folders within the highlighted section to the appropriate organisation within Workbooks (please note that this can be done with any object type within Workbooks).

  1. Open both Workbooks and the appropriate SharePoint site so that the documents section is visible (which should look similar to the screenshot above).
  2. Within Workbooks, navigate to the custom fields page for organisations using the following path:
    • Start > Configuration > Customisation > Record Types > Organisations > Custom Fields
  3. Within the custom fields page, click to create a 'New Custom Field'.
  4. Change the 'Data Type' to 'iFrame'.
  5. To populate the 'URL' field:
    • Within SharePoint, right click on the 'Documents' header (highlighted in green above) and select 'copy link'. 
    • Within Workbooks, right click within the 'URL' field and select 'paste'. 
    • The end of the URL should contain /Shared%20Documents (or something similar). After this, add /@name@. This is a link to the 'name' field of the Organisation record. 
  6. Populate the remainder of the fields as follows, these can all be seen in the screenshot below.
    • Field Label: 'SharePoint Documentation' (or similar).
    • Data Type: 'iFrame'.
    • URL: (or similar).
    • Show on Tab: On.
    • All other fields can be left as they are.
    • It's important that the name of the record corresponds exactly to the document name within SharePoint, or the integration will not work.

      sharepoint 11

  7. Save and close the new custom Field.
  8. Click on the 'Main' tab of the 'Customise Organisation' page and click 'Save and Close'.
  9. Create/Open an organisation with the same name as a SharePoint document.
  10. There should now be a tab labelled 'SharePoint Documentation' that, on opening the tab, should point towards the appropriate SharePoint site and document folder. This is shown below. 

    sharepoint 12

This same process can be used to point to a site instead of a document by changing the URL that the iFrame points to.

Linking a Workbooks record to a specific SharePoint site based on the contents of a custom field

The following example creates a Workbooks tab that displays a SharePoint Site based on the contents of a custom field on the record's main form. This example concerns cases, however other records could be used.

  1. Open the 'Site Contents' page of a SharePoint Collection site (so that you can see the child sites), and log in to your Workbooks account.
  2. Within Workbooks, navigate to the Custom Fields page for Cases using the following path:
    • Start > Configuration > Customisation > Record Types > Organisations > Custom Fields
  3. Once within the custom fields page, click to create a 'New Custom Field'.
  4. Populate the 'Field Label' field with an appropriate name (eg, Project Site Name). The 'Data type' should be set to 'text'. All other fields can be left as default.
  5. Save the custom field.
  6. The 'Field Name' field now contains the ID of the field. This is highlighted in red in the screenshot below:

    sharepoint 13

  7. Do not close the custom field created but do create a new one.
  8. Change the data type to 'iFrame'. 
  9. To populate the URL field:
    • Within the SharePoint Collection Site, right click on a child site (sub-site) and copy the link.
    • Paste this link into the URL field of the new custom field. In this example, the URL is:
    • The last part of the URL identifies the particular child site the URL points to. In this case, the child site is 'Acme Widgets' with a parent site of 'Customers'. 
    • Delete the last section of the URL. In this case: Acme%20Widgets/
    • The URL now becomes: 
    • The field ID from the 1st custom field created (highlighted in the screenshot above) is to be added to the end of the URL in between the two '@' symbols. The final URL is: 
  10. Populate the remaining fields as follows, these can be seen in Figure 16 below:
    • Field label: 'Project site' (or similar).
    • Data Type: 'iFrame'.
    • URL:  
    • Show on tab: On
    • All other fields can be left as they are. 

      sharepoint 14

  11. Save and close both custom fields.
  12. Click on the 'Main' tab of the 'Customise Case' page and click 'Save and Close'.
  13. On opening a case, there will be a new field named 'Project Site Name'. When this is populated with the name of one of the appropriate child sites, the tab named 'Project Site' will point towards said site. 

This method will only work for child sites within the same Site Collection. 

The site name given in the 'Project Site Name' field MUST match a site name exactly or the 'Project Site' tab will not be able to point towards a site.

4. Limitations

There are some limitations, which are currently unavoidable when integrating Workbooks and SharePoint.

You are unable to left-click on links on the SharePoint site which access content that has not been enabled for use within an iFrame. This includes opening documents. To open such links from the iFrame you need to right-click, and then open them within a new tab or a new window.

Related content

An overview of what you can do within the Email & Integration section within Configuration.