Document Extractor
Online Documentation

1. Introduction

Document Extractor Built f or Salesforce platform™ is an integration product that transfers documents saved in Salesforce to SharePoint and replaces the original documents with links pointing to them at the SharePoint document location where those documents are saved.

The product runs as SaaS in Azure cloud and can be configured /controlled via a graphical user interface.

Key features

  • Support for the newest Salesforce Lightening experience
  • Support for documents with multiple versions
  • Support for documents with duplicate names
  • Support for email attachments
  • Grouping documents by Salesforce accounts, contacts, leads, opportunities, quotes, contracts, orders, assets, and email messages.
  • Transferring metadata about the Salesforce document, including creator, editor and owner to SharePoint for easier tracking of the documents
  • Possibility to synchronize deletion of documents
  • Possibility to exclude specific Salesforce objects from the stubbing
  • Push notifications
  • Support for SharePoint ADFS federation settings
  • Modern Authentication support for SharePoint

2. How it works

Document Extractor Built for Salesforce platform™ consists of two basic components:

Connecting Software SaaS portal takes care about configuration, subscription management and monitoring.

Document Extractor Built for Salesforce platform™ is responsible for checking Salesforce for new documents, stubbing them to SharePoint, and creating URLS for those documents in Salesforce.

What is document stubbing?

Document stubbing is the process of copying a document from one business application (Salesforce) to another business application (SharePoint) and replacing the original document in the first business application (Salesforce) with a link that points to that document in the second business application (SharePoint).

3. System Requirements

