› Modules and plugins › Export module › Box Export plugin

Box Export plugin

This topic describes how to configure Transact to export batch files and metadata to the Box repository from Transact, with the following elements of deployment:

  • Prerequisites for using the Box Export plugin

  • Setting up the Box repository application

  • Configuring the BOX_PLUGIN plugin in Transact

  • Executing a batch with files exported to the Box repository

  • Referring to common system messages (error codes) and support

This topic includes configurations and steps to be completed on the Box website, which can be updated without warning at any time. If you try to follow the steps and notice the Box website UI no longer matches the information provided in this section, contact the support team for assistance.

Prerequisites

  • Ensure that Transact is installed and licensed, with an administrator account
  • Ensure that a Box administrator can access and configure Box storage outside of Transact

Create and configure a New App

  1. Navigate to https://developer.box.com.
  2. Log in to the Box account with the credentials in which the developer application is to be created.
  3. Create a new developer application by clicking Create New App.

    • If you are creating your very first Box app, the Welcome screen appears.

    • If you already have Box apps created, the Box application screen appears.

  4. On the Create a New Box App page, select Enterprise Integration and click Next to proceed.
  5. On the next page, set the authentication method to OAuth 2.0 with JWT (Server Authentication) and click Next.
  6. Provide the name of the application (the name should be unique) and click Create App.

    Once the unique app name is provided, the confirmation page is displayed.

    You are also provided with the developer token, which remains valid for one hour and can be used to make the first API call for a new app.

  7. Click View Your App.

    The App Configuration page appears. It includes the same developer token shown on the previous page, which can be used for testing the app.

  8. Under the Application Access, select Enterprise.
  9. Under the Application Scopes, confirm that the properties are defined as shown in the following image.

    Box Developers properties

  10. Under the Advanced Features, enable both options: Perform Actions as Users and Generate User Access Tokens.
  11. Under the Add and Manage Public Keys section, click Generate a Public/Private Keypair.

    This downloads a JSON file with the Box connection details (that are used in Transact during the Box plugin configuration), and the confirmation message is displayed.

    This JSON file contains the following Box app settings:

    • clientID

    • clientSecret

    • publicKeyID

    • privateKey

    • passphrase

    • enterpriseID

    You may be prompted to complete a 2-step verification with one-time password sent to the phone number that you used to register. To set up 2-step verification, see Enable 2-step verification.

  12. Click Save Changes.

Authorize 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 authorization, the warning message that you must authorize the application appears in the Transact UI when trying to access the app.

