› Integration with third party software › RightFax fax server - REST WebAPI

RightFax fax server - REST WebAPI

In addition to configuring the connection to the RightFax fax server in KC Plug-In, the RightFax WebAPI interface must be installed/enabled on the RightFax server to use with Kofax Import Connector.

Work with your fax server administrator to complete the tasks described in the following sections.

RightFax client installation is not necessary on the Message Connector computer.

Prerequisites

RightFax server version 16.4 or higher to support the REST Web API for the clients.

From the RightFax server version 16.6 onwards, the support of the traditional COM API is discontinued.

Configure RightFax server

The RightFax WebAPI interface must be explicitly installed/enabled on the RightFax server.

Http verbs GET, POST, PUT and DELETE must be allowed on the IIS on RightFax server. Note that, especially PUT and DELETE may be disallowed on the IIS due to some historical reasons. For example, by the Microsoft’s UrlScan utility.

  1. On the RightFax fax server, start the Enterprise Fax Manager tool.
  2. Create (or reserve) a user/extension for use with Kofax Import Connector.
  3. Close the tool.
  4. Optional. Verify the connection through REST WebAPI to the RightFax server with the OpenText’s FaxUtil Web client, which uses the same API as the Message Connector. Therefore, if you cannot access the RightFax server mailbox, the Rightfax Connector will also not work. Do the following:
    1. Execute the following URL in a browser of a computer where Message Connector is installed: http://<RightFaxServer>/rightfax.

      Where, <RightFaxServer> is the IP address or hostname of the RightFax server.

    2. Click the FaxUtil Web button and login with any RightFax user. Verify if you can access the mailbox.

      If you cannot access RightFax server with FaxUtil Web using the above steps, contact your Rightfax server administrator.

Configure RightFax connector in KC Plug-In

Following configurations are specific for RightFax Rest WebAPI fax server type. For complete fax server settings, refer to the KC Plug-In online help.

  1. Open Fax server import settings window.
  2. On the Type list, select RightFax Rest WebAPI.
  3. In the Host field, specify the fax server URL in http[s]://<RightFaxServer>/rightfax/api format.

    where, <RightFaxServer> is the IP address or hostname of the RightFax server.

  4. Under Operation Mode, select whether to poll fax server using single or multiple Message Connectors. See the next section.

    • Single Instance

    • Multi Instance

Single and multi-instance modes

When configuring RightFax server in KC Plug-In, you can select to poll the RightFax server using one or multiple instances of Message Connectors.

Single instance

Allows polling of fax server with only one Message Connector. Selecting this option and running multiple connections in parallel may import the same fax multiple times in Kofax Capture.

Following is the process to import a message:

  1. When a new fax is detected in the fax server inbox, it is immediately imported into the Message Connector storage. The comment field of message in RightFax server inbox displays the following status:

    [<UniqueId>]KCFax:fetched at <Date and Time>,awaitConfirm for 600s

    Where,

    <UniqueId>: The unique ID of Message Connector which is polling the fax server.

    <Date and Time>: The UTC date and time when the message arrived in ISO 8601 format.

  2. Once the message is imported in Kofax Capture, the comment field of message in RightFax server inbox is updated with the following status:

    [<UniqueId>]KCFax:deleted at <Date and Time>

  3. The message is deleted immediately.

Multi instance

Allows multiple Message Connector connections to a single fax server, without risking duplicate imports. However, to avoid duplicate fax import, this option introduces a small delay in importing faxes (by default, 60 seconds).

When a new fax arrives in the fax server inbox, instead of importing this message immediately, all Message Connector instances attempt to reserve the message. But the message is reserved for only one instance of Message Connector and only that instance can fetch the message.

Following is the process to import a message:

  1. When a new fax is detected in the fax server inbox, this message is reserved for a specific instance of Message Connector. Before importing, this message must wait in the inbox for 60 seconds (ReservationTimeout).

    The comment field of message in RightFax server inbox displays the following status:

    [<UniqueId>]KCFax:reserved at <Date and Time>,awaitFetch for 60s

    Where,

    <UniqueId>: The unique ID of Message Connector which is polling the fax server.

    <Date and Time>: The UTC date and time when the message arrived in ISO 8601 format.

  2. Once 60 seconds (ReservationTimeout) are expired, the message is immediately imported into Message Connector storage. The comment field of message in RightFax server inbox displays the following status:

    [<UniqueId>]KCFax:fetched at <Date and Time>,awaitConfirm for 600s

  3. When the message is imported in Kofax Capture, the comment field of message in RightFax server inbox is updated with the following status:

    [<UniqueId>]KCFax:deleted at <Date and Time>

  4. The message is deleted immediately.

