0% found this document useful (0 votes)

52 views

File Net Salesforce Connector Installation Guide

Uploaded by

omid amini

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

52 views

File Net Salesforce Connector Installation Guide

Uploaded by

omid amini

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 38

IBM FileNet Content Manager

FileNet Salesforce Connector

Configuration Guide

Version 5.6.1
Copyright

Before you use this information and the product it supports, read the information in "Notices"
on page 33.

© Copyright International Business Machines Corporation 2020.

US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP
Schedule Contract with IBM Corp.

© Copyright International Business Machines Corporation 2020 2

Contents
Copyright .............................................................................................................................. 2

Overview ............................................................................................................................... 5

Preparing the Content Platform Engine environment ............................................................. 6

Deploying the Content Services GraphQL API .................................................................................6
CORS.xml ......................................................................................................................................6
Authentication..............................................................................................................................8
Installing the Salesforce Integration Extensions Add-On ................................................................8
Setting permissions on document classes for use in Salesforce .....................................................9
Editing document class security ...................................................................................................9
Editing the document class Default Instance Owner ................................................................ 10
Editing the document class default instance security .............................................................. 11
Configuring properties to be synchronized with fields on Salesforce records ............................. 13

Preparing the Salesforce Organization ................................................................................. 15

Installing the FileNet Salesforce Connector app in a Salesforce Organization ............................. 15
Configuring Salesforce after installation....................................................................................... 15
Creating a CSP Trusted Site for the Salesforce Organization .................................................... 15
SSL Certificate requirement on the Content Services GraphQL server .................................... 16
Configuring Salesforce to allow Resource Sharing (CORS) with the Content Platform Engine
server......................................................................................................................................... 16
Configuring Authentication to the IBM Content Services GraphQL API Service ...................... 16
Configuring Salesforce users who have administrator access for the Connector .................... 17
Configuring Salesforce users who have non-admin access to IBM FileNet documents ........... 17

Configuring the Salesforce Organization to use object stores ................................................ 19

Configuring an object store .......................................................................................................... 19
Adding the Documents List widget to your Salesforce Organization screens .............................. 20
Assigning Licenses for the IBM FileNet Salesforce Connector Package ....................................... 21
Removing an object store ............................................................................................................. 21

Configuring OAuth authentication ....................................................................................... 22

Configuring OAuth authentication in Salesforce .......................................................................... 22
Generating a new self-signed certificate .................................................................................. 23
Creating a connected app ......................................................................................................... 23
Configuring Salesforce users who can use the Connected App to authenticate...................... 25
Creating a Named Credential .................................................................................................... 26
Configuring OAuth authentication on the Content Services server ............................................. 28
Installing the Salesforce SSL certificate on Content Services server ........................................ 28
Creating the Open ID Connect client configuration file ............................................................ 29

© Copyright International Business Machines Corporation 2020 3

Configuring basic authentication .......................................................................................... 31
Configuring a Salesforce Named Credential for the FileNet server.............................................. 31
Configuring Salesforce users who can use the Named Credential to authenticate ..................... 31
Configuring IBM FileNet Salesforce Connector authentication – per user .................................. 32

Uninstalling the IBM FileNet Salesforce Connector app ........................................................ 34

Notices ................................................................................................................................ 35

Trademarks ......................................................................................................................... 38

© Copyright International Business Machines Corporation 2020 4

Overview

The IBM FileNet Salesforce Connector App enables Salesforce users to store their attachments
as documents in their organization’s FileNet Content Manager object store instead of storing
the documents in Salesforce.

This document outlines the steps needed to prepare the environment on the FileNet side, as
well as the steps to configure the app on the Salesforce side.

The IBM FileNet Content Services GraphQL API provides the connection between the IBM
FileNet Connector for Salesforce app and the IBM FileNet Content Engine server. The following
graphic describes this connection:

The FileNet Salesforce Connector App connects to the IBM FileNet Content Services GraphQL
API through a secure HTTPS connection. The GraphQL API then makes calls to the Content
Platform Engine server through the Content Engine Java API to interact with Documents and
with SalesforceRelationship objects that associate Documents with Salesforce records.

In addition to the GraphQL API configuration, you also prepare the Content Platform Engine
object store and configure permissions for the content.

On the Salesforce side, you install and configure the FileNet Salesforce Connector App, then
make updates to your Salesforce views to make the object store content visible and available to
Salesforce users. You also configure authentication to control access to your content.

© Copyright International Business Machines Corporation 2020 5

Preparing the Content Platform Engine environment

To prepare the Content Platform Engine for integration with the FileNet Salesforce Connector
App, you must deploy and configure the Content Services GraphQL API, prepare the object
store, and assign appropriate permissions to the document classes.

Deploying the Content Services GraphQL API

The Salesforce app uses the Content Services GraphQL API to connect to the Content Platform
Engine. The connection requires the GraphQL API to be accessible from the public internet. As a
result, the GraphQL API cannot be behind a firewall or VPN.

To deploy and configure the IBM FileNet Content Services GraphQL API, follow the instructions
in the following Knowledge Center topic:

https://www.ibm.com/support/knowledgecenter/SSNW2F_5.5.0/com.ibm.p8.containers.doc/c
ontainers_graphql.htm

Note the following configuration requirements that are specific for use of the GraphQL API with
the FileNet Salesforce Connector App:

CORS.xml

By default, the IBM Content Services GraphQL service will not trust calls coming from
Salesforce. To allow the GraphQL service to trust incoming calls from Salesforce.com, and to
allow Salesforce web pages to trust data coming from the Content Services GraphQL service, a
Cross Origin Resource Sharing (CORS) configuration must be established between the two
services. Configuring Salesforce to allow Resource Sharing (CORS) with the Content Platform
Engine server, in this document, describes CORS settings that are required on the Salesforce
side. This section describes the CORS settings required on the IBM Content Services GraphQL
Service side.

