Documents

From Resco's Wiki
(Redirected from SharePoint)
Jump to: navigation, search
Integration with third-party systems


If you need to store a large number of documents, you don't have to rely on CRM attachments. Resco Mobile CRM can leverage cloud storage services, such as OneDrive or SharePoint.

Introduction

When talking about documents or attachments, we refer to a rather large group of file types: PDF, Microsoft Office documents (Word, Excel, PowerPoint, etc.), HTML files, images, video files...

In a CRM, documents are traditionally stored as attachments on CRM servers. However, Resco supports also files stored on external document servers and we refer to them as documents.

Resco supports 5 document servers - Box, DropBox, GoogleDrive, OneDrive, and SharePoint; users may use any number of them.

The basic principles are the same as for attachments:

  • A document must be attached to a single existing CRM record.
  • A CRM record can have multiple attached documents.
  • Standalone documents are unsupported. A document becomes orphaned if its CRM record gets deleted. Orphaned documents are deleted in sync cleanup, or by cascading delete.

The integration to document servers must be enabled in the app, and it must be also configured in the Woodford project.

Log in to your document server in the app

If your document servers are properly configured (see below), you need to log in to your document server to start using it.

  1. Start Resco Mobile CRM or other Resco app that supports documents.
  2. Tap Setup on the home screen.
  3. In the Accounts section, log in to the document server by using your credentials (or the credentials of your company).
  4. Save your setup.
  5. Return to the home screen and synchronize your app.
Note All documents that you want to access must be downloaded to the offline database, even if you want to use Mobile CRM app in online mode.

Box, Dropbox, Google Drive, OneDrive

  1. Edit an app project in Woodford.
  2. Select Documents from the Project menu.
  3. Check Enable Documents and click Save.
  4. Select Configuration from the Project menu and go to Integrations tab.
  5. Enable the document storage that you're using and specify the root folder, then click Save.
    Your documents are saved to the following directory structure: root\entity_name\record_name_record_id.
  6. Next, edit the forms for various entities and add Cloud Document List to the entity form, so that users can access documents associated with entity records.
Warning Integration with the document server may fail if the root folder does not exist. Verify that the root exists; if it does not, create it manually.

SharePoint integration

Note Out of the box, the ntegration with SharePoint document storage is only available on Microsoft Dynamics CRM.

Server-side prerequisites

Mobile CRM application supports both Sharepoint List Component base integration and Server-Side Integration. Both will result in the creation of the required records. The difference is in the CRM web user interface, which is not important for Mobile CRM. The List Component is deprecated, but please read the following guidelines to make sure you pick the right choice.

Mobile CRM requires that sharepointsite and documentLocation records are correctly configured. This means that these records must exist:

  • At least one sharepointsite record with the sharepoint url
  • At least one documentLocation per Sharepoint-enabled-entity root
Warning Don't create these records manually! Use the wizard instead.
  1. In Dynamics CRM, go to Settings > System > Document Management.
  2. Click Document Management Settings to start the wizard.
  3. Select entities that should have SharePoint documents integration.
  4. Enter the URL of the SharePoint site.
  5. Optionally, select the Folder Structure and Automatic folder creation.
  6. Click Finish to conclude the wizard.

Enable SharePoint in Woodford

  1. Edit an app project in Woodford.
  2. Select Documents from the Project menu.
  3. Check Enable Documents and Enable SharePoint.
    Enabling SharePoint integration will also enable SharePoint Site entity in the mobile project. Please do not make any changes to this entity.
  4. If you have SharePoint on premise, you can define the internal and external SharePoint server URL.
  5. Click Save.
  6. Select Configuration from the Project menu and go to Integrations tab.
  7. Scroll down to SharePoint section and select Enable SharePoint.
  8. Enable one of the APIs, then click Save.
    • Use Partial SharePoint REST API (legacy) if you don't use OAuth2 or if you're working with a very large number of SharePoint lists. The legacy interface is also suitable for SharePoint on premise.
    • Use SharePoint REST API (OAuth2) for SharePoint Online with OAuth2 authorization shared with Dynamics (single sign-on). This option also supports multi-factor authentication.
  9. Next, edit the forms for various entities and add Cloud Document List to the entity form, so that users can access documents associated with entity records.
  10. Finally, if your login credentials for SharePoint differ from your CRM credentials, go to Mobile CRM app's Setup and log in to SharePoint. If SharePoint uses different authentication or you use CRM on-premise vs SharePoint online (or vice versa) than CRM, you also need to specify the Type.

Troubleshooting

SharePoint documents can only be used when the documents and associated records are available in the offline database (even if you are using the app in online mode). The records that you are using in online mode must be synchronized. Adjust Sync Filters for specific entities to ensure that the necessary records are downloaded and available in offline mode.

Document Location records need to be downloaded to the offline database. They are needed (among other things) to define the folder structure, i.e., the path to SharePoint server documents. Clear the entire Sync Filter for Document Location entity. If the documents become available in the app, but you need to limit the Document Location records, continue with the next step.

