Skip to content

Live docs: How To Setup Sharepoint Online For File Storage

How It Works

  • By using this setup, all files in Lime CRM will be stored on a dedicated Sharepoint site.
  • The customer is responsible for supplying, maintaining and configuring the Sharepoint site.
  • Once a file is created or updated from Lime CRM, the file will be saved or updated in Sharepoint.
  • No files will be stored in Lime CRM. Lime CRM will only hold links to files in Sharepoint.
  • When a user want to access a file through the web client, they click the "file chip" and get a link to the file in return, which opens in a new browser tab. Thus, making it possible to edit the file straight in Sharepoint.
  • When a user want to access a file through the desktop client, the file is downloaded to the desktop client and uploaded again once the edit is complete.
  • The author of file changes in Sharepoint will be "Sharepoint App" for any file operation made through Lime CRM, except when editing the files via sharing links in editing tools such as Office Online/desktop apps
  • Any user in the Azure AD can use the sharing links provided by Lime CRM, even though they aren't a Lime CRM user. A Lime CRM user is however required to create the sharing link and then share it to other persons
  • The Sharepoint site will be configured such it is accessible for any other user but Sharepoint admins. Users will only be given access to individual files by going via Lime CRM.

Warning

Since the customer is responsible for providing the Sharepoint site, they (or Microsoft) are also responsible for running the site. This concerns correct setup (according to instructions below), file backups, renewing secrets and such. If the Sharepoint site is down, no one will be able to access any files from Lime CRM. Failure to set up the Sharepoint site according to the instructions below could theoretically make files from CRM available to people outside of your organization.

Configuration Steps

Steps 1-3 are performed by the customer's Sharepoint admin. Step 4-6 is performed by Lime.

  1. Create a Sharepoint Communication site
  2. Lock down Sharepoint permissions
  3. Create Azure AD application
  4. Change settings for Lime CRM
  5. Smoke test
  6. Migrate files (optional)

Info

You can watch a video of the first three steps. This video is to be used as support to the documentation below. There might be differences in the interface in the video to how it looks in Sharepoint. The written documentation below will however always hold the right instructions on how to set things up.

Step 1: Create a Sharepoint communication site

  1. Go to the Sharepoint Admin Portal at https://portal.office.com/sharepoint
  2. Click Active Sites
  3. Click Create
  4. Choose to create a Communication site
  5. Fill in the details for site name (suggested name: Lime CRM) and owner and continue
  6. Head back to the Admin portal
  7. Click Active sites
  8. Tick the box next to your site and click Sharing in the top toolbar
  9. In the Sharing settings dialog, ensure no external sharing is allowed by making sure the "Only people in your organization" option is selected. 1
  10. Click Save.
  11. Navigate to your site. The address bar in your browser should now be something like: https://mycompany.sharepoint.com/sites/limecrm
  12. Copy /_api/site and paste it at the end of the url in the browser address bar. You should have a url similar to https://mycompany.sharepoint.com/sites/limecrm/_api/site.
  13. Press Enter and you should see information about the site as an XML.
  14. Search (Ctrl/cmd + F) the XML for d:Id m:type="Edm.Guid" and write down the site ID which should be instead of **** in this part of the XML: <d:Id m:type="Edm.Guid">****************</d:Id>

Step 2: Lock down Sharepoint permissions

Note

This step requires the site to not be bound to an Azure AD group, hence the requirement of creating a site using the Communication site template. Using a team site template will not allow completion of this configuration.

Sharing links with edit access are hard-coded in Sharepoint to the predefined Contribute permission level. Therefore we need to constrain it's assigned permissions to only allow editing of the file contents.

Warning