If a message reserved for a specific Message Connector is not polled due to reasons, such as, the specific Message Connector instance is not working, the following process is used:

  1. The message remains in the reserve state for ProcessingTimeout (by default, 3600 seconds).

  2. Once the ProcessingTimeout is expired, the message enters and remains in expiry pending state define by ExpiryTimeout (by default 300 seconds).

  3. Once the ExpiryTimeout is expired, the message can be reserved by any running instance of Message Connector and is treated as a new message.

    To compensate ReservationTimeout (60 second) for every message, each Message Connector instance can reserve up to 100 messages (MaxReservedTotal) and keep polling the messages for which ReservationTimeout is expired.

By default, all configuration values are defined for optimum performance. If required, change the values of these parameters in the Create_Config.xslt file.

Parameter name Default value Description
ReservationTimeout 60 seconds The time for which message remains in reserved state.
ProcessingTimeout 3600 seconds The time limit for processing a message once the reserve timer is expired.
MaxReservedTotal 100 Maximum number of messages a single instance of Message Connector can reserve.
ExpiryTimeout 300 seconds The time limit to wait after ProcessingTimeout. Once this expires, the message is handled as a new message.

Forward faxes from multiple mailboxes to a single queue user

In KC Plug-In, you can only configure a single user for accessing RightFax. You can access multiple mailboxes using an administrator user. If you do not want to use an administrator user for security reasons, you can set up fax forwarding to a dedicated user, and use the credentials of this user in KC Plug-In. Each fax user must configure fax forwarding using RightFax FaxUtil.

  1. Start RightFax FaxUtil from the Windows Start menu and log in.
  2. On the Tools menu, click Options.
  3. On the Receiving tab, select Forward Received Faxes to Users.
  4. Select the dedicated user as the recipient of the forwarded faxes.
  5. Confirm the changes and close FaxUtil.

Keep messages on RightFax server

By default, Kofax Import Connector deletes imported messages from the fax server. You can configure Message Connector to keep the messages on the fax server for later processing. Do the following in Message Connector Configuration:

  1. Set Keep messages on RightFax Server of the Fax Server tab to "[8] Yes".
  2. Start Message Connector configuration. Verify the value in the Fax Server tab.
  3. Click Save, then click Exit.

Imported messages are no longer deleted from the RightFax server, instead, the text "KCFax:marked to delete" is added to the comment field.

Poll order

Following improvements are implemented in the RightFax Connector to avoid situations where some faxes may stay much longer in the inbox than the others.

RightFax connector - Web API RightFax connector - COM API

Fetches the oldest fax from the inbox first.

Fetches the newest fax first causing the older faxes to remain in inbox for longer times.

Polls multiple inboxes in a round-robin manner.

Starts the poll cycle with the first user in the list and only served the others if first user's inbox is empty.

Security and authentication

  • Rightfax supports only basic authentication for the REST WebAPI. Refer to the API help at:

    http://rightfaxsdk.cloudapp.net/RightFaxSdk/ApiHelp/default.htm

  • For security purposes in the production environments, a SSL certificate would be installed on the IIS server and on the RightFax server, and the RightFax and the RightFax connector would use the https type of connection.

  • In test environments, there may be only a self-signed SSL certificate installed on the server, and the RightFax connector will not be able to connect through https connection as it may not trust the certificate. To ignore certificate errors in test environments, do the following:

    1. Open Create_Config.xslt in a text editor. Default path

      C:\Program Files (x86)\Kofax\KIC-ED\MC\xcd

    2. Set the value of <IgnoreCertificateError> element to true as shown below. 

      <TncRFax2>
	  ...
	  <Test>
	    <IgnoreCertificateError>true</IgnoreCertificateError>
	  </Test>
	  ...
	</TncRFax2>

    3. Save and close the file.

    4. Run configure.bat.

Troubleshoot REST WebAPI connection issues

To troubleshoot REST WebAPI connection issues, use the Fiddler tool. Refer to the following link:

https://www.telerik.com/download/fiddler.

Fiddler tool cannot log the WebAPI communication of Windows services, therefore enable this in Message Connector's configuration.

  1. Open Create_Config.xslt in a text editor. Default path:

    C:\Program Files (x86)\Kofax\KIC-ED\MC\xcd

  2. Search for the following code snippet. 

    ... 
       <Proxy>
         <!-- set enabled to true only to log the webAPI traffic with fiddler  -->
         <Enabled>true</Enabled>
         <Url>http://localhost:8888</Url>
         <BypassOnLocal>true</BypassOnLocal>
       </Proxy>
       ...

  3. Change the value of <Enabled> element from false to true.
  4. Save and close the file.
  5. Run configure.bat.
  6. Save the Message Connector Configuration and restart the Message Connector service.
  7. Start Fiddler and enable the logging of traffic to the IP address of the RightFaxServer.

    In Fiddler enabled mode, Fiddler must be running for the Message Connector to work.

    Alternatively, stop the Message Connector service, and start it in the command line mode by executing the run.bat file. When running in the command line mode, Message Connector is automatically traceable by Fiddler.

    Once Fiddler running and tracing the communication between Message Connector and Rightfax server, run the functions with issues and then save the session data collected in Fiddler for further analysis.