Skip to main content

Sales2CM Installation Guide

Raise a support ticket

DISCLAIMER​

Any advice FYB provides in relation to setting up any FYB App, FYB Add-in, FYB Connector and or advice in relation to opening access to your on-premises or in the cloud systems will be general advice only. This means that the advice is of a general nature and will not consider your network setup, network infrastructure or any security requirements that you may have or in fact need. It is highly advised that you seek advice from internal or external providers to ensure that they are comfortable with what is required prior to going ahead with any deployment, setup, or configuration for external access.

LICENSE DETAILS​

Please contact FYB for a valid license if you are yet to obtain one for your connector.

INSTALLATION COMPONENTS​

The following installation components are required to ensure the full functionality of Sales2CM:

  • FYB Sales2CM Web Application - This is a server-side installation
  • FYB CMLauncher - This is a client-side installation

SALESFORCE CONFIGURATION​

Note

If upgrading from an older version of Sales2CM and the Salesforce app is already created and configured you must still double check the below settings as some may have changed.

  1. Log in to Salesforce with an administrator account

  2. Click the cog icon and select the Setup option

    setupbutton.png

  3. Under Apps, select App Manager

    selectappmanager.png

  4. Click New Connected App

  5. Enter the following details under Basic Information. Use your organisation's email and contact phone number. Connected App Name: FYB Sales2CM API Name(Automatic): FYB_Sales2CM Contact Email: example@example.com.au Contact Phone: XXXX XXX XXX

2020-10-01_11-40-24.png 6. Under API (Enable OAuth Settings) check Enable OAuth Settings

enableoauth.png 7. Enter the Callback URL: https://dummy.org (this will not be used) 8. Enable the Use digital signatures option

usedigital.png 9. Click Choose File and upload the .cer file that contains the public key of your Sales2CM certificate (obtained from the CERTIFICATE BASED AUTHENTICATION section of this guide) 10. Under Selected OAuth scopes select the following:

  • Manage user data via APIs (api)
  • Access unique user identifiers (openid)
  • Perform requests at any time (refresh_token, offline_access)

2022-05-25_16-15-53.jpg

  1. Click on the Save button

    Note!

    As advised by Salesforce, it can take several minutes (2 to 10) for changes to the App settings to take effect.

  2. Under Apps, select App Manager. Click the drop-down arrow for FYB Sales2CM and select Manage

    Manage.png

  3. Click on the Edit Policies button

    edit policies 2.png

  4. Under OAuth Policies set Permitted Users to Admin approved users are pre-authorized, IP Relaxation to Relax IP restrictions, and Refresh Token Policy to Expire refresh token after 1 Day(s)

    Relax2.png

  5. Click on the Save button

    Save.png

  6. Under Apps, select App Manager, click the drop-down arrow for FYB Sales2CM, and select View

    view.png

  7. Under API (Enable OAuth Settings), take a copy of the Consumer Key

    consumer key.png

  8. Under ADMINISTRATION, click Users, then click Profiles, then next to System Administrator click Edit

    System admin.png

  9. Under Connected App Access check FYB Sales2CM

    access.png

  10. Click on the Save button

    Save.png

INSTALLING SALES2CM WEB APPLICATION​

LICENSE​

  1. Create a folder to house the license file (.lic) on the IIS Server

  2. Place the license file in this folder

    Note

    You will be asked to enter this location during the installation

TRUSTED USER ACCOUNT​

  1. Add the account that will run the application pool as a Trusted User Account in Enterprise Studio. Please refer to your Enterprise Studio help file on adding trusted accounts. If using a system account (application pool identity, network service, etc) you will be required to enter the details as DOMAIN\ServerName$. If using a dedicated windows service account, you will be required to enter the details as DOMAIN\username.

    Note

    The account running the app pool will need to have a valid Content Manager login.

UPGRADING FROM SALES2CM v1 to v2​

When upgrading from Sales2CM v1.x to v2.x, prior to installing the new MSI, the following must be completed.

  1. Navigate to IIS > Click on the Server Name > Click Configuration Editor

    image.png

  2. Within the section dropdown enter "system.applicationHost/serviceAutoStartProviders" and Click on Edit Items

    image.png

  3. Highlight the Sales2CMAutoStartProvider - Sales2CM.PreloadClient and click on the Remove button

    image.png

INSTALLATION​

The FYB Sales2CM MSI will:

  • Deploy the installation files
  • Setup the application pool and application in IIS
  • Setup the temp folder
  • Configure the application settings as specified by the user