3.1 General Requirements

  • Web browser Chrome, Firefox, or Edge with internet access to SaaS portal (https://saas.connecting-software.com/)
  • Salesforce user with granted elevated access rights to allow modifications of the system Salesforce requirements
  • Single SharePoint user
  • Document library where files will be stored
  • SharePoint must be accessible to our SaaS portal

3.2 Salesforce requirements

The service needs access to your Salesforce. This is to be achieved by creating a dedicated user. Such user should be granted elevated access rights to allow modifications of the system. Please also make sure this account is not used to access your Salesforce by anyone else.

NOTE:

If your Salesforce uses apex code to customize the behavior, interference during stubbing process can occur, sometimes causing the stubbing process of particular files to fail as it is restricted by Salesforce in some of its steps. Please assess your current apex code in use and its possible interference with actions of the stubbing service. In addition, thorough testing is advisable before the use in production environment.

3.3 SharePoint requirements

Your SharePoint will be used to store documents moved from Salesforce. The service needs access to a document library in your SharePoint site/subsite. This can be achieved by creating a dedicated user. Such user should be granted needed rights to the document library to allow creating folders and uploading documents. It can also be achieved by using Modern Authentication and granting access to the Document Extractor App through OAuth. The process for this is described later in this document.

4. Start your free trial

To try the Document Extractor Built for Salesforce platform™, visit our webpage @ www.connecting-software.com and choose “Document Extractor Built for Salesforce platform™” from the products menu as shown below.

From the “Document Extractor Built for Salesforce platform™” product page shown below, click the “SaaS Free Trial” to purchase your free trial.

Add the free trial to your Cart

Complete your purchase profile and place your order by clicking the “Place Order” button

You will see an order confirmation on the screen

5. Purchase

If you already tried Document Extractor and would like to purchase a plan, the process is similar. From the product page click the pricing tab to view the pricing page with the available purchase plans

Choose the desired number of users range and the subscription duration

Type the exact required number of users and click “Add to Cart”. You will require the total number of all users that are in your Salesforce org, or, if you want to limit Document Extractor to stub only files uploaded by specific, named, users, you can reduce this to just the number of named users that you require.

You could also purchase extra data batteries in case you just need more traffic. Choose the desired data battery size and click “Buy Now”.

Choose the number of batteries and click “Add to Cart”

Graphical user interface, applicationDescription automatically generated

Complete your purchase profile and place your order by clicking the “Place Order” button as shown earlier with the free trial.

6. Login to the SaaS portal

Once you purchase a free trial or a paid subscription, you will get 2 emails from us. An order confirmation email and a guidelines email.

Click the “Complete your Registration” button pointing to our SaaS portal in the guidelines email to access your SaaS portal and configure your “Document Extractor Built for Salesforce platform™”

You will be redirected to https://saas.connecting-software.com/. There you need to login to your SaaS portal account if you have one already (1) or create a new one (2):

Now, you need to configure “Document Extractor Built for Salesforce platform™”.

7. Configuration

The following chapter describes the configuration process of “Document Extractor Built for Salesforce platform™”.

7.1 The Configuration Wizard

The CB Document Extractor wizard is a new streamlined way of configuring your stubbing process.

After logging in, you will be redirected to the configuration page. If for some reason you lost the link or forgot how to get there, the wizard can always be accessed through the dashboard quick links section.

ApplicationDescription automatically generated with low confidence

7.2 Use your license

As shown below, you start by choosing between creating a new configuration (1) or activating a license in an existing configuration (2). If you choose the second option, please refer to this section.

7.3 Configuration

When creating a new configuration or editing an existing one, the following sections can be modified (scroll down the configuration window to see all of them):

7.3.1 General

Here is where you can edit the configuration name, as you can see in the figure below. This name is just for future reference in the list of configurations.

7.3.2 Configure Salesforce

In this section you can modify and test the connection to Salesforce.

7.3.2.a Basic Salesforce configuration

Instance should be set to Production to connect to the production organization (usually https://login.salesforce.com), or Sandbox to connect to https://test.salesforce.com. If your organization is on Salesforce Government Cloud then you will require a custom domain to log in to. In this case, select Custom Login Endpoint and enter your custom domain in the form https://your-domain.my.salesforce.com. Take care whether you are entering your sandbox or production domain, these will usually differ by the addition of a -dev or similar suffix before the “my.salesforce.com” part.

The login and password are the credentials for the Service User account created for Document Extractor to access Salesforce. When you create the Service User account, give it a username starting with “document.extractor”. For example: “document.extractor@myorganisation.com”. This account requires permissions to query all and modify all data. The easiest way to do this is to assign it the System Administrator profile, then during installation it will create a “Document Extractor Service User” permission set containing just the required permissions and assign it to itself.

The security token is generated by following the instructions at: https://help.salesforce.com/articleView?id=user_security_token.htm

7.3.2.b Test your connection

To test your connection, please click the Test Connection button. If this is the first time you are connecting to this Salesforce org, it will detect that Document Extractor has not been installed into Salesforce yet and provide a button for doing so.

7.3.2.b Install into Salesforce

Clicking the Install into Salesforce button will install the managed package and create the “Document Extractor Service User” permission set and assign it to the service user. After a successful installation, a green success message is shown.

7.3.3 Configure SharePoint

This is where you can add, remove, modify, and test the connection to SharePoint systems.

7.3.3.a SharePoint Server URL

As shown below, you need to enter the SharePoint server URL

As shown above there are 2 ways to connect to your SharePoint Server. Using username and password or using Modern Authentication. Only one method is required. We will discuss both methods next

7.3.3.b Connecting to SharePoint via username and password

To connect to your SharePoint server this way, you just need to provide a service user name and password. Please ensure that the provided service user has enough permissions on the document library that will be used to store your Salesforce documents.

If your connection uses ADFS federation for authentication, click the “Using ADFS” button to supply those details:

7.3.3.c Connecting to SharePoint via Modern Authentication

Click the “Using Modern Authentication” button to connect to your SharePoint server using Modern Authentication. The Using Modern Authentication configuration screen will be displayed as shown below.

You will need to provide the Tenant Id for your SharePoint tenant, and then click the Authorize button. An administrator will need to authenticate with SharePoint in the popup window to grant consent to the Document Extractor application.

7.3.3.d SharePoint document library settings

Regardless of the Authentication method you chose, please make sure the document location you wish to use exists in your SharePoint prior entering the connection details. After entering valid credentials to your SharePoint, the “SharePoint document library” dropdown will be populated with the document libraries that are found there. Pick the one in which you would like the files from Salesforce to be uploaded to.

Once you provided all needed SharePoint settings for a given SharePoint connection, please use the “Test Connection” button to test your connection parameters.

7.3.4 Adjust Salesforce settings

From here you can edit various settings to customize how the synchronisation is performed:

Synchronize deletion from Salesforce

If this option is checked then if a file stub is deleted from Salesforce, the corresponding file it points to in SharePoint will also be deleted. Otherwise, if left unchecked, then deleting the stub in Salesforce will not affect the file in SharePoint.

Synchronize renaming from Salesforce

If this option is checked then if a file stub is renamed within Salesforce, the corresponding file it points to in SharePoint will also be renamed to match the new name.

Use IDs for folder names

By default, the name of the Salesforce entity which an uploaded file is associated with will be used for the name of the folder in SharePoint. If this option is checked, then the Salesforce ID is used instead. For example:

unchecked: /Accounts/ACME Inc./Contract.docx

checked: /Accounts/0011t00000DC4ZdAAL/Contract.docx

Stub Attachments as Files

Attachments are a legacy technology within Salesforce. It is recommended to use Files instead of Attachments unless you have specific requirements for attachments. If this option is checked, then any existing Attachments will be replaced by File stubs instead of Attachment stubs. Existing Files are always replaced by File stubs, this only affects Attachments. File stubs have several advantages, including:

  • Support for previews (optional)
  • Better user experience for downloading links, no need to open a .url file or see warnings from the browser
NOTE:

Attachments cannot be converted to files on Emails. Instead, Salesforce must be configured to save Email-to-Case attachments as Salesforce files.

Populate SharePoint URLs on previously stubbed documents

If you are using the CB_Url custom field to display the SharePoint URL for documents, then enabling this document will cause Document Extractor to search all existing stubbed files that do not have a CB_Url value already and assign them the correct value. This can be useful if you have stubbed files before creating the CB_Url custom field. More info is in this section.

Clone and Replace Existing Emails

In order to support stubbing files attached to emails, Document Extractor must create temporary files attached to the email at the time it is received (or sent). These files end in _tmp and have the extension .skip. When the real files are stubbed, the temporary files are replaced with the stub files.

For pre-existing emails that were created before Document Extractor was installed, these temporary files will not exist. In order to stub files attached to these emails, Document Extractor can clone the email, creating a new email message that is a copy of the original, and deleting the original email. This newly cloned email will have the required temporary files, and the attached files with then be stubbed.

Email Attachment Delay

The value set for “Email attachment delay” defines the time delay before files attached to emails or uploaded via the files library are processed.

NOTE:

After a file is uploaded as an attachment to an email draft, it is detected by the stubbing service however the file is not stubbed immediately. The stubbing service waits until the email is sent, provided the email is sent within the time duration defined under this setting. The same behavior is applied to files uploaded via Files library in Salesforce, or as attachments to Chatter posts.

SharePoint Listener Site By default the product will capture the changes (upload, rename, move, and delete) done to the documents in the configured SharePoint document library and reflect that in Salesforce (if configured to do so). This setting is an optional setting to ensure that the product immediately does that. More info is in this section.

Configure exclusions

Click on Configure Exclusions to define which object types to exclude from the stubbing process:

On the left will appear all the object types defined in your Salesforce organization (you must first have filled in the correct credentials in the Salesforce connection settings earlier). Select any type from the left and click “Add” to move it to the list on the right. Object types in the list on the right are excluded from stubbing. This means that any file uploaded to Salesforce that is associated with an entity of that type will not be stubbed. In the example shown above, files attached to Contracts will not be stubbed.

It is also possible to exclude Libraries from stubbing. Any file uploaded to Salesforce that belongs to an excluded library will not be stubbed. If a library does not appear in the list of available object type then please add the Document Extractor Service User as a Library Administrator in Salesforce.

The last entry in the list is “(All other files)”. If this is added to the Excluded object types list then it makes the exclusion operate in an allow-list mode rather than a block-list mode, and all object types which do not appear in the Available object types list will be excluded. This allows exclusion of files on object types which do not appear in the list.

7.3.5 Adjust SharePoint settings

Catch-all folder name

If an uploaded file is not associated with any Salesforce entity, it will be placed in a folder in SharePoint using this name.

Provide temporary public links

Enabling this option will create a temporary public sharing link whenever a document is accessed from Salesforce. Either read-only or edit access may be granted, depending on whether the user has Viewer or Collaborator access to the file in Salesforce.

This is useful if Salesforce users will not have SharePoint accounts, or if you wish to use security restrictions in SharePoint to prevent users from being able to browse and view all the files in the Document Extractor document library. To do this, permissions should be set on the Document Library such that no ordinary users have permission to view its contents, only administrators and the Document Extractor Service User.

When a Salesforce user downloads a file, they are issued a very short-lived anonymous link which grants them access only to the specific document they have downloaded. In this way, a Salesforce user is allowed to see any file in SharePoint to which they have access in Salesforce, but no file to which they do not have Salesforce access.

This functionality is not supported for Attachments, only for Files. Existing attachments in Salesforce can be converted to Files when stubbed by enabling the “Stub Attachments as Files” option within the “Salesforce Settings” section.

Synchronize upload to SharePoint

If this option is checked then when a new file is uploaded directly to SharePoint, a corresponding file link pointing to it will be created in Salesforce.

NOTE:

Only files that are uploaded to existing Document Extractor folders will be recognized. If a folder already has files in it that have been placed there by Document Extractor, then uploading new files to that folder will result in stubs being created in Salesforce (attached to the same Salesforce object as the other files in that folder).

Synchronize deletion from SharePoint

If this option is checked then if a stubbed file is deleted from SharePoint, the corresponding file link pointing to it will also be deleted from Salesforce. If left unchecked, then deleting the file from SharePoint will not affect the file link in Salesforce which could result in broken links in Salesforce.

Use separate sub-folders for different file types

If this option is checked then each file type will be placed within a separate sub-folder, determined by the file extension. For example:

unchecked: /Accounts/ACME Inc./Contract.docx

checked: /Accounts/ACME Inc./DOCX/Contract.docx

Configure field mapping

The “Configure field mapping” button allows mapping of fields from Salesforce into SharePoint custom columns.

The standard file details that can be stored on SharePoint are:

  • Created By: The Salesforce user who created the original file
  • Description: Document description
  • Owner: The Salesforce user who owns the file
  • Version: The document version number within Salesforce

As well as these, any custom fields that you have defined within Salesforce on ContentVersion may also be used.

When the values of these fields are updated in Salesforce, the mapped values in SharePoint will also be updated. For custom fields, and for the Description field, changes made in SharePoint will also be reflected in Salesforce.

7.3.6 Adjust Service settings

Full Scan Polling Interval

Document Extractor uses Push Notifications to watch for files uploaded to Salesforce and optionally also files uploaded to SharePoint and respond to them immediately. Polling is also used as a fallback method for checking for new files, in case the push notification system is not configured, interrupted or misses a file, it will be caught by the next full poll.

The value set for “Polling interval” defines the time delay between two full polls, to check for any files that have not already been immediately stubbed.

Minimum and Maximum File Size

These options allow limits to be set on the minimum and maximum size of file (in MB) to stub. Files larger or smaller than these limits will be ignored and left in Salesforce

Create previews

If this option is checked, then File stubs are created as png image files containing a preview of the file instead of .url files. The url to the file in Salesforce is embedded within the metadata, and when downloaded through Salesforce the browser is redirected to SharePoint in the same way as for .url files. Preview images take up more storage space in Salesforce, several KB compared to around 100B for a .url files.

Previews are only created when SharePoint provides previews for the file type in question. SharePoint Online can provide many file previews, but SharePoint OnPrem generally does not. Where a preview is not available for a file, the standard .url file stub is created instead.

Seal with Port of Trust

If you have a Port of Trust account (available for purchase separately from Connecting Software) then enabling this option will result in every file that is stubbed having a Seal created for it at the time that it is stubbed. This allows for external verification that a document has not been altered after being stubbed.

Send follow-up emails with sharing links

When sending emails from Salesforce with stub files attached, the recipient will receive a stub file that links to the file in SharePoint. If Salesforce is used to send emails to external customers, or users who do not have access to SharePoint, then this will mean they are unable to access the attached files.

Enabling this option causes Document Extractor to watch for emails being sent from Salesforce, and where an email is detected which has stub files attached to it, a second email is automatically sent to each recipient which contains a private SharePoint sharing link that they can use to access the file. This individual link is tied to their email address, and provides read-only access to the file.

For this functionality, an SMTP server used to send the emails must be configured. Click the “SMTP Server Details” link to open the email server configuration page. More details in this section.

Do not stub before

If you wish to leave existing documents within Salesforce and stub only newly uploaded documents, a cut-off date may be specified here. Any existing document that was uploaded before this date will be ignored by Document Extractor and not stubbed.

Process files uploaded by

This section defines the users whose documents will be stubbed by document extractor service. Based on the number of licenses you have you could choose “all users” or only the users in the Document Extractor Users group. This public salesforce group is created automatically by Document Extractor when you click the Document Extractor Users link.

To use only a subset of users click the “Document Extractor Users” link

That will open the “Document Extractor Users” group shown below

Click Edit and add the desired users

Select the desired users (1) and add them to the selected members list by clicking the “Add” button (2). Once done, click save.

7.3.7 Save your configuration

Once done with the configuration, click the “Save” button to return to the configurations screen.

7.3.8 Activate your configuration

To activate a configuration, please click the burger menu icon. Then click “Activate Service”.

Graphical user interfaceDescription automatically generated

The Service activation window will be displayed as shown below

Graphical user interface, applicationDescription automatically generated

Copy the activation code from the e-mail you received earlier and paste it into the “Activation Code” field in the “Service Activation” window and press the “Activate” button. A confirmation message will be displayed confirming that the service was activated successfully.

Graphical user interface, text, applicationDescription automatically generated

7.3.9 Start your configuration

Now the configuration screen should display the configuration just provided. The “Stopped” message is displayed when stubbing is stopped. To start stubbing, click the start button:

7.3.10 Edit your configuration

To edit a configuration, click the menu button on the right of the configuration, and choose “Edit”.

NOTE:

Stubbing must be stopped to edit the configuration. If it is not stopped, the configuration may only be viewed and not edited.

7.4 Activate an existing configuration

If you choose the second option, you can choose from the selection box the name of the configuration that you want to activate the license and press the ‘activate’ button which will then request for your activation token.

If you purchased a trial or a regular subscription you should have received an activation code via e-mail. The field ‘Activation Code’ should be automatically pre filled, but if that is not the case, to activate the service, Copy the activation code from the e-mail you received earlier and paste it into the “Activation Code” field.

Graphical user interface, websiteDescription automatically generated

7.5 Configure your service manually

You need to login to your portal account first as explained before. From the left side menu, click the Document Extractor Built for Salesforce platform™ button to display the Configuration screen shown below.

To create a configuration, click “Create New” as shown below.

This will bring the same screen displayed earlier. Please follow this section to configure your configuration.

7.6 Create multiple configurations

Graphical user interfaceDescription automatically generated

If you have more than one Salesforce organization for which you want Document Extractor to stub files, then additional configurations can be created. These can be started and stopped independently. Please do not run multiple configurations for the same Salesforce organization simultaneously, even using different service user accounts.

To create another configuration, use the “Create New” button, or clone an existing configuration by clicking the Menu button, and the Clone command:

If cloning a configuration, and not modifying the Salesforce credentials, remember to always stop any running configuration for that Salesforce organization before starting a different one.

7.7 View your configurations

A screenshot of a computerDescription automatically generated with medium confidence

After configurations are created, they will be listed in the configuration page as shown. From the above screen, you could do the following:

  • Create New (1): Creates a new configuration.
  • Requested Status (2): is the status requested by the user. Could be “Start” or “Stop”
  • Status (3): Actual configuration Status. Could be “Starting”, “Processing”, “Started” and so on.
  • Start/Stop configuration (4): Starts/Stops each configuration
  • Burger Menu (5): to display additional options as explained in the next section

7.8 Delete your configuration

Graphical user interfaceDescription automatically generated

To delete a configuration, please click the burger menu icon next to the configuration you wish to delete and click “Delete”

Warning

By deleting a configuration, the configuration will be permanently deleted with all activated subscriptions (even paid ones). These subscriptions are not transferable to other configurations.

8. Additional configuration settings

8.1 Access SharePoint documents without a SharePoint license

Please follow the next steps to offer your Salesforce users the option to get the documents from SharePoint based on their access rights and permissions in Salesforce and without having a SharePoint license:

  1. Configure your SharePoint site to allow creation of sharing links to share with Anyone. See the SharePoint documentation for more details.
  2. Enable temporary public link creation for the Document Extractor configuration by navigating to the desired configuration and clicking the Edit Button as shown earlier. Navigate to the Configuration settings and enable the “Provide temporary public links” option.

NOTE:

If the user has a SharePoint account which has Edit permissions for the document extractor library then they will be able to edit the file even if they have only Viewer permission for the file in Salesforce – the link does not deny any rights, it only grants new ones (temporarily).

8.2 Configure push notifications for immediate SharePoint sync

When a file is renamed or moved (within the configured document library) the stub file in Salesforce is updated to point to the new URL for the file, and when appropriate, renamed. The stub file will not be moved in Salesforce.

Optionally, when a file is deleted in SharePoint, it can also be deleted in Salesforce.

A further option can be enabled to allow creation of stub files in Salesforce for files that are uploaded directly to SharePoint.

By default, those changes will be synced according to the duration specified for the Full Scan Polling Interval. To have these changes sync and take effect immediately (rather than on the next full iteration), you must create a site in salesforce that will host an apex class. That site will receive notifications from SharePoint whenever a change is made on one of the documents in the document library configured with the document extractor service. The apex class will process those changes and apply them to the links in Salesforce accordingly. To be able to create a site you would need to create a domain first.

These steps can only be performed after you have successfully installed Document Extractor into Salesforce.

NOTE:

This system can be used with SharePoint Online, or SharePoint 2019 On-Premise onwards as they support WebHooks.

Please follow the following steps to set up the listener for changes from SharePoint:

  1. Login to the org configured with the Document Extractor service
  2. Go to setup and search for sites
  3. You need to have a Salesforce domain before you can create a salesforce site.
  4. A page similar to the one below will be displayed If you don’t have a domain. If you have a domain skip this step and move to the next one.
    1. Type your domain name
    2. Check Availability
    3. Read and accept the Terms of Use
    4. Register the domain
  5. If you have a salesforce domain, a page similar to the one below will be displayed
  6. To create a new site, scroll to the end of the page and click “New” from the sites section
  7. This will display the Edit site page shown below
    1. Provide a meaningful site label (we recommend cb_doc_extractor)
    2. The site name will be provided automatically.
    3. Provide meaningful description
    4. Choose a default web address (we recommend the same name as the site name)
    5. Click “Active” to activate the site once it’s saved
    6. Select “Unauthorized” from the Active Site Home Page List
  8. You should have something similar to the below screenshot
  9. Click save as shown above to be redirected to the site details page shown below
  10. Graphical user interfaceDescription automatically generated with medium confidence

  11. Click “Public Access Settings” button shown above
  12. Graphical user interface, text, application, emailDescription automatically generated

  13. Click Enabled Apex Class Access link shown above then click Edit as shown below
  14. A picture containing chartDescription automatically generated

  15. From the list of “Available Apex Classes” select “docex.CB_SharePointListener” apex class (1) and add it to the list of “Enabled Apex Classes” by clicking the add button (2). This apex class will process notifications received from SharePoint.
  16. Once done, click Save.
  17. Go back to the sites page and click the link from the site URL column
  18. This will open the site url in the browser. Copy the site URL from the browser
  19. Stop and edit the configuration configured the Salesforce org in which we just created the site
  20. Paste the site URL into the “SharePoint Listener site” field in the document extractor configuration edit page and click Test connection. If the Salesforce site was misconfigured or mistyped in the configuration page, Test connection button will display a message reading “Error! Could not connect to the SharePointListener” or “The remote server returned an error: (503) Server Unavailable”. If you configured your site correctly and typed it correctly in the configuration page, you should see the green success message you saw earlier.

8.3 Email Notification of Errors

It is possible to configure email notifications by clicking the Notifications option from the main screen as shown below.

Per default the alerts are disabled completely. The first switch must be turn on to activate alerts. It is useful option to temporary disable all notifications (for example during maintenance or connectivity/ local network issues). It is possible to choose for what kind of events notification should be sent.

To activate license issue related notification, turn on the license switch. It may happen that stubbing service gets interrupted, to get notification about it activate service interruption switch. The fourth switch activates notification about document failed to stub. The next section contains settings called cumulative limit. It represents the amount of time (in minutes) that notifications will be stored before sending them all in one go. This cumulative limit is related to general stubbing warnings and errors. They can be activated via the Stubbing errors & warnings switches. The last section enables to define recipients of email notification. To add new email address, fill it in to field and click on Add New button. It is possible to disable particular email address using the switch at the email row and it can be also deleted via trash button located at the same row.

9. Customizing behavior through custom fields

There are special custom fields that can be created to customize the Document Extractor stubbing behavior. Except “CB_Revert” custom field, each field can be created either on Content Version, in which case it applies only to the specific file, or on any other object type, in which case it applies to all files that are uploaded to that record. In all cases, it is the Field Name which is important, the Field Label may be set to any value. It is not necessary for the field to be shown in the UI layout.

NOTE:

After any change to the Salesforce schema through the Object Manager, the Document Extractor configuration must be stopped and started again to pick up the changes.

9.1 Viewing the SharePoint URL within Salesforce

It is not normally necessary to view the URL to the file in SharePoint from within Salesforce. Clicking the Download button will open the file in SharePoint automatically. However, if you wish to make the URL visible without having to open it then this can be achieved by creating a custom field on the ContentVersion object named “CB_Url”. To do this, in SalesForce Setup, go to Object Manager, Content Version, Fields & Relationships, then click New to create a new field. The field type should be URL, and the Field Name must be exactly “CB_Url”. The Field Label, which will be displayed in the UI, can be whatever you like.

Graphical user interface, text, applicationDescription automatically generated

After this field is created, any new file stub that is created will have this value populated with the URL for the real file in SharePoint. It can be viewed by clicking View File Details on a file, under the Details tab.

This field can also be created on any record type, in which case the URL to the SharePoint folder that contains all the files attached to that record will be populated on the record. This needs to be done individually for each record type, Salesforce has no facility to easily add a field to multiple types.

9.2 Skipping the stubbing of certain document or documents

The CB_Ignore field must be created as a Checkbox data type.

If the value is true (checked) and the field is defined on the ContentVersion (file), then that file will not be stubbed by Document Extractor.

If the value is true (checked) and the field is defined on any other entity type, then all files belonging to that entity will not be stubbed by Document Extractor.

Document could be stubbed later on after setting the value to false (unchecking).

9.3 Defining a parent Salesforce entity or SharePoint folder

The CB_Parent field may be a Lookup field, or a text field. If it is a text field, the value must be the Salesforce ID of another record.

When defined on a Content Version this overrides the normal link relation of which entity it belongs to, and allows specifying exactly which entity should be treated as the owner of the file (by ID). The file will be placed in the folder of that entity when stubbed.

When defined on any other entity type this specifies which other entity (if any, by ID) should be the parent of the given entity. for the purposes of determining the path to the file in SharePoint. This allows for a deep hierarchy of folders, where the file will appear in a folder for the entity it belongs to, and the folder of that entity will appear in a folder for its parent entity, and so on

9.4 Defining a custom SharePoint folder path

The CB_Folder field must be a text field. When defined on a Content Version, this overrides the normal calculation of destination folder by specifying the exact path in SharePoint (relative to the document library root) of the folder where the file should be stored. If left blank, the normally calculated destination folder will be used. Note that the name of the file can't be defined here, just the path (folder).

NOTE:

Files uploaded to SharePoint in a custom folder of this sort cannot be synced to Salesforce, as they are not associated with any specific entity.

When defined on any other entity type, this specifies the folder to use for all files belonging to that entity. If the value starts with a / then it is treated as an absolute path (relative to the document library root). If it does not start with a / then it is treated as relative to the parent entity folder (if any).

For example, if you have a Contract whose parent is an Account, then…

  • The default behavior would give a path like "Document Library/Accounts/ACME Inc/Contracts/Supply001/Invoice.docx".
  • If you set CB_Folder on the Supply001 contract to be "Invoices/1" then the result would be "Document Library/Accounts/ACME Inc/Invoices/1/Invoice.docx".
  • If instead you set it to be "/Invoices/1" then the result would be "Document Library/Invoices/1/Invoice.docx".

9.5 Stubbing to multiple SharePoint Sites and Subsites

The CB_Subsite field must be a text field. This field allows a file to be stubbed into a different SharePoint subsite. Document Extractor must be configured with the root SharePoint site, and the value of this field will be appended to the URL to obtain the subsite.

For example, the SharePoint server URL in the Document Extractor configuration may be:

  • https://example.sharepoint.com/sites/demo/.

If the value of the CB_Subsite field was “sub1” then the following subsite would be expected:

  • https://example.sharepoint.com/sites/demo/sub1.

Subsites will not be created by Document Extractor, they must be created by the SharePoint administrator, and already exist. The credentials supplied to Document Extractor for the root site must also be valid for the subsite.

There must be a document library in the subsite with the same name as the document library configured for the root site, however this may be overridden using the CB_DocumentLibrary field as described next.

If the destination is a different site, rather than a different subsite, then the CB_Site field can be used instead. This field must be the complete URL to the SharePoint site. However, note that the same restrictions still apply – the credentials supplied to Document Extractor for the original root site must also be valid for this site, therefore it must be part of the same tenant.

NOTE:

Synchronization of changes from SharePoint is not supported for custom sites or subsites. Revert feature will not revert files that have been uploaded to those subsites as well.

9.6 Stubbing to multiple SharePoint document libraries

The CB_DocumentLibrary field must be a text field. This field allows a file to be stubbed into a different SharePoint document library from the one set in the Document Extractor configuration. Libraries will not be created by Document Extractor, they must be created by the SharePoint administrator, and already exist.

NOTE:

Synchronization of changes from SharePoint is not supported for custom document libraries. Revert feature will not revert files that have been uploaded to those document libraries as well.

9.7 Restoring a file back to Salesforce from SharePoint

The CB_Revert field can only be defined on ContentVersion. It must be a Checkbox data type. If it the value is true (checked), and the file has been stubbed, then the file will be brought back from SharePoint into Salesforce. If the file is not stubbed, then CB_Revert will prevent it from being stubbed.

NOTE:

You must have sufficient free storage space within Salesforce to upload the file being reverted.

10. View your recently stubbed files

Graphical user interfaceDescription automatically generated

A list of the 100 most recently stubbed files may be obtained by clicking the Menu button, and the Recent files command.

11. View the not stubbed files

Graphical user interfaceDescription automatically generated

When a file cannot be stubbed for some reason, Document Extractor will automatically retry stubbing it after a delay. If, after 5 repeated retries the file can still not be stubbed, it will be listed as a “Not stubbed file”. To view these files, click the Menu button, and the Not Stubbed files command.

From this list, a file can be manually triggered for further retries by using the “Retry again” link. To determine why a file was not stubbed, please check the logs page.

12. Reverting Stubbing

If you want to reverse the process of stubbing and return all the files that were moved into SharePoint back into Salesforce, then a Revert command is available. To use this, first stop the configuration, then click the Menu button and the Revert command:

Graphical user interface, applicationDescription automatically generated

Document Extractor will first check that you have sufficient storage space within Salesforce to accommodate all the files that have been stubbed, then begin replacing the stub files with the real files from SharePoint. As each file is uploaded to Salesforce, it is deleted from SharePoint. The configuration will automatically stop when there are no more files to revert.

13. Troubleshooting

13.1 View configuration logs

To help troubleshooting performance issues if any, we provide a couple of logs capturing information that could become handy. To view available logs, please click the Show Logs button from the top menu to display the Document Extractor Built for Salesforce platform™ Logs Page as shown below. There are four level of messages:

  • Debug: Shows debug information for errors occur during the stubbing process.
  • Error: Shows errors occur during the stubbing process
  • Warning: Shows warnings generated by the stubbing process
  • Info: Shows information regarding the stubbing process.

13.2 View SaaS platform logs

To view available logs, please navigate to Logging -> Show Logs to display the Portal Logs Page as shown below.

Graphical user interfaceDescription automatically generated

13.3 Create a ticket

If you ever need help with your service or want to contact us, please click the Contact Us link located at the footer of the SaaS portal.

13.4 View the release notes

To help our clients to keep up with our improvements and new features we have a release notes page. To see it, please click the Release Notes link located at the footer of the SaaS portal. There you will be able to see the changes made for each version.

14. Navigating the Dashboard

After having an active configuration, this configuration can be accessed through the SaaS Configuration menu or through the SaaS Dashboard:

Graphical user interface, applicationDescription automatically generated

In the Dashboard you will find quick links (1) as well as your configurations (2). Keep in mind that by clicking ‘Go to Configuration’ (3) you will be redirected to configuration page (refer to section View Configurations) and by clicking ‘More Info’ (4) you will be able to see more information about the configuration.

Each configuration has information about traffic consumption, number of subscriptions, batteries and users:

Graphical user interface, applicationDescription automatically generated

  1. Service icon/name
  2. Name of your configuration
  3. Link to the Configuration’s list page (where you can start/stop the configuration)
  4. Available traffic – takes into account all active subscriptions traffic and available batteries
  5. Battery in use – an icon shows if the specific service is using a battery at the moment
  6. Number of available subscriptions (both active and future)
  7. Number of available batteries
  8. Number of users
  9. More info link

Clicking anywhere on the configuration box (2) will redirect you to a section where you can see more information about the service such as subscriptions, batteries and available traffic.

14.1 Valid Subscriptions

Scrolling down to the next section, you can find all active and future subscriptions. For each subscription a monthly traffic graphic can be seen as well as other important information.

A picture containing background patternDescription automatically generated

Expanding a subscription, you could see useful information, like validation period and monthly traffic used/remaining.

Graphical user interface, applicationDescription automatically generated

  1. Subscription’s validation date
  2. The day the subscription was activated
  3. Subscription plan
  4. The activation code
  5. Monthly traffic information
    1. Available traffic percentage
    2. Monthly plan (start date – end date)
    3. Available, used and remaining traffic for the month

14.2 Available Batteries

Scrolling down more, in the next section the user can see all the available batteries for the configuration. These batteries are spent only when all valid subscriptions’ traffic is spent for that month. Keep in mind that this section is only shown for services that use traffic. Each battery has the following information:

Graphical user interface, applicationDescription automatically generated

  1. Battery percentage
  2. Total battery traffic
  3. Remaining battery traffic
  4. Activation code

14.3 Other Information

In the last section, you can find more info, for example, batteries that have all their traffic spent or subscriptions that are already expired.

Graphical user interface, applicationDescription automatically generated

15. Conclusion

This document described installation, configuration and maintenance of Document Extractor Built for Salesforce platform™ by connecting software for stubbing of documents from Salesforce to SharePoint.