Configuring and Using the Box Export Plugin

Overview of the Transact and Box Solution with Ephesoft Transact 4.5.0.0

This document describes topics and tasks for setting up a connection and export between Transact 4.5.0.0 and the Box storehouse.

The Data Capture, Processing, and Storage Solution

Box is a cloud-based computing solution with a content management repository.

  • Box provides state-of-the-art tools for the enterprise, enabling the enterprise to secure, share, edit and store files in cloud deployment.
  • Box provides the API support that enables applications to integrate the Box repository.
  • For additional information, refer to the Box home page:
Transact 4.5.0.0 supports the BOX_EXPORT plugin for the Box data storehouse.

This document describes how to set up and export source and batch files to the Box storehouse from Transact 4.5.0.0, with the following elements of deployment:

  • Prerequisites for using the Box Export Plugin
  • Setting up the Box storehouse application
  • Configuring the BOX_PLUGIN in Transact
  • Executing a batch with Box export
  • Using the CREATE_MULTIPLE_FILES (plugin)
  • Referring to common system messages (error codes) and support

Prerequisites

  • Ensure that Transact 4.5.0.0 is fully installed and licensed, with an administrator account
  • Be familiar with the configuration and functions of the CREATE_MULTIPLE_FILES plugin
  • Ensure that a Box administrator can access and configure Box storage outside of Transact

Creating and Configuring the Box Developer Application

Setting up Box for Transact Integration

Navigate to https://developer.box.com.

1. Log in to the Box account with the credentials in which the developer application is to be created.

2. To create the new developer application, navigate to My Apps.

3. If you are creating the very first Box app, the following screen appears:

If you already have Box apps created, the following screen appears:

4. Click Create New App. The following screen appears.

5. Choose Enterprise Integration for a new Box application.

6. Set the authentication method to OAuth 2.0 with JWT (Server Authentication).

7. Click Next, and provide the name of the application. The name should be unique.

8. Click Create App. This creates the application with the same API call command. The following dialog appears. This dialog provides a sample URL by which you can test the connection. Use this sample URL to verify that the Box web app has been successfully created.

9. Click View Your App. The following screen appears.

  • You can use the Developer Token in the Ephesoft Transact configuration for testing the configuration. Note that this is only valid for one hour.
  • For Production access with Ephesoft Transact, Ephesoft recommends using the RSA keypair-based authentication.

10. Set the Application Access to Enterprise.

11. Under Application Scopes, define the following settings illustrated in the snapshot.

12. Under Advanced Features, enable the following settings:

  • Perform Actions as Users
  • Generate User Tokens

13. Under Add and Manage Public Keys, click Generate a Public/Private Keypair.

This downloads a JSON file with Box connection details. This file will be used in Transact during Box plugin configuration (in a later procedure).

Note: The system may prompt you to enable or enter two-factor authentication to generate the keys. Please enable this from the link provided when you click generate public/private keys.

Enabling 2-step Authentication

Perform these steps to enable 2-step authentication in the Transact connection to Box:

1. When you click Generate a Public/Private Keypair, you may be prompted to define additional settings. Refer to the topic Defining Additional Settings.

2. In Authentication, enable (select) Require 2-step verification for unrecognized logins.

3. When the Enable Login Verification dialog appears, provide the required settings.

4. Click Continue. Enter the Confirmation Code and click Continue.

The system returns you to the Account Settings screen.

5. Click Save Settings.

Generating the Public/Private Keypair

Perform these steps to generate the public/private keypair to support the Transact connection to Box:

1. Navigate back to the Developer Console — My Apps. Re-open the application.

2. Click Configuration to reopen the configuration settings screen. Browse down to Add and Manage Public Keys and click Generate a Public/Private Keypair. The following message appears:

3. Click OK. Click (open) the downloaded JSON file.

4. Open the file for editing. The following snapshot illustrates the downloaded JSON file.

  • The enterpriseID links to the Box account. You will see this same ID in the App you have created.

Authorizing the Box Developer Application for Access from API

Once the Box application is created and configured with the previous steps, the Box administrator must also authorize the application to be able to use it.