To install Sales2CM, follow these steps:

  1. Run command prompt as an administrator and launch the Sales2CM-XXX.msi

  2. Click on the Next button

    install1.png

  3. On the Web Application Settings screen, select a Site to host the application and click on the Next button

    image.png

    Note

    The site the connector is being installed underneath must be https protected and able to communicate with the Salesforce API outside your network.

    image.png

  4. On the Application Pool Settings screen, enter the domain, username, and password for the Application Pool identity. Click Next

    image.png

    Note

    The account used to run the App Pool must have access to the digital certificate that was uploaded to Salesforce in step 9 of the Salesforce Configuration section.

  5. On the General Configuration Settings screen enter the required settings and click on the Next button

    image.png

    NAMEDESCRIPTION
    Dataset IDThe two alphanumeric character dataset identifier.
    Workgroup ServerContent Manager workgroup server name. This is generally set to local
    Workgroup Server URLContent Manager workgroup server URL.
    License PathThe path to your license including the .lic file
    Temp PathThe folder Sales2CM will use to store temporary files
  6. On the Email Settings screen enter the required settings and click on the Next button

    image.png

    NAMEDESCRIPTION
    License ContactsThe email addresses that will be contacted for any license expiry notifications. Multiple contacts can be added by adding a ';' between each contact
    From AddressThe email address that all email notifications will be sent from
    Mail HostThe mail host for all email notifications to be sent
    Mail PortThe mail port used for all email notifications to be sent
  7. On the Salesforce Settings screen enter the required settings and click on the Next button

    image.png

    NAMEDESCRIPTION
    Consumer KeyThe Consumer Key of the Salesforce connected app. This is obtained in the SALESFORCE CONFIGURATION section of this guide.
    Salesforce UsernameThe username of the account that Sales2CM will use to connect to Salesforce.
    Certificate Friendly NameThe certificate friendly name of the certificate used in step 9 of SALESFORCE CONFIGURATION
    Salesforce API VersionThe version of your Salesforce API. This matches the version of the Salesforce instance. Version must be in format XX.X (e.g. 49.0)
  8. On the Custom Setup screen select the install location and click on the Next button

    image.png

  9. On the Confirm Installation window, click on the Install button

    install6.png

COMMAND LINE ARGUMENTS (OPTIONAL)​

The follow command line arguments can be passed to the MSI if required.

ARGUMENTPURPOSE
DBIDSets the Database ID that connects to Content Manager dataset to run the application
Workgroup ServerContent Manager workgroup server name. This should generally be set to local
Workgroup Server URLContent Manager workgroup server URL.
LICENSE_PATHSets the license that connects to the application
TEMP_PATHSets the temporary path that connects to the application
LIC_CONTACTSSets the license contacts for the email notifications
FROM_ADDRESSSets the from address for the email notifications
MAIL_HOSTSets the mail host for the email notifications
MAIL_PORTSets the mail port for the email notifications
CERTIFICATE_NAMEThe certificate friendly name of the certificate used in step 9 of SALESFORCE CONFIGURATION
SALESFORCE_IDThe Consumer Key of the Salesforce connected app. This is obtained in the SALESFORCE CONFIGURATION section of this guide.
SALESFORCE_USERNAMEThe username of the account that Sales2CM will use to connect to Salesforce.
API_VERSIONThe version of Salesforce instance. This is used to connect to the API
WEB_APP_POOL_IDENTITY_DOMAINSets the App Pool domain for the application pool
WEB_APP_POOL_IDENTITY_NAMESets the App Pool username for the account running the application pool. Use "" around the username if there are any special characters
WEB_APP_POOL_IDENTITY_PWDSets the App Pool password for the account running the application pool. Use "" around the username if there are any special characters

CONFIGURATION​

IIS CONFIGURATION​

  1. From the Features View go to Authentication and check that Windows Authentication is enabled. All other methods should be disabled.

    auth.png image.png

  2. Right click the application in IIS and select explore

    app.jpg

  3. Right click the app data folder and select properties

    prop.jpg

  4. Navigate to the security tab and ensure users have read, write and modify permissions.

    permiss.jpg

  5. Click on Application Pools

    image.png

  6. Within the application pool listing screen, right click on Sales2CM application pool and select the Advanced Settings option from the drop-down menu (you might have a different application name)

    image.png

  7. Within the Advanced Settings window, set Idle Time-out Action to Suspend, Idle Time-out Action (minutes) to 0 and Start Mode to Always Running click the OK button

    2021-04-26_11-52-56.jpg

  8. Select the Sales2CM app in IIS and click on Basic Settings, and set Enable Preload to true

    image.png

  9. Complete a restart of the app pool for the settings to take effect

    Note

    If you're connecting to a SANDBOX instance of Salesforce the Salesforce Sandbox option must be set to true

    image.png

CONTENT MANAGER CONFIGURATION​

