Last Updated on

Overview of the Transact and Box Solution with Ephesoft Transact 4.5.0.x

Section 1

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

The Data Capture, Processing, and Storage Solution

Section 1.1

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:
    https://www.box.com/home
Transact 4.5.0.x 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

Section 1.2

  • Ensure that Ephesoft Transact 4.5.0.x 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

Section 2

Setting up Box for Transact Integration

Section 2.1

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:

Box Welcome Screen

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

Box Developers home screen

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

First screen of Create New App

5. Choose Enterprise Integration for a new Box application.

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

Authentication Method screen and information

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

Naming the app

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.

Confirmation of app creation

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

Configuration screen with Developer Token and more information
  • 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.
Application Access and Authentication settings

10. Set the Application Access to Enterprise.

Application Access settings

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

Application Scopes settings

12. Under Advanced Features, enable the following settings:

  • Perform Actions as Users
  • Generate User Tokens
Advanced Features

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

Add and Manage Public Keys

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

Section 2.2

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.

Authentication Password Settings

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

Enable Login Verification settings

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

Enable Login Verification settings — Confirmation Code

The system returns you to the Account Settings screen.

5. Click Save Settings.

Generating the Public/Private Keypair

Section 2.3

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:

Keypair Configuration

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

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

JSON File editing
  • 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

Section 2.4

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:

Authorization error message

Follow these steps to authorize the app:

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

Welcome screen of the Admin Console

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

Click Business Settings

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

Account Information from Business Settings

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

Productivity Integrations for Box for Office Online

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

Custom Applications

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.

App Authorization > Enter the API Key

5. Click Next. The following popup dialog appears:

App Authorization

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.

Click Reauthorize App as applicable

8. Authorize all users.

Defining Additional Settings

Section 2.5

Creating the Box Developer Account

Section 2.5.1

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.

Advisory for Two Factor Authentication

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

Authentication Method

Box App Configuration — Developer Access

Section 2.5.2

Developer Token screen

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

Section 2.5.3

Admin Options and access to Business Settings

Authoring the Box Developer Application

Section 2.5.4

Defining email addresses

Configuring the Box Export Plugin in Transact 4.5.0.0

Section 3

Prerequisites

Section 3.1

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
Setting up Multipage File Creation Type

Procedure

Section 3.2

Perform the following steps to configure the BOX-PLUGIN:

1. Launch Ephesoft Transact, expand the Administrator menu, and click Batch Class Management.

Administrator menu during login

Alternatively, if you are already logged into Ephesoft Transact, expand the navigation on the left, and click Batch Class Management.

Administrator menu in navigation pane

The batch classes that are currently configured for Transact display on the home page.

Batch Class Management home screen (sample batch classes shown)

2. You can add a new batch class or edit an existing batch class.

  • To create a new batch class, click Add.
  • To configure the Box Export plugin for an existing batch class, select (check) the batch class to be configured, and click Open.

The navigation on the left displays all components of the batch class you have opened or created.

Expand to the Export Plugin

3. If the Box Export plugin has not been added to the Export module, follow these steps to add the Box Export plugin to the batch:

a. Click Export. The Plugin Configuration screen appears.

b. Select BOX_PLUGIN from the Associated Plugins field, and click the right arrows to move this plugin to the Selected Plugins field.

c. Click the up or down arrow to move this plugin to the proper position, in relation to other plugins. In most or all cases, the BOX_EXPORT plugin should come before the CLEANUP plugin.

Box Export plugin in the Selected Plugins field

d. Click Apply and Deploy. The BOX_PLUGIN should now appear in the Export module on the left.

4. To enable the BOX_PLUGIN feature, follow these steps:

a. Select BOX_PLUGIN from the Export module.

Enabling BOX_PLUGIN

b. In the Plugin Configuration field, select ON for the Export to BOX Switch setting, then click Apply and Deploy.

5. To enable the BOX Export plugin, navigate to Modules > Export > BOX_PLUGIN > Configure, as shown.

Navigate to Export > BOX_PLUGIN > Configure

 

6. Define the Connection Details in the following screen.

Connection Details for the Box Export Plugin

You can set up the Box export in either of the following ways: 0 — Production Mode or 1 — Testing Mode.

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.
Connection Details with sample settings defined
  • 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.
App Info settings

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.
Connection Details with environment and token information

7. 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>.
Folder ID name location

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

8. 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.
Document Attributes with Access Stats
  • 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.

Details of the Box account

Using the Box Export Plugin in Transact 4.5.0.x

Section 4

This section describes and illustrates how to use or operate the BATCH_PLUGIN from the Export module of a batch class.

Creating Folders in the Box Dashboard

Section 4.1

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.
Files in Box account

Create a New Folder screen

  • Enter the file name.
File Name entry location
    Enter the folder ID.
Folder ID location and Export Details

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

Defining Document Attribute Key
Defining Document Attributes
Connection Settings

Testing a Connection

Section 4.2

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.

Box Mapping Configurations for testing a connection

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.

Connection Details

Demo Use Cases

Section 5

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

Section 5.1

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

Troubleshooting

Section 6

Box Error Codes

Section 6.1

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

400 — invalid_grants System Message

Section 6.2

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

Section 6.3

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?

Vincent Francis