Overview of the Transact and Box Solution with Ephesoft Transact 4.5.0.x
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
|Box is a cloud-based computing solution with a content management repository.
|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 220.127.116.11, with the following elements of deployment:
- 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
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.
Application Access settings
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.
Enable Login Verification settings — Confirmation Code
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 18.104.22.168
Ensure the following preconditions are met prior to setting up Box Export in Transact 22.214.171.124.
- 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:
- Tiff and PDF
Perform the following steps to configure the BOX-PLUGIN:
1. Launch Ephesoft Transact, expand the Administrator menu, and click Batch Class Management.
Alternatively, if you are already logged into Ephesoft Transact, expand the navigation on the left, and click Batch Class Management.
The batch classes that are currently configured for Transact display on the home page.
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.
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.
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.
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.
6. Define the Connection Details in the following screen.
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.
- Provide the Login ID or the User ID in addition to the JSON details to allow a user to connect to Box during export.
- 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.
7. Configure the Export Details for Box with the following settings:
|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.
|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.|
|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.
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.|
- 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.x
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
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.
Create a New Folder screen
- Enter the file name.
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.x.
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.
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.
|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.|
|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.
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:
2. Then retry your request to generate the App User access token.
Box API Retry Functionality
Ephesoft Transact 126.96.36.199 supports a configurable retry mechanism for some error codes from Box API. The configuration is accessible from the following location:
|The user can adjust the number of retry attempts.
The default setting is 3. This can be modified, if required.
|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.