The following additional fields need to be set up in Content Manager:

FIELD NAMETYPEAPPLIES TO OBJECTSAPPLIES TO
Account IdstringRecord, OrganizationRecord Type used for Salesforce Account folders
Contact IdstringPersonPerson and Organisation location types
Document IdstringStringRecord Type used for Salesforce documents
Document Version IdstringStringRecord Type used for Salesforce documents
Folder TypestringRecordAll record types being utilized by Sales2CM
Case IdstringRecordAll record types being utilized by Sales2CM
Template IdstringRecordAll record types being utilized by Sales2CM
Email IdstringRecordRecord Type used for Salesforce documents

CUSTOM OBJECTS FOR SALES2CM (OPTIONAL)​

Note

Note that the below steps are optional and only required if you intend to capture custom objects from Salesforce

In order to capture a Custom Object from Salesforce into Content Manager the Custom Object must contain a Master-Detail relationship with the Salesforce Account Object. To create a Master-Detail relationship for a Custom Object, complete the following:

  1. Click on the Cog icon, Click Setup

    image.png

  2. Click Object Manager and click on the Custom Object being used. Otherwise create the new Custom Object required

    image.png

  3. Click on Fields & Relationships

    image.png

  4. Click New

    image.png

  5. Click Lookup within the Data Type, followed by clicking Next

    image.png

  6. Select Account from the Related To dropdown and click Next

    image.png

  7. Click Next through the rest of the pages, and do not change any displayed default data.

  8. Click Save.

  9. If the Custom Object already exists, you must populate the Account on each object. If this is not completed, the Custom Field cannot be updated to a Master-Detail relationship which is required by Sales2CM.

    image.png

  10. Redirect back to the Object Manager > Fields and Relationships. Click Edit on the Account Lookup.

    image.png

  11. Click on Change Field Type

    image.png

  12. Select the Master-Detail Relationship . Click Next. Click Save

    image.png

    API Names

    Please ensure that the API name of the account is Account__c. Do not change the API name at any point. This exact name is required by Sales2CM.

CERTIFICATE BASED AUTHENTICATION​

The application utilizes a certificate-based authentication to verify its identity to Salesforce, as such you will need to register a certificate for your application in the registration portal.

You can choose to use an existing certificate if you have one otherwise you can create/purchase a new certificate for this purpose. Please follow the steps below on how to upload a certificate:

  1. After obtaining a copy of your certificate (.pfx), install the certificate-to-certificate manager under local machine on the server the application will be installed on

    sales2cmcertificate.png

  2. Ensure the certificate has been given a friendly name, this is required when installing the app to the server

  3. Please ensure the account that will be running the application pool for the application has access to the certificate private key

  4. Right-click the certificate, select All Tasks > Manage Private Keys

    manageprivatekeys.png

  5. Grant the account running the app pool full control permission on the certificate

  6. Export the public key from the certificate using the (https://docs.microsoft.com/en-us/azure/application-gateway/certificates-for-backend-authentication), you will only need to complete step 1 to 7 in the Export authentication certificate (for v1 SKU) section. NOTE: Sales2CM does not use Azure, but the steps for exporting the certificate are the same.

ADDING THE RECORD VIEW TO SALESFORCE (LIGHTNING)​

The following instructions describe how to add a Record View page to the Account object to view records related to that account. Similar steps can be taken to add a Record View page for other objects.

  1. Log in to Salesforce as your Admin account

  2. Click on the Cog button, then click on Developer Console

    dev.png

  3. Click File -> New -> Apex Class

    filenew.png

  4. Enter the name AccountController

    acccontroller.png

  5. Copy the following code into the new class: Note: \<servername\> should be replaced with the name of the server that Sales2CM is installed on. This code assumes that each folder in Content Manager that is related to a Salesforce account will have an additional field called accountId which stores the account id. The query here can be adjusted if necessary.

public class AccountController
{
private final Account acct;

public AccountController(ApexPages.StandardController stdController)
{
this.acct = (Account)stdController.getRecord();
}

public string getAddress()
{
return 'https://\<servername\>/Sales2CM/Grid?query=containerEx:[accountId:' + acct.Id + ']&pageSize=10';
}

public string getAccountNumber()
{
string accId = acct.Id;
string accountNumber;

List\<account\> result = [SELECT AccountNumber FROM Account WHERE Id = :accId LIMIT 1];

if(result.size() == 1)
{
accountNumber = result[0].AccountNumber;
}

return accountNumber;
}
}
  1. Click on File and select the Save option

  2. Click File -> New Visualforce Page

  3. Enter the name of AccountPage into the displayed window and click on the OK button

    apage.png

  4. Copy the following code into the new page:

<apex:page StandardController="Account" Extensions="AccountController" showHeader="false">
<div style="height:590px">
<apex:iframe id="theIframe" src="{!Address}" scrolling="true" height="100%"/>
</div>
</apex:page>
  1. Click on File and select the Save option

  2. In Salesforce, click the cog icon and click Setup

    setupbutton.png

  3. Click Custom Code

  4. Click Visualforce Pages and click Edit next to AccountPage

    cc.png

  5. Check the Available for Lightning Experience, Lightning Communities, and the mobile app checkbox

    light.png

    PLEASE NOTE

    If you make any changes to the page, then this checkbox will revert to being unchecked, and you will need to check it again before the page will be available for use.

  6. Click on the Save button

  7. In Salesforce, navigate to any account page

  8. Click the cog button, followed by clicking the Edit Page button

    ep.png

  9. Select the tab control in the middle of the page

    tab.png

  10. On the right of the screen, click Add Tab

    addtab.png

  11. A new tab called Details will be created

  12. Click on the new Details tab, and change the Tab Label to Custom.

    custom.png

  13. Enter the custom label Documents

    docu.png

  14. Click on theDone button

  15. Select the Documents tab

    dtab.png

  16. From the menu on the left, click and drag Visualforce to where it says Add Component(s) Here

    drag.png

  17. On the right, uncheck Show Label. Under Visualforce Page Name enter AccountPage. Under Height (in pixels) enter 600

    label.png

  18. Click on the Save button

    Save2.png

ADDING THE RECORD VIEW TO SALESFORCE (CLASSIC)​

The following instructions describe how to add a Record View page to the Account object to view records related to that account. Similar steps can be taken to add a Record View page for other objects.

  1. Log in to Salesforce as your Admin account

  2. Click on your profile, then click on Developer Console

    image.png

  3. Click on File -> New -> Apex Class

    filenew.png

  4. Enter the name AccountController

    acccontroller.png

  5. Copy the following code into the new class: Note: \<servername\> should be replaced with the name of the server that Sales2CM is installed on. This code assumes that each folder in Content Manager that is related to a Salesforce account will have an additional field called accountId which stores the account id. The query here can be adjusted if necessary.

public class AccountController
{
private final Account acct;

public AccountController(ApexPages.StandardController stdController)
{
this.acct = (Account)stdController.getRecord();
}

public string getAddress()
{
return 'https://\<servername\>/Sales2CM/Grid?query=containerEx[accountId:' + acct.Id + ']&pageSize=10';
}

public string getAccountNumber()
{
string accId = acct.Id;
string accountNumber;

List\<account\> result = [SELECT AccountNumber FROM Account WHERE Id = :accId LIMIT 1];

if(result.size() == 1)
{
accountNumber = result[0].AccountNumber;
}

return accountNumber;
}
}
  1. Click on File and select the Save option

  2. Click on File and select New Visualforce Page option

  3. Enter the name AccountPage and click on the OK button

    apage.png

  4. Copy the following code into the new page:

<apex:page StandardController="Account" Extensions="AccountController" showHeader="false">
<div style="height:590px">
<apex:iframe id="theIframe" src="{!Address}" scrolling="true" height="100%"/>
</div>
</apex:page>
  1. Click on File and select the Save option

  2. In Salesforce, click on the Setup button

    image.png

  3. Search in the left hand menu VisualForce

    image.png

  4. Click Visualforce Pages and click Edit next to AccountPage

    image.png

  5. Check the Available for Lightning Experience, Lightning Communities, and the mobile app checkbox

    light.png

    PLEASE NOTE

    If you make any changes to the page, then this checkbox will revert to being unchecked, and you will need to check it again before the page will be available for use.

  6. Click on the Save buttpm

  7. In Salesforce, navigate to any Account page

  8. Click the cog button, followed by clicking Edit Layout

    image.png

  9. Select the Fields control and add a new Section by dragging and dropping the new section into the layout.

    image.png

  10. Name the Section Documents and select Layout as 1-Column

    image.png

  11. Scroll down in the Layout Properties and click Visualforce Pages. Drag and drop the AccountPage into the Documents section

    image.png

  12. Click Properties on the AccountPage

    image.png

  13. Uncheck Show Label. Check Show Scrollbars . Under Height (in pixels) enter 600

    image.png

  14. Click on the Ok button

  15. Click on the Save button

    image.png

INSTALLING CM LAUNCHER (OPTIONAL)​

The FYB CMLauncher can be installed if required. It allows users to open documents directly from the record view in Salesforce. CMLauncher needs to be deployed to the users PC.

Please refer to the CMLauncher Installation Guide for further details.