To authorize the app:

  1. On the navigation panel, select the Admin Console (https://app.box.com/master) and click Enterprise Settings.
  2. Navigate to the Apps section, scroll down to Custom Applications and click Authorize New App.

    A dialog box appears in which you must provide the clientID from the JSON file downloaded earlier.

  3. Enter the clientID value in the API Key field and click Next.
  4. In the App Authorization pop-up window, click Authorize.

    If all configurations have been done correctly earlier, the authorization should be granted to All Users.

    If you get the Only App Users of this App option instead, review the steps above and update the settings that require modifications.

    If you make any changes to your dev app, you need to reauthorize it. To reauthorize your app, click the ellipsis (…) button under Actions for the corresponding app and select Reauthorize app.

Enable 2-step verification

  1. On the Navigation panel, click Settings to open the Account Settings screen.
  2. Under the Authentication section, enable Require 2-step verification for unrecognized logins.
  3. When the Enable Login Verification dialog appears, provide the required information and click Continue.
  4. Enter the Confirmation Code and click Continue.

    The system returns to the Account Settings screen.

  5. Click Save Changes.

Configure the BOX_PLUGIN plugin in Transact

To configure export from Transact to the Box repository:

  1. Create or open your batch class.
  2. Configure document types and index fields.
  3. In the Export module, add the BOX_PLUGIN plugin.

    You can drag and drop it from the Associated Plugins to the Selected Plugins list, or use the right arrow to move the selected plugin to the Export module.

    Ensure to place BOX_PLUGIN plugin before the CLEANUP plugin and click Apply to save the changes.

  4. On the BOX_PLUGIN Configuration screen, select ON.
  5. Expand the BOX_PLUGIN drop-down list and select Configure.
  6. To add a new configuration, click Add.

    The Box Mapping Configurations screen appears.

  7. In the first section, select Document Type and Connection Type.

    The Connection Type options become enabled only after you select the Document Type.

  8. After you select the Connection Type, the Connection Details section appears.

    Provide your connection details here.

    This section offers two types of environments:

    Two Environment Types

Environment type - Production

In a production environment, Transact uses the JSON file obtained from the Box platform, which contains all required details for a secure connection. This connection is configured and established on a permanent basis as required for production.

  1. Select 0 - Production as your environment type.
  2. Provide the Connection Name.
  3. Click Browse JSON and upload the JSON file generated by Box when creating the dev app.

    Client ID, Client Secret, Enterprise ID, Public Key ID, Private Key, and Passphrase fields are automatically populated once the file is uploaded.

    Provide either your Login ID (email address that you use to log in to Box) or the User ID (see Box > My Apps > <Your App> > General > App Info).

  4. Click Connect.

If all provided details are correct, the confirmation message is displayed, and the Export Details and Document Attributes sections become available.

Environment type - Test

In a test environment, Transact uses the developer token generated by Box for a selected application. This token is valid only for one hour. Thus, this configuration is temporary and is provided to test the connection and Box export functionality.

  1. Select 1 - Test as your environment type.
  2. Provide the Connection Name.
  3. Provide the Developer Token (see Box > My Apps > <Your App> > Configuration > Developer Token > Generate Developer Token).

    If the provided details are correct, the confirmation message is displayed, and the Export Details and Document Attributes sections become available.

  4. Click Connect.
  5. Fill in the Export Details section.
    Configurable property Description

    File Type

    The type of the files to be exported. Available options are: PDF (default), TIFF, PDF_TIFF. Set this value so that it matches the value of the Multipage File Creation Type property in the CREATEMULTIPAGE_FILES plugin. This property must be set to the same value in both the plugin and this screen.

    Folder ID

    The target folder number as defined in the Box repository. The folder ID value can be seen in the browser URL when the user is inside the desired folder. Set this value to 0 if you want to export the files to the root directory.

    File Name

    The name of the exported file (as it appears in the Box repository). The name can be static or dynamic. To define the dynamic name, select available options by using the dollar sign ($) and &<symbol>& as a separator, for example, &_&. The file name should always end with an ampersand (&).

    File Description

    The description of the exported file (as it appears in the Box repository). The description can be static or dynamic. To define the dynamic name, select available option(s) by using the dollar sign ($) and &<symbol>& as a separator, for example, &_&. The file description should always end with an ampersand (&).

    The following example demonstrates that both static and dynamic values can be combined in the file name/description. "Lorem Ipsum" can be any static text combined with dynamic placeholders:

    • Lorem Ipsum&_&$BATCH_IDENTIFIER&_&$DOCUMENT_ID&

    • $BATCH_IDENTIFIER&_&Lorem Ipsum&_&$DOCUMENT_ID&

  6. Fill in the Document Attributes section.
    Configurable property Description

    Attribute Key

    The name of the custom metadata field in Box*.

    Attribute Value

    The value to be exported into the custom metadata field in Box*. This value can be static or dynamic. To see the list of available options, expand the drop-down or enter a dollar sign ($) in the field.

    *View metadata details in the bottom-right corner after you open the file in Box.

  7. Click Apply to save your changes.

Manage BOX_PLUGIN configurations

All saved configurations are displayed on the Configuration screen:

  • To add a new configuration, click Add.
  • To edit an existing configuration, select it and click Edit.
  • To copy an existing configuration and use it for another document type, select it, click Copy, and choose the document type from the drop-down list.
  • To delete any configuration, select it and click Delete.
  • To exit the BOX_PLUGIN Configuration screen, click Close.

Use cases

Export files to multiple Box folders

To export files and metadata to multiple Box folders:

  1. Create a BOX_PLUGIN configuration record as explained above.
  2. In the Configuration screen, select the new configuration and click Copy.
  3. Select the appropriate document type and click OK.
  4. Open the copied configuration and change the Folder ID in the Export Details section as required.
  5. Click Apply to save your changes.

Export files with the same name to the same Box folder

The Box API supports version control. When a file is exported to a Box folder that already contains a file with the same name, the exported file is saved as a new version of the existing file.

When viewing a list of files in Box, a label is shown that displays the current version number of each document:

Example of Version Control with Files

Box error codes

The detailed information about Box error codes and solutions is available on the Box website.

Troubleshooting

Fix 400 system error

If there is a discrepancy between the time zone settings for the Transact system and the Box repository, the user may receive the following 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, this error appears.

To fix this error, follow these steps:

  1. Update the Unix time on your machine to match the Unix time available at the Unix Time Stamp website.
  2. Retry your request to generate the App User access token.

Box API retry functionality

Transact supports a configurable retry mechanism for some error codes received from the Box API.

The configuration is accessible from the following location:

<Ephesoft Transact Installation Directory>/Application/WEB-INF/classes/META-INF/dcma-box-plugin/dcma-box-plugin.properties

Box API retry functionality

Configurable property Description
box.api.max.retry.attemps

The number of retries that the system performs to export the documents and metadata to Box if it encounters errors specified in the box.api.retry.statusCode parameter. The default value here is 3.

box.api.retry.interval

The interval between the retry attempts in milliseconds. The default value of this parameter is 2000.

box.api.retry.statusCode

The list of error codes for the retry mechanism. Four error codes are provided by default (408, 409, 429 and 0), however, this parameter can be modified as needed to account for any other possible errors listed on the Box website.