Configuring the Edit Service client for IBM Content Navigator

If you use IBM® Content Navigator with IBM FileNet® P8 and IBM Content Manager repositories, you can install the Edit Service client on users' workstations. Then, users can easily add files or edit files in the local apps that are installed on their computers.

Before you begin

The IBM Content Navigator web client communicates with the Edit Service client through localhost.ibm.net, a global domain name server that points to 127.0.0.1.

If your network cannot access the internet, you must take one of the following actions to enable the web client to communicate with the Edit Service client.
  • Configure your own DNS server with to point localhost.ibm.net to 127.0.0.1.
  • Configure the hosts file on each client workstation to include the following entry,
    127.0.0.1 localhost.ibm.net

The Edit Service client stores temporary files and data files in the %TEMP%\IBM Content Navigator Edit\ and %APPDATA%\IBM Content Navigator Edit\ directory. Ensure that the user has write access to the files.

About this task

By default, the Edit Service client includes support for Microsoft Office documents. However, you can configure the Edit Service client to support other document types, such as PDF or HTML files.

When you use the Edit Service client on Mac OS and Windows, SAML SSO and Kerberos and SPNEGO SSO are supported.

The Edit Service client streamlines the following processes for users:
  • Creating and adding new documents to the repository.

    When the Edit Service client is enabled, a user can click New and select the type of file that they want to create. The file is added to the repository, checked out, and opened in the appropriate application on the user's workstation. Also, when the user saves their changes, the changes are checked into the repository.

  • Saving changes that are made in native desktop applications to the repository.

    When the Edit Service client is enabled and a user clicks Edit > Edit with Desktop apps, the file is checked out and opened in the appropriate application on their workstation. Also, when the user saves their changes, the changes are saved or checked into the repository.

For an IBM Content Manager repository, designate which item types are used with the Edit Service client. Set up the base security for the Edit Service client templates and the draft items. For draft items, all users of the Edit Service client require creator privileges.
Note: If the version policy is set to Always, the document will increase by two new versions after the editing process.

Note:

To designate the item types to use with the Edit Service client, complete the following steps:
  1. Open the repository configuration in the IBM Content Navigator administration tool.
  2. Click the Edit Integration tab.
  3. In the Class and Role Settings section, select the classes that are used with Edit Service client for IBM Content Manager.
  4. In the Class and Role Settings section, specify the groups or roles who can use the Edit Service client templates and the draft items.
  5. Save your changes to the repository configuration.

Procedure

To integrate IBM Content Navigator with user desktop applications:

  1. Enable the Edit Service client on each repository where you want users to store the files they add or edit through the Edit Service client:
    1. Open the repository configuration in the IBM Content Navigator administration tool.
    2. Click the Edit Integration tab.
    3. In the Edit Service Integration section, enable the Edit Service client.
    4. Save your changes to the repository configuration.
  2. By default, the Edit Service client enables users to create blank Microsoft Excel, PowerPoint, and Word documents. However, if you want to enable users to create other types of documents, such as PDF files, complete the following steps:
    1. Click New Category.
    2. Enter a display name and description for the category.
    3. Select the MIME types that you want to associate with the category.
    4. Click OK and save your changes to the repository configuration.
  3. If you created a custom category or if you want to associate a custom template with a default category, you must add one or more templates to each category.
    The following table explains when you must provide a custom template and when you can optionally provide a template.
    Templates Default categories Custom categories
    Blank template provided Yes. A blank template is provided for Microsoft Excel, PowerPoint, and Word files. No. However, you must add custom templates to enable users to create custom file types by using the Edit Service client.
    Custom templates required No. If you want users to create and add only blank Microsoft Office documents, you do not need to provide a custom template.

    However, if you provide a custom template, the blank templates that are provided with the Edit Service client are overwritten.

    If you want users to be able to create blank documents or use a predefined template, you must add a blank template and a custom template.

    Yes. Add one or more templates to each custom category to enable users to add new files to the repository by using the Edit Service client.
    1. Click Add for the category that you want to add a template to.
    2. Select the template file that you want to add to the repository and specify the appropriate values for the file in the repository.
      Important: Ensure that the users who need to use the template have access to the template.

      External users can add or modify files that are shared with them in the local applications that are installed on their computers. To use this feature, the Edit Service application must be installed on the client. For more information, see Sharing documents and folders with users outside of your organization.

    3. Click Add to add the file to the repository.
    4. If you have multiple templates that are associated with a category, specify which template is selected by default.
      This template is selected by default in the New Document window when the user clicks New > Document type.
    5. Save your changes to the repository configuration.
  4. Enable the Edit Service client on the appropriate desktops in your environment.
    1. Open the desktop configuration in the IBM Content Navigator administration tool.
    2. On the General tab, enable edit services.
    3. On the Repositories tab, ensure that the desktop includes at least one repository for which the Edit Service client is enabled.
    4. Save your changes to the desktop configuration.
  5. Deploy the Edit Service client to users by installing the service on user workstations silently or interactively.
    • To silently install the Edit Service client, modify the following command, as necessary. Then, run the command on client computers:
      ICNEditClient.exe /v"/qn /L*v C:\EditInstallLog.txt AgreeToLicense=Yes"
      Any messages and errors from the installation program are written to the c:\EditInstallLog.txt log file. If you want to generate the log file in a different location, modify the following argument in the command:
      /L*v \"fully_qualified_path_of_the_log_file\"
      If you want to enable SAML SSO in silent install, set the parameter ISSSO to true. Run the command
      ICNEditClient.exe /v"/qn ISSSO=True AgreeToLicense=Yes"
      This parameter is not necessary for Kerberos SSO.
    • To interactively install the Edit Service client, instruct your users about where they can download the ICNEditClient.exe file to run the installation program.
    Related information:
If users receive an error when saving in the Edit Client, there is a Retry Saving option that they can use to retry saving their document.
Note: The Edit Service client starts an SSL service by using port 13553. If the service cannot be started by using port 13553, the service attempts ports 13554, and then 13555. If all three ports fail, the Edit Service client reports an error.

Disabling automatic validation of IBM Content Navigator server SSL certificate for the Edit Service client

About this task

The Edit Service client validates the IBM Content Navigator server SSL certificate for security reasons by default, and protects your client system from invalid SSL certificate attacks. If you want to disable this feature, complete the following steps:
  • Windows: In the default installation directory, C:\Program Files (x86)\IBM\IBM Content Navigator Edit\EditClient\, open the IBM Content Navigator Edit.exe.config file and change the SSL parameter from True to False.
  • Mac: In the default directory, /Users/%username%/Library/Application Support/IBM Content Navigator Edit, open the IBMContentNavigatorConfiguration.plist file and change the Validate SSL Certificate parameter from True to False.

Configuring the Edit Service client for an SSO environment

About this task

To use the IBM Content Navigator Windows and Mac Edit Service client in an SSO environment, complete the following configuration.
Option 1
Click the Edit Service client application icon, and then select Use Single Sign-On from the menu.
Option 2
(Windows Edit Service client only) Modify the IBM Content Navigator Edit.exe.config file and change the isSSO parameter from False to True. The default path is: C:\Program Files (x86)\IBM\IBM Content Navigator Edit\EditClient\. Restart the Windows Edit Service client.
Note:
  1. If you choose option 2, then Use Single Sign-On is disabled in the menu. When the isSSO parameter is changed from True to False, Use Single Sign-On is enabled and active.
  2. These options apply only to special cases that need to do the authentication for the Edit Service client in IBM Content Navigator. The following items are special cases.
    • A custom Identity Provider (IdP) server is used, which applies a token exchange mechanism during authentication.
    • When the Edit Service client is started after the user already authenticated IBM Content Navigator from the browser. In this situation, the user needs to refresh the browser page to allow the web to send the authentication token to the Edit client again. If the user does not refresh the browser, the Edit client resorts to the previous method of authentication and opens an authentication window.
    • A custom certificate is used and the password for the custom certificate is stored in the IBM Content Navigator database. In this case, the Edit client needs to retrieve the custom certificate password from the IBM Content Navigator database upon launch. This retrieval process requires authentication.
    • A user has unsaved document changes to the local workstation that results from a lost network connection or from other reasons. The network becomes online and tries to upload the unsaved changes.

Customizing the Edit client URL

About this task

You can customize the Edit client URL to use your own certificate. The default URL to access the Edit client is https://localhost.ibm.net:13553.

You can configure an Edit client custom URL in the administration desktop by enabling the Edit Service custom URL, and then entering the same hostname with your custom SSL certificate. Following are the detailed steps.