Not following these steps can give users enough access to files to destroy the integrity of files stored in Lime CRM. Moving or renaming files directly in Sharepoint will have the same effect as deleting the file in Lime CRM.

  1. Navigate to your Sharepoint site
  2. Click the cog icon in the top right and choose "Site Permissions"
  3. Click "Change how members can share" (Site Sharing)
  4. Select the option "Only site owners can share files, folders and the site"
  5. Turn off "Allow access requests"
  6. Click Save
  7. Copy /_layouts/15/role.aspx and paste it at the end of the url in the browser address bar.
  8. Press Enter.
  9. Click the Contribute permission level
  10. De-select all permission options by clicking the top checkbox
  11. Select "Edit items" to get permissions needed to edit (but not delete, rename etc) documents.
  12. Select "Open items" to get permissions to the features "download a copy", "download as pdf" and "open in desktop app".
  13. Select "View versions" to get permissions to see previous versions of a documents and restore an older version.
  14. Click Submit

Step 3: Create Azure AD application

  1. Go to the Azure Portal at https://portal.azure.com
  2. Click the search bar, search for "Enterprise applications" and click it.
  3. Click "New application" and then choose to "Create your own application"
  4. Fill in a name such as "Lime CRM File Access" and choose "Register an application to integrate with Azure AD (App you're developing)"
  5. In the "Supported account types" section, choose "Accounts in this organizational directory only - Single tenant".
  6. Click Register.
  7. Click the search bar, search for "App Registrations" and click it.
  8. Find your application in the list and click to open it
  9. Write down the
    • client_id ("Application (client) ID") and
    • tenant_id ("Directory (tenant) ID")
  10. Add a client secret in "Client credentials"
  11. Give it a suiting name, for instance "Lime CRM", and set an expiry date. Suggested: 24 months. It is your responsibility to provide Lime with a new secret before this one expires.
  12. Write down what is the "Value" column in the secrets list. NB! Not the value in the "Secret ID" column.
  13. Click "API permissions" in the left menu to start adding required permissions
  14. Click "Add a permission" and choose "Microsoft Graph" followed by "Application permissions"
  15. Search for Files and expand that section
  16. Select "Files.ReadWrite.All"
  17. Search for and Sites and expand that section
  18. Select "Sites.ReadWrite.All" 2
  19. Click "Add permissions" at the bottom of the page
  20. Click "Grant admin consent for <domain>" in the toolbar and proceed

🎉 You are now done with the setup of Sharepoint! 🎉

By now, you should have written down the following:

  • Site ID
  • Application (client) ID
  • Directory (tenant) ID
  • Secret
  • Expiry date for the secret

If you have a contact person at Lime, please reach out to them and they will arrange a secure way for you to send them this information.

If you do not have a contact person at Lime, please upload this information using our secure file transfer service. Write a message as follows:

Subject: Live docs settings for [your company name]

Message:

These are the settings to be used for Live docs for [your company name]

site_id: ...

client_id: ...

tenant_id: ...

client_secret: ...

Step 4: Change settings for Lime CRM (performed by Lime)

Before starting this guide, please make sure you have received Site ID, Application (client) ID, Directory (tenant) ID and Secret from the customer.

Tip

While each Lime CRM application need its own Sharepoint site ID, the application settings (client_id and client_secret) can be the same. Tenant ID is representing the Azure AD directory and will always be the same within one Azure AD domain.

Cloud setup

  • Open the CAFE page for your application
  • Go to the Configuration tab
  • Add the following to Configuration and Secret:

Configuration:

file:
  default_storage: onedrive

onedrive:
  site_id: 123abc-efgh...
  client_id: 123456-abcdefg...
  tenant_id: abcdef-1234567...

Secret:

onedrive:
  client_secret: **********...