Without authorizing the application, the following message appears:

Follow these steps to authorize the app:

1. Navigate to the Admin Console, or https://app.box.com/master.

2. Click the settings on the top-right corner and navigate to Business Settings > Apps.

3. Click Apps from the menu of the following screen.

The following snapshot illustrates certain additional business settings to enable in this setup.

4. Navigate to Custom Applications and click Authorize New App.

A dialog box appears in which you must provide the client-id from the JSON file downloaded and opened in a previous step. Enter this value in the API Key field.

5. Click Next. The following popup dialog appears:

6. Click Authorize.

Note: Navigate to Apps > Authorize New App. Provide the API key and click Authorize.

7. If the App Authorization setting is limited to Only App Users on this App, you must click Reauthorize App.

8. Authorize all users.

Defining Additional Settings

Creating the Box Developer Account

If you have been prompted to define additional settings during the previous procedure, follow these steps.

1. If the system prompts you with the following message, click to enable 2-step authentication.

2. Click Settings.

3. In Account Settings, define the following properties and Save Changes.

Box App Configuration — Developer Access

Note: The Developer Token can be used to test the API connection. Be aware that the token is only valid for one hour.

Box App Configuration — Production Access

Authoring the Box Developer Application

Configuring the Box Export Plugin in Transact 4.5.0.0

Prerequisites

Ensure the following preconditions are met prior to setting up Box Export in Transact 4.5.0.0.

  • Verify that the external Box configurations are live and operational for external storage. Refer to the topic Creating and Configuring the Box Developer Application if necessary.
  • Verify the Transact configurations are live and operational, with production batch classes imported.
  • Use BOX-PLUGIN in the Transact Export module to configure file export functions through connection to Box data storage.
  • This plugin is dependent on the CREATEMULTIPAGE_FILES plugin to export files.
  • The user must select the Multipage File Creation Type, with the following options:
    • PDF
    • Tiff
    • Tiff and PDF

Procedure

Perform the following steps to configure the BOX-PLUGIN:

1. Click Configure in the BOX_PLUGIN file to set up the configuration setting for the plugin.

2. Define the Connection Details in the following screen.

You can set up the Box export in either of the following ways:

a. 0 — Production Mode

This mode requires the Box JSON file.

  1. Provide the Login ID or the User ID in addition to the JSON details to allow a user to connect to Box during export.
  2. Click Browse JSON, and some fields auto-populate from the JSON file.
  • You must enter the Login ID or the User ID.

The Login ID is the email address with which the Box user is logging into the developer account.

          Note: If you provide the User ID, you can leave the Login ID blank.

  • The Connection Name must be unique.

  • In the case of User ID, if you wish to populate the User ID in the JSON file, you can do so. Navigate back to the Box Developers Console from the previous procedure. Open the App. Access the User ID from the App Info section.

b. 1 — Test Mode

This mode uses a developer token for setup. The developer token is only valid for one hour from creation time.

Generate the developer token from the configuration screen in the Box developer website.

  • Click the Connect button to verify the connection is operable. This will verify that the user can perform a file upload to the target folder.

3. Configure the Export Details for Box with the following settings:

File Type Set as Tiff, PDF or both, depending on the Multipage File Creation Type settings for the CREATEMULTIPAGE_FILES plugin.

IMPORTANT: This setting must be the same in both plugins.

Folder ID Set the Box Folder ID to define the target location of files to be exported.

If you do not set a specific folder, set 0 for the root folder if there is no specific Folder ID.

File Name and File Description Provide these settings for the files to be exported to Box. You can make use of the suggested placeholders to generate dynamic file names.
Autosuggestion The autosuggestion parameters must be separated by the $ (ampersand) character, as with other Ephesoft plugins. The default setting creates file names as <Batch Instance ID>_<Document ID>.

The snapshot above illustrates where to view the Folder ID or folder name.

4. Configure the Document Attributes as follows:

Attribute Key This is the name in the Custom Metadata exported to Box.
Attribute Value This is the value for the Custom Metadata exported to Box. Metadata details can be viewed in the bottom-right corner, after the file is opened in Box.

  • Click View Details for more metadata information.
    • If the Box file name already exists in the target Box account folder, to which the file is exported, then the API also supports versioning.

                    Note: If the filename is the same, Ephesoft will export with a new file version using the support provided in the Box API.

Using the Box Export Plugin in Transact 4.5.0.0

Checking the BOX_PLUGIN Configuration

Follow these steps to check the value of the Box plugin configuration:

1. In the navigation pane on the left, browse to the BOX_PLUGIN and click Configure.

2. Click Add to define the Document Type and Connection Type. The Box Mapping Configurations screen appears.

With the Invoice document type selected, the following screen shot illustrates the settings required for a new connection.

For more information, refer to the JSON file in the procedure, Generating the Public/Private Keypair

The following screen illustrates required parameters from the JSON file.

Creating Folders in the Box Dashboard

The following use case and snapshots illustrate folder creation in the Box dashboard.

  • Once you have created a new folder, refer to the URL for the complete ID for the new folder.
  • Paste that folder ID into the Folder ID field of the Export Details screen in Transact.
  • If the user does not have access to the root folder, the user must create and configure a specific folder name or ID.

Folder ID here

Provide the document attributes in the Box Mapping Configuration screen, as illustrated below. Define the Attribute Key and the Attribute Value.

Click Edit from the BOX_PLUGIN Configuration screen. This will display additional fields that allow you to view or edit configuration details. Refer also to the topic Configuring the Box Export Plugin in Transact 4.5.0.0.

Testing a Connection

Follow these steps to test and view details of a connection:

1. Click Connect. A few moments are required. When successful, the screen displays additional Export Details.

2. Click in the Folder ID field to select additional target Box storage information. Transact supports dynamic test folders.

  • Enter 0 to export to the root folder of the Batch export location.
  • You must provide a folder ID but it does not need to be 0 in every case.

3. Enter the File Name.

Demo Use Cases

This section will contain sample configurations that illustrate certain settings of the Box Export plugin.

Note: These demo configurations are taken from an operable environment with the Ephesoft Transact and Box Developer environments.

Upcoming Information

These demo cases will illustrate sample guidelines or configurations for the following scenarios:

  • Using multiple export folders for a single document type
  • Versioning the same export document if required
  • Using the retry mechanism and error codes, as in cases of network failure, or another failover mechanism
  • Using a dynamic file name or description

Box Error Codes

Refer to the following list for Box error codes that may apply with configuration or operational issues.

Code Explanation
0 Due to network issue, API cannot be accessed
400 Invalid grants on Box because of app may not be authorized, or verify if server time is correct.
404 Not found
409 Conflict: Item with same name already exists or API operation may be blocked temporarily
429 Rate Limit is exhausted for the API
500 Box Internal server error
503 Unavailable – Box API may be down

Refer to the following online resource for additional information about Box error codes.

https://developer.box.com/docs/detailed-error-messages

Troubleshooting

400 — invalid_grants System Message

If there is a discrepancy between time zone settings between the Transact system and the Box storehouse, the user may receive an error message – “400 – invalid_grants”.

When the Box Java SDK generates a request for the App User access token, it uses the current UTC time as part of this request. If the Unix time on your local machine and the Box server are out of sync, you will see the exp claim error.

To fix this error, follow these steps

1. Update the Unix time on your machine to match the Unix time from the following site:

https://www.unixtimestamp.com

2. Then retry your request to generate the App User access token.

Box API Retry Functionality

Ephesoft Transact 4.5.0.0 supports a configurable retry mechanism for some error codes from Box API. The configuration is accessible from the following location:

<EPHESOFT>/Application/WEB-INF/classes/META-INF/dcma-box-plugin/dcma-box-plugin.properties

Retry Attempts The user can adjust the number of retry attempts.

The default setting is 3. This can be modified, if required.

Retry Interval The user can adjust the interval during each retry attempt is to be made.

The default setting is 2000 milliseconds, which is approximately 2 seconds.

The default retry mechanism is for some frequent errors that may occur on the network, or an API limitation. This can be modified if required.

Was this article helpful to you?

Rene Hernandez