For the Windows Edit Service client, choose one of the two approaches.
  • The first approach. Save the custom certificate password in the Content Navigator database.
    1. When you enable the Edit Service custom URL in the administration desktop, enter the custom certificate password into Custom Certificate Password.
    2. Copy the certificate to the Edit client's installation directory: ...\IBM Content Navigator Edit\EditClient\.
    3. Open and modify the IBM Content Navigator Edit.exe.config file, which is in the installation directory: ...\IBM Content Navigator Edit\EditClient\. Change the certificate name to the name of your custom certificate. Update ServerURL and UserID with your IBM Content Navigator server URL and user ID.
    4. Restart the Edit client.
  • The second approach. Enable the custom certificate password through Edit client plug-in.
    1. Retrieve the EditCustomURLPlugin source code from Windows Edit Client build file and open it with Visual Studio IDE. Change the variable CertPassword value to the certificate's password in the file CustomURLPlugin.cs. Recompile the project EditCustomURLPlugin to generate the DLL file with Visual Studio IDE.
    2. Copy the EditCustomURLPlugin.dll file to the Edit client's installation directory: ....\IBM Content Navigator Edit\EditClient\Plugins\.
    3. Copy the certificate to the Edit client's installation directory: ...\IBM Content Navigator Edit\EditClient\.
    4. Open and modify the IBM Content Navigator Edit.exe.config file, which is under the installation directory: ...\IBM Content Navigator Edit\EditClient\. Change the certificate name to the name of your custom certificate. Update the DefaultCustomURLPlugin value if you have a different plug-in name.
    5. Restart the Edit client.
Note: The certificate must be in the PKCS#12 format with the .p12 extension.
For the Mac Edit Service client:
  1. Retrieve the EditCustomURLPlugin source code from the Mac Edit Client build file. Open the code with Xcode IDE, and then change the variable certPassword value to the certificate's password in the CustomURLPlugin.m file. Clean and build the project CustomURLPlugin to generate the plug-in file with Xcode IDE.
  2. Copy the CustomURLPlugin.plugin file to the Mac Edit client's configuration directory: /Users/%username%/Library/Application Support/IBM Content Navigator Edit/Plugins/.
  3. Copy the custom certificate to the Edit client's configuration directory: /Users/%username%/Library/Application Support/IBM Content Navigator Edit/.
  4. Open and modify the IBMContentNavigatorConfiguration.plist file, which is under the configuration directory: /Users/%username%/Library/Application Support/IBM Content Navigator Edit/. Change the CertificateName value to the name of your custom certificate. Update the DefaultCustomURLPlugin value if you have a different plug-in name.
  5. Restart the Edit client.
Note: The plug-in bundle file must be code-designed with a valid Apple development certificate during the rebuild process. Otherwise, the Mac Edit Service client can't load it.

Configuring the Edit Service client to list Content Navigator hosts that can access the Edit client

About this task

For Windows only. You can configure the Edit Client to provide a CORS site IBM Content Navigator host access list. You can limit the Content Navigator hosts that can access the Edit Service client.

To configure your Edit Client with the Content Navigator host list, complete the following steps.

  1. Edit the IBM Content Navigator Edit.exe.config configuration file and add the CORSSites property with the list of hosts that are allowed to access the Edit Service client. The value can be *, which allows all hosts. You can list several hosts that are separated by commas and no spaces.
    Examples:
    • To allow all Content Navigator hosts, enter
      <setting name="CORSSites" serializeAs="String"> <value>*</value></setting>
    • To allow a limited set of Content Navigator hosts, enter
      <setting name="CORSSites" serializeAs="String"> <value>http://icnserver1:port,https://icnserver1:port,https://icnserver2:port</value></setting>
      Note: If you have a host that is defined as http(s)://icnserver:port/navigator, set the URL as http(s)://icnserver:port.
  2. Restart the Edit Service client. Click IBM Content Navigator Edit.exe.
  3. From one of the allowed Content Navigator hosts, edit a document. Go to Edit > Edit with desktop apps.

    In the Response Headers, the Access Control Allow Origin: displays the Content Navigator host URL that you are using for your document edits. If the Access Control Allow Origin: displays an *, then any Content Navigator host URL is allowed to edit documents. If an * is not displayed or if the host is not listed in the CORSSite property, the edit request is rejected by the Edit Service client, and an error message is posted.