The IBM Content Services GraphQL service allows the following CORS options to be set to
control access by external web sites:
• Allowed HTTP methods
• Allowed HTTP Request Headers
• Allowed HTTP Response Headers
• Allow Credential
• Max Age

© Copyright International Business Machines Corporation 2020 6

To allow calls from Salesforce.com, you must create a cors.xml file, and place it in the
${server-config-dir}/configDropins/overrides directory of your WebSphere Liberty
server, to allow calls from your Salesforce Organization’s domain URL. The file should contain
the following:

<?xml version='1.0' encoding='UTF-8'?>

<server>

<cors domain="/content-services-graphql"
allowedOrigins="https://<Salesforce_Org_URL>"
allowedMethods="GET, POST, OPTIONS"
allowedHeaders="Connection,Pragma,Cache-Control,XSRFtoken,Origin,User-
Agent,Content-Type,Content-Length,Accept-Control-Request-Method,Accept-Control-
Request-Headers,Accept,Referer,Accept-Encoding,Accept-Language,DNT,Host,Content-
Length,Cache-control,Cookie,Authorization"
exposeHeaders="Content-Disposition,Content-Length,Content_Type,Content-
Language,X-Powered-By,Date,Allow,Transfer-Encoding,$WSEP,DNT,Access-Control-Allow-
Credentials,Access-Control-Allow-Headers,Access-Control-Allow-Max-Age,Access-Control-
Allow-Methods,Access-Control-Allow-Origin,Access-Control-Expose-
Headers,Connection,Cache-control,Cookie,x-content-download"
allowCredentials="true"
maxAge="3600" />
</server>

You must replace the <Salesforce_Org_URL> placeholder text above with your Salesforce
Organization's instance domain URL (without any context root). In the following example, the
domain URL is:
test-demo-dev3.lightning.force.com

© Copyright International Business Machines Corporation 2020 7

Authentication

When you deploy the Content Services GraphQL API, it is recommended that you initially
configure Basic Authorization to get the connector app working as part of a test or
development environment.

However, for production environments it is recommended to use OAuth for authentication.

Important:

Configuring the FileNet Connector for Salesforce app to use OAuth requires that your IBM
FileNet Content Manager users use the same name to authenticate as the corresponding
Salesforce user (for example, [email protected]). If the same names are used in
both places, then the Content Services GraphQL server can be configured to trust the
OAuth/OIDC tokens that are generated by Salesforce.

See the instructions in the Advanced Authentication section of the Content Services GraphQL
API documentation for details of the Content Platform Engine side of this configuration.

Installing the Salesforce Integration Extensions Add-On

The Salesforce integration requires that you install a custom feature AddOn in each Object
Store that is exposed to Salesforce. This AddOn defines Content Engine classes and properties
that are used by the Salesforce app to associate Content Engine documents to Salesforce
objects.

You download the add-on extension files, register the add-on with the server, then install the
add-on. Perform these configuration steps as a P8admin in the Administration Console for
Content Platform Engine.

To enable the add-on:

1. Download the following IBM Salesforce Integration Extensions AddOn files from this
GitHub location:

FNCE_SalesforceIntegrationAddOn.desc
SalesforceIntegrationExtensions.xml
SalesforceIntegrationPostImportScript.js

2. Copy the files into a single directory on the server where you can access the IBM
Administration Console for Content Platform Engine.

© Copyright International Business Machines Corporation 2020 8

3. Start the New Add-On wizard in the administration console:
a. In the domain navigation pane, navigate to Global Configuration > Data Design >
Add-ons.
b. Right-click the Add-ons node and click New Add-On.
4. Use the following values in the wizard:
Select Use the descriptor method.
Add-on descriptor file: Browse to FNCE_SalesforceIntegrationAddOn.desc.
In the Create the Add-on dialog box: select Optional.
Import data set: SalesforceIntegrationExtensions.xml
Post-import script: SalesforceIntegrationPostImportScript.js
For the remaining fields, accept default settings.
5. Click Finish to complete the wizard.
6. In the domain navigation pane of the Administration Console for Content Platform
Engine, click the object store that you want to use with the app.
7. In the object store navigation pane, click the name of the object store (the top-level
item).
8. From the Actions menu in the object store tab, click Install Add-On Features.
9. Select the SaleforceIntegrationAddOn, and click OK.

Setting permissions on document classes for use in Salesforce

When you configure a Salesforce organization to access an IBM FileNet object store through the
app, you select a set of document classes to be available to your Salesforce users for creating
new documents. The settings in these document classes influence the permissions that
Salesforce users have on documents that are exposed through the app. You determine what
access different users should have to documents through the Salesforce app by configuring
permissions on your doc classes via the Administration Console for Content Platform Engine.

Although not required, it is recommended to create a new set of classes in your object store for
your Salesforce documents. You can then set permission on these classes as described in the
next section without any impact to other document classes that you might already have in your
object store.

Editing document class security

There is one Document Class security permission that will impact Salesforce users: Create
Instance permission.

© Copyright International Business Machines Corporation 2020 9

The Document Class Security tab in the Administration Console for Content Platform Engine
shows the default permission settings for a Content Engine document class. To be usable by
end users, the document class should grant View All Properties, Read Permissions, and Create
Instance permission to all users. Only users with Create Instance permission on a Document
class are able to create a document of that class.

If your document class uses this default setting to grant these three permissions to
#AUTHENTICATED_USERS, then nothing further needs to be done in the Document Class
permission settings. However, if you are not granting these permissions to
#AUTHENTICATED_USERS, then create a group containing all of your Salesforce users, and use
the Administration Console for Content Platform Engine to add a permission to each document
class that will be exposed in Salesforce, granting these permissions to the Salesforce user’s
group.

Editing the document class Default Instance Owner

The owner of a document gets implicit permissions on the document, including the ability to
read, view, edit, and change permissions. Therefore, the owner of a document can always
view and edit the document through the Salesforce application.

The Default Instance Owner property of a document class determines who the default owner
will be for a new document of the document class. FileNet applications (including the

© Copyright International Business Machines Corporation 2020 10

Salesforce app) typically rely on this document class setting to control who the owner of new
documents will be.

The Default Instance Owner of a document class can be viewed and edited in the
Administration Console for Content Platform Engine by scrolling to the bottom of the Default
Instance Security tab:

For document classes that are exposed in Salesforce, the default setting of #CREATOR_OWNER
should be maintained for the Default Instance Owner property. This setting means that the
person who creates a document is always it’s owner.

Editing the document class default instance security

The permissions on documents created by the IBM FileNet Salesforce Connector app are
determined by the Default Instance Security settings on the exposed document classes. The
following screenshot shows an example of the Default Instance Security for a document class:

Configuring users who can view existing documents and their properties

In the example above, the #AUTHENTICATED_USERS pseudo-group (which represents all users
who are able to login to the server) is granted the View Content security group. This security
group includes the following permissions: View all properties, View content, Read permissions.

© Copyright International Business Machines Corporation 2020 11

These permissions allow users to view document content and properties from the Salesforce
app, but not the ability to edit document properties or create new versions of a document.

When an object store is created, one or more user groups can be specified as object store
users. If such a group is specified at object store creation time, then they will be given the View
content access group for all document classes by default. If no such group is specified at object
store creation time, then #AUTHENTICATED_USERS is granted the View Content access group
for all document classes by default.

Customers may edit the Default Instance Security settings to limit access to smaller groups, or
to remove all access, and instead use security mechanisms other than Default Instance Security
to control document permissions.

For the Salesforce environment, we recommend that Default Instance Security should grant
View Content either to #AUTHENTICATED_USERS, or to a group that will contain users who
should have read-only access to all Salesforce documents.

Note that if a user has only View Content permission, then they will be able to edit properties
and content for documents that they create, but not for documents that were created by any
other user.

Configuring users who can edit properties or create new versions of existing documents

In the example above, the intg_admin group is granted the Major Versioning permission group.
This security group includes permissions to modify properties or create new versions, in
addition to the permissions that the View Content group has. Users who should be allowed edit
documents that were created by other Salesforce users should be given this permission.

If a customer wanted to grant permission to edit document properties, but not permission to
create new document versions, then the group should be granted the Modify Properties
permission group, rather than the Major Versioning permission group.

For the Salesforce environment, we recommend that Default Instance Security should grant
Major Versioning permission to either some or all Salesforce users, by assigning this permission
group to a group that contains these users (or to #AUTHENTICATED_USERS).

© Copyright International Business Machines Corporation 2020 12

Configuring users who can remove documents from a Salesforce organization

In the example above, the #CREATOR_OWNER pseudo-user, and as the CEAdminGroup, have
both been granted the Full Control permission group. These permissions allow the grantees to
view and edit the documents, as well as to remove them from the Salesforce record.

For the Salesforce environment, we recommend that Default Instance Security should grant Full
Control permission to a group who are admins within Salesforce, as well as to the
#CREATOR_OWNER pseudo-user.

Configuring properties to be synchronized with fields on Salesforce records

Whether you create new document classes for use by the Salesforce Connector, or chose to use
existing document classes, you have some options for which properties on your classes are
visible and settable in Salesforce. You also have the option to create some new properties to
hold copies of Salesforce fields from the Salesforce records where you have added FileNet
document attachments.

You can create special properties on your document class that are automatically populated with
values from the Salesforce record that a document is added from. When creating a new
document, the IBM FileNet Salesforce Connector automatically looks for any properties on the
target document class whose symbolic name begins with the prefix “Fnsf”. If any properties
with this prefix are found, then the Connector attempts to find a Salesforce field with a
matching name, and then populates the FileNet property with the value from that field during
document creation.

For example, if the Salesforce record where a document is being added has a field whose name
is “AccountName”, and a property exists on the target document class with the symbolic name
“FnsfAccountName”, then that property is automatically populated with the value of the
“AccountName” field.

When you configure an object store in Salesforce, you can select the document classes that are
exposed to Salesforce users, and select which document properties of those classes Salesforce
users can set the values for when they create a new FileNet document through Salesforce. If a
property with an “Fnsf” prefix in its symbolic name is selected, then it appears on the New
Document dialog of the Document List View widget as read-only. The user cannot override the
value from the Salesforce record.

If you want to store a copy of the entire Salesforce record in your FileNet object store, you can
do that by creating a property with the symbolic name “FnsfJSONRecord” in your target

© Copyright International Business Machines Corporation 2020 13

document class. If this property exists, then the JSON for the Salesforce record is copied into it
when a document is added to the record through the IBM FileNet Salesforce Connector. Note
that this property must be a string property, with the UsesLongColumn flag set to true, because
this data can be moderately large.

Note that there are some limitations of this field synchronization feature:
• The property on the FileNet document has the value of the Salesforce field at the point
in time when the document is first added as an attachment on the Salesforce record. If
the value of the Salesforce field is subsequently updated, the value of the property on
the FileNet document is not updated.
• If the document is later added to additional Salesforce records through the Add To
Record feature, it is not updated with field values from the new record.
• Only fields that are of string, date, or integer value can be synchronized through this
feature. The data type of the Salesforce field must match the data type of the FileNet
property, or the synchronization does not work
• If the length of the Salesforce string exceeds the length of the corresponding FileNet
property, then the string is truncated to fit in the FileNet property

© Copyright International Business Machines Corporation 2020 14

Preparing the Salesforce Organization

A Salesforce administrator user must install and configure the IBM FileNet Salesforce Connector
app with a Salesforce Organization.

Note that you must accept the license agreement for the Salesforce Connector application
before the app can be installed. The specific terms and conditions for this application are
available in the installation wizard, and also on the AppExchange listing page. License terms for
the prerequisite products are accepted during the purchasing of those products.

Installing the FileNet Salesforce Connector app in a Salesforce Organization

To install the FileNet Salesforce Connector app:

1. From the Salesforce Organization, click the AppExchange link.
2. Browse for and select the FileNet Salesforce Connector app.
3. Supply values for the AppExchange installation wizard. When asked, choose Install for
Admin Users only.
4. Click Install now to complete the wizard.

It can take a few minutes for the installation to complete.

Configuring Salesforce after installation

After you install the app in the Salesforce organization, you must do additional configuration in
Salesforce to make the app features available for users.

Creating a CSP Trusted Site for the Salesforce Organization

You must create a CSP Trusted Site in the Salesforce Organization so that the IBM FileNet
Salesforce Connector can work securely with the Content Services GraphQL server.

To create the CSP Trusted Site:

1. From Setup, use the Quick Find field to find CSP Trusted Sites.
2. From CSP Trusted Sites, click New Trusted Site
3. For Trusted Site Name, enter IBM_Content_Services_Endpoint.
4. For Trusted Site URL, enter the URL for the IBM Content Services GraphQL API.
5. Select the Active checkbox.
6. For Context, select the All option (default).

© Copyright International Business Machines Corporation 2020 15

7. Click Save.

See the following Salesforce documentation for more details:

https://help.salesforce.com/articleView?id=csp_trusted_sites.htm&type=5

SSL Certificate requirement on the Content Services GraphQL server

When IBM FileNet Salesforce Connector App sends an outbound message to the Content
Services GraphQL server, using a CSP Trusted Site, the Salesforce.com organization acts a client
that will only trust the target host (that is the Content Service GraphQL server) if it presents an
SSL Certificate signed by a root Certification Authority (CA). Self-signed certificates cannot be
used by the target host. Also the target host URL must be specified using a registered DNS
domain name, matching the domain name in. the SSL certificate; the target host URL cannot be
specified using it’s public IP address.

Configuring Salesforce to allow Resource Sharing (CORS) with the Content

Platform Engine server

By default, browsers do not allow a request to one web site to retrieve many types or resources
from a different web site. Cross Origin Resource Sharing (CORS) is a standard that allows a
primary web site to request access to resources from a secondary web site, and for the
secondary web site to be configured to allow this access. The IBM FileNet Connector for
Salesforce requires CORS access to be configured on both the Salesforce Organization, and on
the IBM Content Services GraphQL API service.

To configure CORS within Salesforce, the Salesforce admin must add a trusted domain to the
Salesforce organization’s CORS whitelist.

To configure resource sharing:

1. From Setup, use the Quick Find field to find CORS.
2. Click New.
3. For Origin URL Pattern, enter the domain of the IBM Content Services GraphQL API.
4. Click Save.

Configuring Authentication to the IBM Content Services GraphQL API Service

Salesforce supports following authentication protocols:

• User Password
• OAuth 2.0
• OAuth 2.0 JSON Web Token (JWT)

© Copyright International Business Machines Corporation 2020 16

• JWT Token Exchange
• AWS Signature Version 4

IBM FileNet Salesforce Connector App supports User Password (aka BasicAuth) and OAuth 2.0
JSON Web Token (JWT). Both protocols requires creating a NamedCredential and completing a
set of additional configuration steps.

To configure the app to use OAuth authentication, see the instructions in section 5 of this
document. To configure the app for BasicAuth authentication, see the instructions in section 6
of this document.

Configuring Salesforce users who have administrator access for the Connector

When the IBM FileNet Connector for Salesforce is installed, it creates two Permission Sets,
which control which users have which access levels within the connector. The first of these is
the IBM FileNet Admin Permission Set

Only administrative users should have access to sync an IBM FileNet Content Manager object
store with a Salesforce organization, or to configure which properties are editable in the
document properties dialog. To grant Salesforce users this access, they must be added to the
IBM FileNet Admin Permission Set.

To configure admin users:

1. In the Setup menu, go to Users in the Administration, and select Permission Sets.
2. Select the IBM FileNet Admin permission set.
3. Click Manage Assignments on the permission set screen.
4. Select the user or users that you want to add to the permission set, or unselect users
that you would like to remove from the permission set, and click Assign.
5. Click Save to save your changes.

Configuring Salesforce users who have non-admin access to IBM FileNet

documents

The second Permission Set that is created during the installation is the IBM FileNet User
Permission Set. All users who need runtime access to retrieve, create, or update documents
through the IBM FileNet Salesforce Connector must be added to the IBM FileNet User
Permission Set.

To add non-administrator users:

1. In the Setup menu, go to Users in the Administration, and select Permission Sets.

© Copyright International Business Machines Corporation 2020 17

2. Select the IBM FileNet User permission set.
3. Click Manage Assignments on the permission set screen.
4. Select the user or users that you want to add to the permission set, or unselect users
that you would like to remove from the permission set, and click Assign.
5. Click Save to save your changes.

© Copyright International Business Machines Corporation 2020 18

Configuring the Salesforce Organization to use object stores

Once the IBM FileNet Salesforce Connector app has been installed and all of the post-install
configuration steps are complete, you are ready to configure an object store for use in your
Salesforce organization. Multiple object stores can be configured with a single organization if
you choose.

For each object store that is configured, the admin chooses the document classes to be
available for Salesforce users to store documents. Additionally, for each document class that is
selected, the admin can select the subset of properties that a user can set when they create a
new document or update existing documents.

You must be a member of the IBM FileNet Admin Permission Set to perform any of the actions
in this section.

Configuring an object store

You use the Connector app to choose an object store and select the Document classes and
associated properties that you want to use for your application.

To configure an object store:

1. Use the App Launcher to navigate to the IBM FileNet Salesforce Connector tab.
2. Select the Configuration menu option.
3. From the drop-down list of object stores, select the object store that you want to
configure.
4. From the list of available document classes for the object store you that selected, use
the checkboxes to select or unselect classes.
5. For each document class that you select, use the Select Properties link next to the class
to configure the properties to make editable for that class. In the Properties to Display
dialog, you can select the properties to display from the list of available properties, and
you can also use the up and down arrows to adjust the order in which the properties are
displayed.
An asterisk (*) before the property name indicates that the property is automatically
populated from the corresponding Salesforce field. This auto-population occurs whether
or not you select it as a property to display. If you do select it as a property to display,
then it appears as a read-only property in the document properties dialog.
6. When you have completed setting up your document classes and properties, click Save
to save your choices.

© Copyright International Business Machines Corporation 2020 19

If you get an error when you attempt to configure an object store that says that the Salesforce
Integration Extensions AddOn has not been installed, refer to the instructions in Installing the
Salesforce Integration Extensions Add-On.

Note that the Configure object store action can be run multiple times for an object store, to
change the selected document classes, or to change the list of fields that are selected for a
given class. After an object store has been configured once, the Reconfigure button can be
used to configure it again.

After you configure an object store, you add a Document List widget to the relevant Salesforce
pages to make the object store visible to end users.

Adding the Documents List widget to your Salesforce Organization screens

Note: Only a Salesforce system administrator can modify a page layout, as described in this
section. The edit page link is not visible to a standard user.

For each configured object store, you must add the IBM Documents List Widget to the pages
where you want IBM FileNet documents to be accessible. The widget can be added to any
Salesforce page, including pages for custom Salesforce record types. The follow steps use the
Account page as an example.

To add the Documents List widget to a page:

1. Go to the App Launcher, and start the IBM FileNet Salesforce Connector app.
2. Click the Accounts tab.
3. Select an individual account, and go to the Related tab. The IBM Documents widget is
not visible.
4. From the Setup menu, select Edit page.
5. From the Lightning Components bar, under Custom > Managed menu, select the
DocumentsList component and drag and drop it to your desired location on the Related
Items tab.
6. Make this component visible to users that have permission to access the component:
a. Click Add Filter.
b. Click the Advanced tab, click Select, and from the Type of filter list, click
Permission.
c. From the Permissions drop down menu, select Custom permissions.
d. From Custom permissions, select IBM_FileNet_User_Document_List.
e. Click Done.
f. From Filter Type dialog, make sure that the operator is Equal, and Value is True,
then click Done.

© Copyright International Business Machines Corporation 2020 20

7. Click Save to save the edited layout
8. To activate these changes, click Activation. Click Assign as Org Default, then click Save.
9. Click Back to return to the main screen.

Repeat the steps for other Salesforce pages, as needed.

Assigning Licenses for the IBM FileNet Salesforce Connector Package

To assign licenses to Salesforce AppExchange users:
1. From Setup, enter Installed Packages in the Quick Find box, then select Installed
Packages to find the IBM FileNet Salesforce Connector package.
2. Click the Manage Licenses link before the package name.
3. Click Add Users.
4. Click the checkbox in the Available users section to select users
5. Click Add in Selected Users.

Removing an object store

If you want to disassociate an object store from a Salesforce organization, you can do so by
selecting the object store in the Configure Object Store tab, and then using the Remove
button.

This action prevents any new documents from being added to this object store, as well as the
listing or viewing of any existing documents. It does not, however, remove the Document List
widget for the Object Store from the Salesforce pages where it is in use. The Document List
widgets will show an error when pages that contain the widget are viewed.

If you use the Remove button to remove an object store association, and you then re-configure
the object store, then all of the documents will come back. If you do not intend to immediately
re-configure the object store, then you should manually remove the Document List widget from
all Salesforce pages prior to performing the Remove operation.

© Copyright International Business Machines Corporation 2020 21

Configuring OAuth authentication

You can configure the IBM FileNet Salesforce Connector app to authenticate to the IBM
Content Services GraphQL server by using the OAuth 2.0 protocol.

Configuring OAuth authentication in Salesforce

The IBM FileNet Connector for Salesforce app references a Salesforce Named Credential when
it accesses the IBM Content Services GraphQL server. The Named Credential is configured to
perform all of the necessary authentication steps when a connection from Salesforce to the
IBM Content Services GraphQL server is made.

Named Credential
A Named Credential is a configuration that declaratively manages a Salesforce Organization’s
authentication to an external service. The credential specifies the URL of the external service
and its authentication parameters. The connection between Salesforce and the external service
is established using the Authentication Protocol parameter in a Named Credential.

OAuth 2.0 JSON Web Token (JWT)

OAuth 2.0 is an open standard which allows simple and powerful server-to-server API
integration. The main advantage of using the OAuth 2.0 protocol over the User Password
protocol is that Salesforce users do not need to manage their own credentials for the external
system.

The OAuth 2.0 JWT is an OAuth flow, similar to Web Server flow within OAuth 2.0, which uses a
JWT format of the OAuth access token. With this flow, Salesforce creates a token using the
logged on user’s identity, and digitally signs the token using a private key. Whenever the IBM
FileNet Salesforce Connector App makes a callout to IBM Content Services server, Salesforce
sets this token in the Authorization header of the HTTP Request object.

The value of the Authorization header looks like the following:

Authorization: Bearer eyJraWQiOiJTY...eyJpc3MiO...FEjHNzZ...

IBM FileNet Content Services server parses the token and verifies the signature using the SSL
Certificate stored in server's KeyStore. The server also checks the expiration time in the token.
An error response is returned if signature verification fails or token is already expired.

To configure OAuth 2.0 JWT:

1. Generate a new Self-Signed or CA Signed certificate.
2. Create a Connected App.
3. Create a Named Credential.

© Copyright International Business Machines Corporation 2020 22

Generating a new self-signed certificate
You use Salesforce to generate the new certificate.

To generate a new self-signed certificate:

1. From Setup, enter Certificate in the Quick Find Box, then select Certificate and Key
Management.
2. Click Create Self-Signed Certificate.
3. Enter the following fields:
• Label: IBMFileNetCertificate
• Unique Name: IBMFileNetCertificate
4. Click Exportable Private Key.
5. Click Save.
6. Click Download Certificate.

The certificate is downloaded to your system. Make a note of the location so you can use this
certificate in a later configuration procedure.

Creating a connected app

You use Salesforce to create a connected app.

To create a connected app:

1. From Setup, enter App Manager in the Quick Find Box, then select App Manager.
2. Click New Connected App.
3. Enter the following fields:
• Connected App Name: IBM FileNet Salesforce Connected App

© Copyright International Business Machines Corporation 2020 23

• App Name: IBM_FileNet_Salesforce_Connected_App
• Contact Email: Enter your e-mail address
4. In the API (Enable OAuth Settings) section, click Enable OAuth Settings.
5. In Callback URL, enter the IBM Content Services redirect URL, for example,
https://cpe-cmis-dev.ibmbrsandbox.com:9444/oidcclient/redirect/IbmContentServices

You can change the callback URL at later time. If you don’t know the URL when creating
the Connected App, you can enter a placeholder URL, and change it at a later date.
6. Select Use digital signature, click Choose File, and select the certificate that you
downloaded to your system in Generating a new self-signed certificate.
7. From Available OAuth Scopes, add the following to Selected OAuth Scopes:
• Access your basic information (id, profile, email, address phone)
• Allow access to your unique identifier (openid)
• Perform requests on your behalf at any time (refresh_token, offline_access)
8. Check Require Secret for Web Server Flow.

9. Confirm all fields and click Save.

10. On the Salesforce status message, click Continue.
11. From the IBM FileNet Salesforce Connected App page, in the API (Enable OAuth
Settings) section, copy the value for the Consumer Key in the text editor. You will use
this value in Creating a Named Credential.

© Copyright International Business Machines Corporation 2020 24

The screenshot below shows an example of the Connected App details:

Configuring Salesforce users who can use the Connected App to authenticate

When using OAuth, users must reference the IBM FileNet Salesforce Connected App
Connected App directly from their profiles. This approach requires that they have access to the
Connected App. There are two options to complete this step, depending on whether you want
all users to be able to use the connector, or only certain users.

Option 1: Allow access for all users in the Salesforce Organization (Recommended)

If you want all Salesforce users within an organization to have non-administrative access to the
IBM FileNet Salesforce connector, add the Connected App that was created in a previous step
to the Standard Profile for the organization (or the user profile of your choice).

1. In Setup, go to Profiles.
2. Select the Standard User profile (or the user profile of your choice).
3. Click Assign Connected Apps.
4. Click Edit for Assign Connected Apps.
5. Add the IBM FileNet Salesforce Connected App to the list of Enabled Connected Apps.
6. Click Save.

Option 2: Allow access for a subset of Salesforce Organization users

© Copyright International Business Machines Corporation 2020 25

If you only want a subset of your users to have access, then you must create a third Permission
Set in addition to the two that were created automatically when the app was installed. Use the
following steps to configure this access.

1. In the Setup menu, go to Administration > Users, and select Permission Sets.
2. Click New to create a new Permission Set
3. For Label, enter IBM FileNet Connected App
4. For API Name, enter IBM_FileNet_Connected_App
5. Leave the Session Activation Required checkbox unchecked.
6. Leave the License dropdown set to Salesforce
7. Click Save to save the Permission Set.
8. In the Apps section for the Permission Set that you just created, click on Assigned
Connected Apps.
9. Click Edit.
10. In the Installed Connected Apps list, select the IBM FileNet Salesforce Connected App
Named Credential and move it to the Enabled Connected Apps list.
11. Click Save to save your changes.
12. On the Permission set screen, click Manage Assignments.
13. Select the user or users that you want to add to the permission set (or unselect users who
you would like to remove from the permission set), and click Assign.
14. Click Save to save your changes.

Creating a Named Credential

You use Salesforce to create a Named Credential.

1. From Setup, enter Named in the Quick Find Box, then select Named Credentials.
2. Click New Named Credential.
3. Enter the following field values:
• Label: IBMFileNetCredential
• Name: IBMFileNetCredential
• URL: The URL of your IBM FileNet Content Services API server
• Identity Type: Per User
• Authentication Protocol: JWT
• Certificate: Click the Search icon and select the certificate that you created in
Generating a new self-signed certificate.
• Issuer: Paste the Consumer key from Creating a connected app.

© Copyright International Business Machines Corporation 2020 26

• Per User Subject: $User.Username
• Audiences: https://login.salesforce.com
• Token Valid for: 2 Hours
• JWT Signing Certificate is automatically filled in.
• In Callout Options, Generate Authorization Header is selected.
4. Confirm your values and click Save.

The screenshot below shows an example of the Named Credential details:

See the following Salesforce documentation topic for more details:

https://help.salesforce.com/articleView?id=remoteaccess_authenticate_overview.htm&type=5

Configuring OAuth authentication on the Content Services server

The email address of the logged-on Salesforce user is used as part of the identity propagated to
Content Services and the Content Platform Engine. To be able to access Content Services, the
user’s email address must exist as the shortName attribute in the Content Platform Engine
LDAP server for the user.

Installing the Salesforce SSL certificate on Content Services server

You install the SSL certificate that you generated on the SalesForce server on the Content
Services server to establish a secure connection. You downloaded this certificate as part of
Generating a new self-signed certificate.

To install the Salesforce SSL certificate:

1. Copy the SSL certificate that you downloaded from Salesforce to the overrides folder on
your Content Services server that contains your trust store. For example:
/opt/ibm/wlp/output/defaultServer/configDropins/overrides.
Create a new trust store and import the certificate to the Content Services server by using a
command similar to the following example:

keytool -import -file Saleforce_Certificate_for_IBM_Content_Services.crt -

alias Saleforce_Certificate_for_IBM_Content_Services -keystore
graphqlTrustStore.p12 -storetype pkcs12

2. Because keytool lowercases certificate alias names, verify what your certificate is called
after importing by using a command similar to the following:
keytool -list -keystore graphqlTrustStore.p12 -storetype pkcs12

Typical output for this command might be like the following example:

Keystore type: PKCS12

Keystore provider: SunJSSE

Your keystore contains 2 entries

default, Oct 14, 2019, PrivateKeyEntry,

Certificate fingerprint (SHA1):
BB:BB:4E:2F:62:4D:93:EC:29:3B:D3:3A:D2:84:53:40:FE:AE:E8:BC
saleforce_certificate_for_ibm_content_services, Nov 18,
2019, trustedCertEntry,

Certificate fingerprint (SHA1):
3D:42:08:D3:51:1B:86:05:65:C2:C6:A3:C3:E9:73:C3:8D:A0:14:5

Creating the Open ID Connect client configuration file

You configure your Content Services server as an Open ID Connect client by adding an oidc.xml
configuration file to the overrides directory for your Liberty server.

To create the OIDC client configuration file:

1. Create a file called oidc.xml, using the following example contents, and save it to the
${server-config-dir}/configDropins/overrides folder for your Liberty server:
<?xml version='1.0' encoding='UTF-8'?>
<server>
<featureManager>
<feature>openidConnectClient-1.0</feature>
<feature>transportSecurity-1.0</feature>
</featureManager>

<openidConnectClient
id="IbmContentServices"

issuerIdentifier="3MVG9_XwsqeYoueKsnUYSJ4OcVmjZvYlP6nOCuXA4ZfmRuD2toaZ121BKU.tqddt0V4l
7j.1YFkf9WC7i7BY8"
trustStoreRef="graphqlTrustStore"
trustAliasName="saleforce_certificate_for_ibm_content_services"
realmName="localRealm"
audiences="https://login.salesforce.com"
inboundPropagation="required"
httpsRequired="true"
isClientSideRedirectSupported="false"
signatureAlgorithm="RS256"
userIdentifier="sub"
uniqueUserIdentifier="sub"
userIdentityToCreateSubject="sub">
</openidConnectClient>
<keyStore id="graphqlTrustStore"
location="/opt/ibm/wlp/usr/servers/defaultServer/configDropins/overrides/graphqlTrustS
tore.p12" type="PKCS12" password="changeit" />

</server>

2. Update the following properties in the openidConnectClient stanza:

• Id: Must match the last part of the Callback URL defined on Salesforce in Creating a
connected app, for example, https://cpe-cmis-
dev.ibmbrsandbox.com:9444/oidcclient/redirect/IbmContentServices
• issuerIdentifier: The value for the Consumer Key that is defined on Salesforce in
Creating a connected app.
• trustStoreRef: Trust store in which you imported the Salesforce SSL certificate of your
Connected App in Installing the Salesforce SSL certificate on Content Services server.

• trustAliasName: SSL certificate alias of the Salesforce certificate you imported in
Installing the Salesforce SSL certificate on Content Services server.
• realmName: Name of the Content Platform Engine LDAP realm that contains Salesforce
user email addresses.

3. Add the keyStore stanza for the graphqlTrustStore into which you imported the Salesforce
certificate.

Configuring basic authentication

You can configure the IBM FileNet Connector for Salesforce to connect to the IBM Content
Services GraphQL API using the BasicAuth protocol. This method is recommended only for
development and test environments. For production environments, it is recommended to use
the OAuth mechanism as described in the previous section.

Configuring a Salesforce Named Credential for the FileNet server

The IBM FileNet Salesforce Connector requires a Salesforce Named Credential to control
authentication options for calls to the remote IBM Content Services GraphQL API.

To configure the connector for authentication through BasicAuth:

1. From Setup, enter Named Credentials in the Quick Find box, then select Named
Credentials.
2. Click New Named Credential, or click Edit to modify an existing named credential.
3. Enter the following fields:
• Label: IBM FileNet Credential
• Name: IBMFileNetCredential
• URL: The URL of your IBM Content Services GraphQL API server
• Identity Type: Per User
• Authentication Protocol: No Authentication
• Take the defaults in the Callout Options section
4. Click Save.

Each user must configure their username and password credentials for the FileNet environment
in their user profile, as described in a later section. For further details, see the following
Salesforce documentation topic:
https://help.salesforce.com/articleView?id=named_credentials_about.htm&type=5

Configuring Salesforce users who can use the Named Credential to authenticate

When using BasicAuth, users must reference the IBMFileNetCredential Named Credential
directly from their profiles. This approach requires that they have access to the Named
Credential. There are two options to complete this step, depending on whether you want all
users to be able to use the connector, or only certain users.

Option 1: Allow access for all users in the Salesforce Organization (Recommended)

If you want all Salesforce users within an organization to have non-administrative access to the
IBM FileNet Salesforce connector, add the Named Credential that was created in a previous
step to the Standard Profile for the organization (or the user profile of your choice).

1. In Setup, go to Profiles.
2. Select the Standard User profile (or the user profile of your choice).
3. Click Enable Named Credential Access URL.
4. Click Edit for Enable Named Credential Access.
5. Add the IBMFileNetCredential Named Credential to the list of Enabled Named Credentials.
6. Click Save.

Option 2: Allow access for a subset of Salesforce Organization users

1. In the Setup menu, go to Administration > Users, and select Permission Sets.
2. Click New to create a new Permission Set
3. For Label, enter IBM FileNet Named Credential
4. For API Name, enter IBM_FileNet_Named_Credential
5. Leave the Session Activation Required checkbox unchecked.
6. Leave the License dropdown set to Salesforce
7. Click Save to save the Permission Set.
8. In the Apps section for the Permission Set that you just created, click on Named Credential
Access.
9. Click Edit.
10. In the Available Named Credentials list, select the IBMFileNetCredential Named Credential
and move it to the Enabled Named Credentials List.
11. Click Save to save your changes.
12. On the Permission set screen, click Manage Assignments.
13. Select the user or users that you want to add to the permission set (or unselect users who
you would like to remove from the permission set), and click Assign.
14. Click Save to save your changes.

Configuring IBM FileNet Salesforce Connector authentication – per user

If the IBM Salesforce Connector app is configured to use Basic Auth, each user must add the
Named Credential IBMFileNetCredential to their individual profile and specify their credentials
for the FileNet environment. Any user who needs access to FileNet documents must perform
the following steps.

To configure authentication as an end user:

1. Navigate to your user profile in Salesforce.

2. Click Settings.
3. Go to Authentication Settings for External Systems.
4. Click Add to add a new Named Credential.
5. Set External System Definition to “Named Credential”.
6. Set Named Credential to “IBMFileNetCredential”.
7. If the BasicAuth option was chosen to configure authentication to the IBM Content Services
GraphQL API, then:
a. Set Authentication Protocol to “Password Authentication”
b. Enter the username for the IBM FileNet domain in the Username field.
c. Enter the password for the IBM FileNet domain in the password field.

Uninstalling the IBM FileNet Salesforce Connector app

You can remove the installed package. When a package is removed, all the components within
that package are also removed.

Note: When a Salesforce standard object has a reference to the package component, for
example, assigned users to a Permission Set, Salesforce prevents you from uninstalling the
package. You must delete those references first before you uninstall the package.

To remove the app from your organization:

1. From the Setup menu, go to Permission Sets, and remove all users from the IBM FileNet
Users permission set. Do the same for the IBM FileNet Admins permission set. These
permission set users must be removed before the app can be uninstalled.
2. Go to the page layouts where the IBM Document List widget was previously added, and
remove the IBM Document List lightning component from each of these pages. These
document list components must also be removed before the app can be uninstalled.
3. From the Setup menu, go to Installed Packages. Select the Uninstall action for the IBM
FileNet Salesforce Connector package.
4. Scroll to the bottom and check the checkbox to confirm that you want to uninstall the
package and permanently delete its components, and click Uninstall to complete the action.
5. From the Setup menu, go to the CSP Trusted Sites page, and delete the site that was
created for the IBM Content Services GraphQL endpoint.
6. From the Setup menu, go to the CORS page, and delete the whitelisted origin for the IBM
Content Service GraphQL endpoint.
7. From the Setup menu, go to the Named Credentials page, and delete the ecmcred named
credential.
8. For each user, from User Settings, remove the ecmcred Named Credential from the user
profile.

Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the products
and services currently available in your area. Any reference to an IBM product,
program, or service is not intended to state or imply that only that IBM product, program,
or service may be used. Any functionally equivalent product, program, or service that
does not infringe any IBM intellectual property right may be used instead. However, it is
the user's responsibility to evaluate and verify the operation of any non-IBM product,
program, or service.

IBM may have patents or pending patent applications covering subject matter described
in this document. The furnishing of this document does not grant you any license to
these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing IBM Corporation J74/G4 555 Bailey

Avenue

San Jose, CA 95141 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing Legal and Intellectual Property

Law IBM Japan, Ltd. 19-21, Nihonbashi-Hakozakicho, Chuo-ku Tokyo
103-8510, Japan

The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES
CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may not
apply to you.

This information could include technical inaccuracies or typographical errors. Changes

are periodically made to the information herein; these changes will be incorporated in
new editions of the publication. IBM may make improvements and/or changes in the
product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience
only and do not in any manner serve as an endorsement of those Web sites. The
materials at those Web sites are not part of the materials for this IBM product and use of
those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes
appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of
enabling: (i) the exchange of information between independently created programs and
other programs (including this one) and (ii) the mutual use of the information which has
been exchanged, should contact:

IBM Corporation J46A/G4 555 Bailey Avenue San Jose, CA 95141-1003

U.S.A.

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this document and all licensed material available for
it are provided by IBM under terms of the IBM Customer Agreement, IBM International
Program License Agreement or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment.

Therefore, the results obtained in other operating environments may vary significantly.
Some measurements may have been made on development-level systems and there is
no guarantee that these measurements will be the same on generally available
systems. Furthermore, some measurements may have been estimated through
extrapolation. Actual results may vary. Users of this document should verify the
applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those
products, their published announcements or other publicly available sources. IBM has
not tested those products and cannot confirm the accuracy of performance,
compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those
products.

All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice and represent goals and objectives only.

This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands and products. All of these names are fictitious
and any similarity to the names and addresses used by an actual business enterprise is
entirely coincidental.

This information contains sample application programs in source language, which

illustrate programming techniques on various operating platforms. You may copy,
modify and distribute these sample programs in any form without payment to IBM, for

the purposes of developing, using, marketing or distributing application programs
conforming to the application programming interface for the operating platform for which
the sample programs are written. These examples have not been thoroughly tested
under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability,
or function of these programs. The sample programs are provided "AS IS", without
warranty of any kind. IBM shall not be liable for any damages arising out of your use of
the sample programs.

Trademarks

IBM, the IBM logo and ibm.com are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies. A
current list of IBM trademarks is available on the Web at "Copyright and trademark
information" at www.ibm.com/legal/copytrade.shtml.

Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron,
Intel Xeon, Intel SpeedStep, Itanium and Pentium are trademarks or registered
trademarks of Intel Corporation or its subsidiaries in the United States and other
countries.

Linux is a registered trademark of Linus Torvalds in the United States, other countries,
or both.

Microsoft, Windows, Windows NT and the Windows logo are trademarks of Microsoft
Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other
countries. Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates. Other product and service names might be
trademarks of IBM or other companies.