On-prem setup

  • Create or open config.yml (or config.yaml if config.yml doesn't exist), which is found in %programdata%\Lundalogik\LIME Pro Server\{service name}\configs for the webserver, eventhandler and taskhandler.
  • Update the files with the following:
features:
  application_configuration: true
file:
  default_storage_in_app_config:
    - onedrive
  • Create or open %programdata%\Lundalogik\LIME Pro Server\application_config.yaml
  • Update the application_config.yaml file with the parts in section config and secrets:
<application-name>:
  config:
    file:
      default_storage: onedrive
    onedrive:
      client_id: 123456-abcdefg...
      tenant_id: abcdef-1234567...
      site_id: 123abc-efgh...

  secrets:
    onedrive:
      client_secret: **********...
  • Restart Windows services for changes to take effect.

Step 5: Smoke test (performed by Lime)

In the web client:

  1. Create a document card and attach a file
  2. Press save.
  3. Hover to cursor over the file chip. It should say something like https://vandelay.lime-crm.com/vandelay/api/v1/file/46110/edit/. The important thing is the /edit/ at the end of the url.
  4. Click the chip. A new tab should open where you're asked to log in using your 365 account. Most of the time Lime employees do not have such an account for the customer's domain.

Step 6: Migrate files (performed by Lime, optional)

If this concerns an existing solution which already have files stored somewhere else than Sharepoint, you should perform a file migration.

  1. Log in to Lime Admin
  2. Go to System -> File storage
  3. Make sure onedrive is the default storage
  4. Press Start migration

The speed of the migration is approx. 2 files/second, depending on file size.

Troubleshooting

I can't upload a file to the document card

If this has never worked, the reason is most likely that something in step 3 has not been properly setup. It is recommended to redo step 3 rather than figure out what has not been properly setup since that will most likely take less time.

If you, after re-setup, still experience issues and want to figure out why an upload doesn't work we need to identify the issue by looking at the logs.

  1. On-premise: Open the logs for the webserver.

    Cloud:

    1. Navigate to Kibana
    2. In the hamburger menu on the left select Discover
    3. In the top right click Open to select a saved searh
    4. Select the saved search appserver-cloud-customer-with-errors
    5. Change the "url" in the search field to your customer's prefix
    6. Find the failed request in the list
    7. Expand the failed request and click the + button next to the trace_id field
    8. Remove everything in the search field at the top

  2. There should be a python exception at the bottom of a stack trace that matches one of these:

    • ClientAuthenticationError: invalid_client AADSTS7000215: Invalid client secret provided: This exception is thrown when the client_secret is wrong.
    • Client Error: Bad Request for url: This exception is thrown when the site_id in the application configuration is wrong. Make sure the site_id is the id for the sharepoint site.
    • ClientConnectionError: Unable to get authority configuration: This exception is thrown when the tenant_id is wrong. The Directory (tenant) ID is shown in the app registration page in Azure Portal.
    • ClientAuthenticationError: unauthorized_client AADSTS700016: Application with identifier '...' was not found in the directory: This exception is thrown when the client_id in the application configuration is wrong. The Application (client) ID is shown in the app registration page in Azure Portal.
    • HTTPError: 403 Client Error: Forbidden for url: This exception means the API Permissions for the app registration hasn't been configured properly. Make sure the permissions listed above are set and that admin consent has been granted for the app registration in Azure Portal.
    • ClientAuthenticationError: invalid_client AADSTS7000222: The provided client secret keys for app '...' are expired.: This exception means the client secret has expired, ask the customer to create a new one and update the secret in Lime CRM.

I can't edit a document even though I can make changes to the document card!

Depending on the access to the document, the link to the file will differ. Even though the document card is editable in the web client, the logged in user may have view access only to the document.

  1. Log in to the web client and open the document card
  2. Hover the file link using the mouse pointer
  3. Check the last part of the link to the file
  4. The last part is either /view or /edit, depending on the access level
  5. Open the info dialog from the menu and review the object access settings
  6. Ensure the current user has write access to the document to enable editing using Sharepoint Online applications

I get a Errors: 1 ResourceNotFound when performing a migration

This is due to the migration not finding a file where it expected it to be. This is most of the time due to files not being migrated when a database has been moved. Or files may have been deleted while the reference to the file remains. Most of the time, this is fine. If the migration can't find the files, they were never there in the first place.

I get an error saying 423 Client Error: Locked for url when trying to rename a file

Sharepoint has locked the file. This is most likely due to someone having the file open. If you open the file in Office (Word) online you should be able to see if someone has the file open. It may take a while before Sharepoint unlocks the file after being locked.

FAQ

When I click the file for edit, it's being downloaded instead, why?

A Lime CRM application can have files stored in multiple storage systems at the same time. Only file links ending with /view or /edit are stored in Sharepoint and available for online viewing or editing. File links that ends with /contents are stored elsewhere and can't be viewed or edited directly.

Can the Sharepoint site used for storage be shared among multiple applications?

Using the same site for storing files with multiple Lime CRM applications result in severe data loss and unpredictable behavior.

One reason behind this design decision is storage limits within Sharepoint. The storage limits that are applied per site are one reason why a new site needs to be created per Lime CRM application.

Why does it say that "Sharepoint App" authored a file and not the CRM user?

Storing files in the Sharepoint site is done by the Azure AD application created when configuring the file storage. All access through the Lime CRM clients (web, desktop) will be made by this "user". Only when editing the files directly in Office Online apps will reveal the real user that edited the file.

The sharing links created by Lime CRM are the same as when sharing a file by using the "Share" button in Office apps and selecting "People in your organization". With Onedrive or using Sharepoint from Teams, the sharing links can be removed with a click of a button. With files stored in Sharepoint by Lime CRM the sharing links are removed when the file is replaced.

To replace a file using the web client, just click to upload the file again in the document card.

Is Azure AD Authentication required to enable Sharepoint storage in Lime CRM?

No, it's not required. When the user clicks a link to edit a document in Office Online, they are required to login using an account in the Azure directory where the Sharepoint site is located.

Enabling Azure AD Authentication in a Lime CRM Application that uses Sharepoint for file storage only brings the Microsoft login dialog up a bit earlier in the process.

Can I use different accounts for accessing the files in Sharepoint and Lime CRM?

The sharing links created are targeted to "People in the organization" which makes it possible to share the editing links provided by Lime CRM to other users, not necessarily having access to Lime CRM.

Note

Sharing a document link to someone outside Lime CRM only gives them access to the specific file. Every upload to a document card creates a new file, which means there will be a new sharing link. Always go to the document in Lime CRM to be sure to get the current sharing link.

Is it possible to share files for viewing with external users such as customers?

The suggested setup is that files can only be shared within the organization. If you however wish to setup your Sharepoint site to support sharing outside your organization, this is possible. See footnote 1

Can I add the Sharepoint site to Microsoft Teams?

No. The Sharepoint site is only used to provide editing access to files stored in Lime CRM and can for data integrity reason not be accessed directly from Sharepoint or Teams.

How are object access rules enforced when using Sharepoint for file storage?

Object access rules will be applied within Lime CRM but can't be enforced on the sharing links provided to the user. All users receive the same sharing links, one for edit access and one for view access. If a user with edit access sends the link with edit permission to someone else within the same organization, the receiver will also gain the same access to the file. It does not matter if the receiver is a Lime CRM user or not in this case, and Lime CRM can't control if the sharing link is sent to other persons. The one who receives the link within the same organization will be able to view or edit the document found on that link.

Can I restrict the access of the Azure Lime CRM app?

The recommended setup for file storage in Sharepoint for Live docs is to let the CRM app in Azure to have Files.ReadWrite.All and Sites.ReadWrite.All permissions. If you want to limit the CRM app to only have access to the specific SharePoint site, this is possible, albeit more complicated. Read more here.

  1. By choosing "Only people in your organization" in the Sharing settings dialog (Step 1.9), you make sure that users can not share links to files with people outside your organization. If you wish to make it possible for users to share links to files with people outside your organization, you should choose the option "Site owners and members can share files, folders and the site.". It is important that you understand what this means and make sure this is in line with the security policies of your organization. If you are in doubt, choose "Only people in your organization". Read more in the Sharepoint documentation. ↩↩

  2. If you wish to limit the application to have more restricted access to your Sharepoint (for instance only to the designated site), this is possible but not easy to setup due to the lack of a graphic user interface (GUI). Read more here on how to restrict the permissions. ↩