The document location defining the CRM entity root folder must have its regarding set to NULL (empty). Otherwise, they are treated as file location records; this breaks the folder structure used in the app. If you need to filter Document Location entity records, make sure that records with an empty regarding are OR-ed with the other conditions; for example:

Document location entity sync filter for sharepoint documents.png

External document synchronization filter options

Document filters available in the Configuration section of Woodford allow you to exclude specific documents from download to the Mobile CRM app’s database, based on the file type, entity, a file they’re associated to, how many and what maximum size per file type, etc.

See also this part of our webinar. Webinar

Technical information

On the device, external documents are stored in two locations:

  • Document headers are stored in the database entity resco_sharepointdoc. Each record describes one document - its file name, path, size... but mainly the lookup to the owning CRM record (resco_regardingid).
  • Document bodies are stored separately in the blob storage.

SharePoint specifics

SharePoint is organized via sites and lists. Resco mobile apps synchronize with specific SharePoint lists - document libraries.

  • Each document location represents a subfolder of some document library.
  • Documents represent document library list items.

In the Dynamics CRM world, Resco relies on existing Dynamics SharePoint integration consisting of two entities:

  • sharepointsite - lists SP sites used in the integration
  • sharepointdocumentlocation - Lists document locations, i.e. folders of document libraries and their corresponding CRM records.

In the standard integration, CRM admin selects entities (account, contact…) that can have SharePoint attachments. In turn, respective SharePoint document libraries are created: One library per one entity with the library names identical to the entity names.

Resco mobile apps sync first these two above-mentioned entities (as part of the standard sync) and then use them to control communication with SharePoint.

If you want to use SharePoint storage for other platforms (Resco Cloud or Salesforce), Woodford admin needs to define these tables manually. At the minimum, the sharepointsite table must have a single record pointing to a suitable SharePoint site; document locations are created by Resco apps when needed.

Resco apps support 3 alternative ways of SharePoint communication:

  • The oldest ListService interface is used by default. Needs extra API calls to obtain necessary info about document libraries. (GetListCollection does not return root folders.)
  • Enable the SharePoint REST API configuration setting to use ListService partially using REST API. This interface is more efficient than the first because it does not need GetList API calls.
  • Enable New SharePoint REST API configuration setting to use the full REST API. It is just as efficient at the second option. Additionally, it uses the OAuth authorization, with a single sign-on with Dynamics possible.

Document synchronization

Documents are synchronized in a separate step after the sync of CRM records is completed.

The download is organized similarly to attachments:

  • Download of document headers from external document server. If you have multiple servers, they are queried one by one. The result of this step is an updated resco_sharepointdoc table containing headers of (non-downloaded) documents.
  • Not all known documents need to be downloaded. Woodford admin may use either the Max Attachment Size setting or the BlobStoreFilter to determine which documents are downloaded. Non-downloaded documents can be downloaded on demand from UI. Documents that should be downloaded are enqueued in a so-called FileDownloadQueue.
  • The download queue works in parallel to the above step. Its task is to download the document bodies (files). If the download is interrupted, the queue resumes its work at the next sync. Unlike attachments, asynchronous document download is unsupported.

The upload phase is conceptually simpler: Document changes (creations/deletions) are uploaded one by one.

Caveats

Documents may consume a large portion of device memory.

  • Use MaxAttachmentSize setting or BlobStoreFilter to limit needed storage.
  • To measure the used document storage (need to be done on Windows) go to the %APP_DATA% folder, then subfolder blob, then subfolder resco_sharepointdoc.

API call consumption

  • Some calls are needed for document headers. (Exact specification is server-dependent.)
  • Each downloaded document requires 1 call.

Dynamics SharePoint integration

  • Dynamics lately added another SP-related entity: sharepointdocument - used internally by Dynamics for presentation purposes.
Woodford admins might be tempted to enable this entity, but this would be pure overhead - Resco apps do not use it.
(Moreover, for MCRM versions prior to v12.2 this entity causes sync failure. (Because it does not have the rowversion field.))

Too many GetList calls

  • Applies to SharePoint with old ListService API. If you use SharePoint for many purposes, you might end up with 10K+ lists and the sync might get penalized by long delays (up to several hours per sync!). While Resco apps offer some tricks for this problem, the simplest and best solution is to start using the REST API. This eliminates GetList calls altogether.

Root document locations

  • Document locations are hierarchical. Resco apps require that you have a root location for each entity type which allows SharePoint attachments. For example, you need to have a location for "accounts". If the location exists, MCRM can create a location for any particular account record. It does so by creating a subfolder with the name <record_name>_<record_id>.
  • In the opposite case, Resco Mobile CRM refuses to create SharePoint attachments for the account entity.
  • Only documents located directly in the folder of a CRM record are downloaded. Resco Mobile CRM does not support additional folder structure; documents in subfolders are not downloaded.

Additional resources

For more information about documents: