S2T Salesforce to HP TRIM Integration -...
24
21 July 2017 Version 0.1 S2T Salesforce to HP TRIM Integration Installation Document
Transcript of S2T Salesforce to HP TRIM Integration -...
21 July 2017
Version 0.1
S2T Salesforce to HP TRIM Integration
Installation Document
S2T INS
Fuse Information Technologies Limited Page 2 of 24
Ins
tall
ati
on
Do
cu
me
nt FuseIT Contact Detai ls
Fuse Information Technologies Ltd
7 Forests Road
Stoke, Nelson
New Zealand 7011
+64 3 547 8200
+64 3 547 8209
Confidential ity
This document contains confidential and proprietary information of Fuse Information
Technologies Limited (“FuseIT”). This document was prepared for the requesting parties
(“Customer”) for the sole purpose of evaluating the products and services proposed. It is
submitted to you in confidence, on the condition that you and your representatives have, by
receiving it, agreed not to reproduce or copy it, in whole or in part, or to furn ish such
information to others, or to make any other use of it except for the evaluation purposes stated
above, and to return it to Fuse Information Technologies upon request. The previous
statement shall not apply to the extent that such statement violates any law requiring such
information to be made available to the public. In the event this document results in a
contract, you may retain this document for use, including making any necessary copies
related to the products and services covered by such cont ract. The offerings and prices
presented in this document, excluding any leasing quotes or rates, shall remain valid for a
period of 120 days from the document date unless Fuse Information Technologies authorises
an extension.
Terms and Condit ions
This document is subject to FuseIT’s standard terms and conditions which are available on
request. FuseIT reserves the right to vary the terms of this document in response to changes
to the specifications or information made available by the Customer. Submission of this
document by FuseIT in no way conveys any right, title, interest or licence in any intellectual
property rights (including but not limited to patents, copyrights, trade secrets or trademarks)
contained herein. All rights are reserved.
FuseIT does not assume liability for any errors or omissions in the content of this document or
any referenced or associated third party document, including, but not limited to, typographical
errors, inaccuracies or out-dated information. This document and all information within it are
provided on an "as is" basis without any warranties of any kind, express or implied. Any
communication required or permitted in terms of this document shall be valid and effective
only if submitted in writing.
All contracts with FuseIT will be governed by New Zealand Law and be subject to the
exclusive jurisdiction of the New Zealand courts.
S2T INS
Fuse Information Technologies Limited Page 3 of 24
Ins
talla
tion
Do
cu
me
nt
Contents
1 Introduction ................................................................................................. 5
2 S2T Installation ............................................................................................ 6
3 Support Information ................................................................................... 19
4 Troubleshooting ......................................................................................... 20
Appendix A - HP TRIM Record Management Overview ............................................. 23
List of Figures
Figure 1 – Document Direction .................................................................................. 5
Figure 2 – WSE Error ................................................................................................ 8
Figure 3 – IIS Bindings .............................................................................................. 8
Figure 4 – Certificate Issuing ..................................................................................... 9
Figure 5 – SSL Settings .......................................................................................... 10
Figure 6 – Organisation Profile ................................................................................ 11
Figure 7 – Certificates ............................................................................................. 11
Figure 8 – MMC Console ......................................................................................... 12
Figure 9 – Add/Remove Snap-In .............................................................................. 12
Figure 10 – Certificates Snap-In .............................................................................. 13
Figure 11 – Local Computer .................................................................................... 13
Figure 12 – Import Task .......................................................................................... 14
Figure 13 – Certificate Import Wizard....................................................................... 14
Figure 14 – Certificate Import Wizard....................................................................... 15
Figure 15 – Storing the Certificate ........................................................................... 15
Figure 16 – Certificate List ...................................................................................... 16
Figure 17 – Certificate Details ................................................................................. 16
Figure 18 – New Trim Record .................................................................................. 17
Figure 19 – Linked Record Details ........................................................................... 17
Figure 20 – Records Lookup .................................................................................... 18
Figure 21 – SSL Ignore Setting ................................................................................ 20
Figure 22 – TRIM Latest Part Link ........................................................................... 21
Figure 23 – TRIM Record View Pane ....................................................................... 21
Figure 24 – Salesforce Container Lookup ................................................................ 22
Figure 25 – TRIM Organizational Structure .............................................................. 23
S2T INS
Fuse Information Technologies Limited Page 4 of 24
Ins
tall
ati
on
Do
cu
me
nt
List of Tables
Table 1 – S2T Support Matrix .................................................................................. 19
S2T INS
Fuse Information Technologies Limited Page 5 of 24
Ins
talla
tion
Do
cu
me
nt
1 Introduction
This document describes how to install S2T, the Salesforce to HP TRIM integration from FuseIT. For information about using S2T please see the document, S2T_Usage_Document.pdf.
S2T is a one way integration that lets attachments and chatter documents stored in Salesforce to be manually pushed to HP TRIM. Pushed documents are, therefore, stored in both TRIM and Salesforce.
Figure 1 – Document Direction
FuseIT have two other products in this space that operate bidirectional.
• T4S is Salesforce centric and pushes documents to and from HP TRIM using TRIM web services and an intermediate Windows server. Documents can be stored in TRIM and Salesforce, or only in TRIM and referenced from Salesforce. T4S can send larger files than S2T which, because of Salesforce imposed limits to callout requests, can only send files less than 3 MB.
• TRIM4S is HP TRIM centric and pushes document links to and from Salesforce. This makes HP TRIM the single repository for documents.
The differences between products are disclosed on the FuseIT website. This document provides details of S2T only.
S2T INS
Fuse Information Technologies Limited Page 6 of 24
Ins
tall
ati
on
Do
cu
me
nt
2 S2T Installation
2.1 Installation Process
Please refer to the following link to learn how to install a Salesforce package from the AppExchange:
http://na2.salesforce.com/help/doc/en/distribution_installing_packages.htm
The S2T package is located on the Salesforce AppExchange.
2.2 Upgrade Process
To upgrade from an older version to a new version of S2T, please refer to the following link:
http://eu1.salesforce.com/help/doc/en/distribution_upgrading_packages.htm
After upgrading, any new functionality documented in the latest release of this document can be seen.
2.3 Uninstall Process
To remove the S2T package from your existing Salesforce instance, please refer to the following link:
http://na2.salesforce.com/help/doc/en/distribution_uninstalling_packages.htm
2.4 Licensing
The licensing detail is defined on the Salesforce AppExchange listing. No customisation of HP TRIM or HP TRIM web services is required.
2.5 Security
S2T has been configured to use best practice security practices:
• No user credentials are stored outside of Salesforce.
• No Salesforce credentials are used or passed outside of Salesforce.
• HP TRIM user credentials are 256bit AES encrypted and securely stored in a managed package custom setting inaccessible to users or processes outside of S2T managed code.
• The callout from Salesforce to HP TRIM is via a secure SSL Connection.
• The HP TRIM Web Service should use two-way SSL authentication.
S2T INS
Fuse Information Technologies Limited Page 7 of 24
Ins
talla
tion
Do
cu
me
nt
2.6 Interaction with HP TRIM
S2T has no interaction with HP TRIM other than establishing a session to HP TRIM Web Services. S2T will not over-write operating system commands, scripts, libraries, or data files.
2.7 Interaction with Salesforce
As a Salesforce managed package, S2T is well constructed, well tested and consumes minimal resources. S2T does not repurpose any standard Salesforce objects so has a low footprint after installing it into an existing Salesforce Org.
2.8 Assigned Users
Because S2T connects to an external web service it does not require a dedicated Salesforce user. Each Salesforce user may use their own HP TRIM credentials to synchronize with TRIM, or the Default credentials set against each HP TRIM object.
2.9 Limitations
S2T uses Salesforce callouts to interact with HP TRIM. The web service callouts are limited by Salesforce Apex Governor Limits, in particular the limit surrounding the maximum size of Apex callouts. Please see the Apex Governor Limits section at:
https://login.salesforce.com/help/doc/en/salesforce_app_limits_cheatsheet.pdf
If the limits set by Salesforce are too inhibiting, then please consider using T4S which bypasses such limits and allows for far greater operations.
2.10 HP TRIM Web Services Setup
1. IIS
If HP TRIM Web Services is not already installed, please run the installer from your TRIM install media (HPTRIM_WebService_x64.msi).
You can locate the web service as suits your requirements. It is the bindings on the site that will be used for the callout from Salesforce.
S2T INS
Fuse Information Technologies Limited Page 8 of 24
Ins
tall
ati
on
Do
cu
me
nt
2. Firewall, Salesforce IP Range
It is assumed that the HP TRIM Web Services has been installed on the target internal network. There are many possible configurations including installation in DMZ or public facing servers that require additional, highly specific routing and firewall configuration.
The port used for the HP TRIM Web Service needs to be passed through to the target internal instance. In the following example, the web service is running on a machine at 192.168.5.50.
Figure 3 – IIS Bindings
In our experience it is sufficient to allow traffic through to the web service from Salesforce IP addresses 204.14.234.8 and 182.50.78.8
3. IIS SSL
In the example above, a certificate has been purchased for trimssl.fuseit.com and installed in IIS. When port 443 is added in the bindings, the appropriate SSL certificate is selected and Require SSL is checked under SSL Settings.
4. Authenticated Web Service Callouts allow S2T to prove its Identity against
the HP TRIM Web Service
To set up your own Salesforce Certificates log into Salesforce then follow these
steps:
Note: If you receive the following error related to Microsoft WSE please download and install WSE3
Figure 2 – WSE Error
S2T INS
Fuse Information Technologies Limited Page 9 of 24
Ins
talla
tion
Do
cu
me
nt
a. Go to Setup Administrative Setup Security Controls Certificate and Key Management.
b. Click Create Self-Signed Certificate
c. Enter a name like “TrimWebService” as the label and unique name.
d. Save the new certificate.
e. Download the certificate as a .cer file for placement into your IIS server
See Section 2.12 Two-way SSL Certificate Setup for more information
5. IIS Salesforce Certificate
Use the Certificates Snap-in to the MMC to import the certificate exported from Salesforce in the previous step. (enter MMC at command prompt Add Certificates Snap In).
The certificate will say Issued By: <the name of your Salesforce organization>. If you look at the properties of the certificate, you can see that Issuer is Salesforce.
Figure 4 – Certificate Issuing
S2T INS
Fuse Information Technologies Limited Page 10 of 24
Ins
tall
ati
on
Do
cu
me
nt
6. Turn on client certificates for the web service
Figure 5 – SSL Settings
2.11 Salesforce S2T set up.
Once the S2T package has been installed into your Org, you will find two new Tabs available and which can be added to your default tab groups. The first tab to set up is the TRIM Tab.
1. From the TRIM Tab create a new TRIM object.
2. Fill in the required fields.
a. The name of this TRIM Server
b. The default Container URI (found in HP TRIM).
c. The name of the Salesforce Certificate created in the section above.
d. The HP TRIM Web Service SSL URL/IP address that S2T will use to connect with.
3. Once the new TRIM object has been saved you can enter in the default TRIM Credentials used to log into TRIM. Each User has the ability to enter their own TRIM Credentials when synchronizing TRIM Records with TRIM, If you do not wish to have default TRIM Credentials used by you Salesforce Users, then enter fake credentials that will not authenticate against TRIM.
a. On the new TRIM object page click the “Login Credentials” button.
b. Enter the TRIM Username and Password and then save.
c. For security previously entered Usernames and passwords are not displayed and will be overwritten by the new credentials.
4. Add the Remote Setting Site (S2T IP Address) to Salesforce so that the S2T callouts are permitted.
a. Go to Setup -> Administration Setup Security Controls Remote Site Settings.
b. Create a new Remote Setting with the SSL HP TRIM URL
Note: Once you activate client certificates, you may need to bump up the settings in IIS to allow the documents plus certificate to not exceed IIS buffer size. See here for more information:
http://www.fuseit.com/FuseITBlog/2013/February/Trim%20Buffer%20Size.aspx
S2T INS
Fuse Information Technologies Limited Page 11 of 24
Ins
talla
tion
Do
cu
me
nt
2.12 Two-way SSL Certificate Setup
Note: If the org is a Sandbox or Developer Org it helps to have the “Company Profile” “Company Information” named in a useful manner before the next step, so the certificate can be identified once installed.
Figure 6 – Organisation Profile
Create a new Salesforce Certificate by going to “Setup” “Administration Setup” “Certificate and Key Management” “Create Self-Signed Certificate”
Figure 7 – Certificates
Save the certificate.
Install Salesforce Two-Way SSL Certificate
During the S2T Package Install Setup you would have created a Salesforce Certificate (Refer to “Two-way SSL Certificate” in the Package Install document). Download this certificate and save somewhere on the TRIM WS Server so that it is available for installation.
On the TRIM WS Server, start a command prompt and type in “mmc” to bring up the MMC Console.
S2T INS
Fuse Information Technologies Limited Page 12 of 24
Ins
tall
ati
on
Do
cu
me
nt
Cmd mmc
Figure 8 – MMC Console
Navigate to the Add/Remove Snap-in
Figure 9 – Add/Remove Snap-In
Add the “Certificates” snap-in selecting the “Computer account”
S2T INS
Fuse Information Technologies Limited Page 13 of 24
Ins
talla
tion
Do
cu
me
nt
Figure 10 – Certificates Snap-In
Select “Local computer”
Figure 11 – Local Computer
“Finish” and “OK” the dialog box.
Under “Trusted Root Certification Authorities” select “All Tasks” “Import”
S2T INS
Fuse Information Technologies Limited Page 14 of 24
Ins
tall
ati
on
Do
cu
me
nt
Figure 12 – Import Task
Follow the wizard import to find the saved Certificate.
Figure 13 – Certificate Import Wizard
If you named your Salesforce Org Company Profile accordingly (i.e. Productio n or Sandbox etc.) then it will be easier to check to see if you have installed the correct Certificate.
S2T INS
Fuse Information Technologies Limited Page 15 of 24
Ins
talla
tion
Do
cu
me
nt
Figure 14 – Certificate Import Wizard
Figure 15 – Storing the Certificate
S2T INS
Fuse Information Technologies Limited Page 16 of 24
Ins
tall
ati
on
Do
cu
me
nt
Figure 16 – Certificate List
Open the certificate to see the Org ID and the Org Company Profile Name.
Figure 17 – Certificate Details
S2T INS
Fuse Information Technologies Limited Page 17 of 24
Ins
talla
tion
Do
cu
me
nt
Testing Two-Way SSL
Within Salesforce add the “Trim Documents” button to a s tandard object such as Opportunity.
Open an existing Opportunity click on “Trim Documents” button click on “New Trim Record” button.
Figure 18 – New Trim Record
Click “Create Linked Record” button to bring up the New Linked Record page, then finally “Record Search”
Figure 19 – Linked Record Details
From this page you can make a TRIM Record search calling S2T web service.
S2T INS
Fuse Information Technologies Limited Page 18 of 24
Ins
tall
ati
on
Do
cu
me
nt
Figure 20 – Records Lookup
See the Troubleshooting Section if error message appears.
S2T INS
Fuse Information Technologies Limited Page 19 of 24
Ins
talla
tion
Do
cu
me
nt
3 Support Information
3.1 Support Matrix
The following support matrix specifies the environment required for S2T.
System Detail Supported
Infrastructure Cloud based Force.com Required
S2T Host Environment Salesforce.com Required
S2T Operating System Not applicable
S2T Database Not applicable
Internet Browser IE 6+ Yes
Firefox 3.5+ Yes
Chrome Yes
Safari 4+ Yes
Opera 9+ Yes
HP Software Integration HP TRIM Web Services Version 7.02 Yes
Table 1 – S2T Support Matrix
3.2 Support Contacts
Please email the following contacts for more information about S2T or any other HP TRIM product from FuseIT:
• Terry Humphris: [email protected]
• William Boyd: [email protected]
S2T INS
Fuse Information Technologies Limited Page 20 of 24
Ins
tall
ati
on
Do
cu
me
nt
4 Troubleshooting
4.1 IIS SSL Setup
Any TRIM WS web server errors will be displayed as Error messages above the grid.
If the connection is not working, first try turning off the “Require” Client certificates within IIS, applying the change to the TRIM WS site, and try again. This can help determine if there is a general issue connecting to S2T under your standard SSL setup, or there is an issue with the Salesforce Certificate.
Figure 21 – SSL Ignore Setting
Finding the Default URI
You can use the TRIM Web Client by finding the Container or Record and clicking on the “Latest Part” link within the Properties pane.
S2T INS
Fuse Information Technologies Limited Page 21 of 24
Ins
talla
tion
Do
cu
me
nt
Figure 22 – TRIM Latest Part Link
Use TRIM Desktop Client by right clicking on the Record View Pane, and adding the custom field “Unique Identifier” to the list of displayed fields.
Figure 23 – TRIM Record View Pane
Once Salesforce and S2T have been setup, you can use the Container Search feature to easily find any Container URI
S2T INS
Fuse Information Technologies Limited Page 22 of 24
Ins
tall
ati
on
Do
cu
me
nt
Figure 24 – Salesforce Container Lookup
S2T INS
Fuse Information Technologies Limited Page 23 of 24
Ins
talla
tion
Do
cu
me
nt
Appendix A - HP TRIM Record Management Overview
Records management best practices dictates information should be placed into a shallow container structure (one level deep). This completely eliminates nested containers, like that of a computers file system so alternative systems are required. HP TRIM is one such system.
To ensure files are stored so they can be easily found, while still maintaining best practices, HP TRIM uses concepts such as classifications that can be applied to substitute for a nested structure. The following diagram shows the organizational items in TRIM.
Figure 25 – TRIM Organizational Structure
Location (assignee) is the top level structure and has one of the following location types:
• Group
• Organization
• Position Person
• Project Team
• Committee
• Venue
• Work Group
S2T INS
Fuse Information Technologies Limited Page 24 of 24
Ins
tall
ati
on
Do
cu
me
nt
Locations must have a:
• Name
• Location Type
Container is a record with record type equal to File Folder. It must contain records to be a container otherwise it is just a file folder.
Record is metadata about a record. The record type is typically Document, Standard Document, or File Folder (which are called Containers if they contain records). Records must have an:
• Assignee e.g. Boyd, William
• Record Number e.g. D12/40
• URI e.g. uri:1434
• Title e.g. Test Record
• Record Type e.g. SF Document
Document: Electronic binary information or physical object which is the actual evidence or article.
