Box is a cloud storage service provided by Box Inc. Metadata is supplementary information about the file itself and can be used to search for files or aggregate scattered files. (Available for Business Plus, Enterprise, and Elite accounts only.)

This article describes Questetra’s automated process for adding metadata to Box files.

1. About Box Metadata

There are two ways to add Box metadata to a file.

The first is to prepare a metadata template in advance. By entering values for template items (keys), uniform metadata common to all files is added.

The second method is called custom metadata. Metadata is added by entering keys and values.

It is possible to add both metadata templates and custom metadata to a single file.

Box Support: Using Metadata

Questetra’s automated process only supports the above method of preparing metadata templates in advance; you need to prepare the templates in advance in Box, so please create them from Box’s Admin Console.

Box Support: Customizing Metadata Templates

2. Questetra’s Auto-Steps

Questetra has added a built-in automatic process to automatically add the above Box metadata to files. (Available in Ver. 14.1~, Advanced Edition and above)

This auto step, [Box: Add Metadata to File], can be used to automatically add metadata to a file specified by the Box ID.

Box: Add Metadata to File

Adds metadata to a file on Box using a metadata template defined within the company. If the specified metadata template has already been added to the file, an error will result. Up to 8 attributes in a templateare supported.

 

Box Metadata Template Settings and Questetra Settings

Box metadata is assigned in the form of one value per item. A metadata template is a package containing as many of these items as necessary. Templates are created by the Box infrastructure administrator and used by users.

When creating/editing templates, items are referred to as “attributes” and are described as “add/delete attributes” or similar. Each attribute must have a name, and the string specified in the name is the key of the item.

Attributes come in several formats, and the format of the value entered depends on the format, like Questetra’s Data Items and data types.

In Questetra’s auto-step the Box template is invoked and input values are specified for each attribute key set in the template, and metadata is added to the specified file. The input values are set to follow the format of the target attribute.

3. Box and Questetra Integration Settings

Configure authentication settings for integration with Box.

Please refer to the article Using Box to Send Files to People Outside the Company for specific instructions on how to set up Box.

4. Sample App

In the “File Registration” step, files are registered and values are set for each attribute to be added as metadata. In the “Create Folder” step, a folder is created in Box, and in the “Upload Files” step, the specified files are uploaded to this folder. Metadata is added to the files in the last automatic step. Adding metadata enhances future searchability.

Workflow App Settings

Data Items

Data Item NameData TypeField NameRequired“File Registration” processDescription
TitleEditableProcess Title.
FileFile-typeq_fileEditableAdd files to be uploaded.
Folder IDString-type (single line)q_folder_idNo DisplaySave the ID of the folder created in the “Create Folder” process.
File IDString-type (single line)q_file_idEditableSave the ID of the file created in the “File Upload” process.
Upload Username ValueString-type (single line)q_user_nameEditableThe value to be entered in the template key “Upload User Name”. Select “Process Start User” from “Insert Reference…” for [Initial Value] and set #{processInstanceInitQuserName}.
Process ID ValueNumeric-typeq_process_idEditableThe value to be entered in the key “Process ID” of the template. Select “Process ID” from “Insert reference…” for [Initial value] and set #{processInstanceId}.
Process start date valueDate-type (YMD)q_start_dateEditableThe value to be entered in the template key “Process Start Date. Under Default Value, select “Process Start Date” from “Insert Reference…” and set processInstanceStartDatetime.
Work Status ValueSelect-type (select box)q_status_choiceEditableThis is the value to be entered for the key “Work Status” in the template. This time, we will set three fixed choices with choice IDs of “New File”, “Work in progress”, and “Finished product”, and the display label will be the same as the choice ID. Specify “New File” as the initial value.
Data Item Settings

Create Folder Step

First, register the files to be shared in the “File Registration” process. Metadata values are automatically entered as initial values.

In the subsequent Create Folder step (see “Box: Create Folder”), a folder for sharing is created on Box.

Item NameRequiredDescription
C1: OAuth2 SettingSpecify the OAuth2 setting to be used to connect to Box. The OAuth2 settings you specify must have a token obtained in advance (see “Box and Questetra Integration Settings”).
C2: Parent Folder IDUse the ID to specify in which folder the new folder will be created. Let’s leave it blank this time and specify the root folder.
C3: Folder name to createSpecify the name of the folder to be created. In this case, let’s use “#{processInstanceId}“. The “#{processInstanceId}” part contains the Process ID, so there will be no duplication with other folders created by this application.
C4: Data Item that will save Folder IDSpecify the Data Item to which the generated folder ID will be saved. In this case, specify the Folder ID.
C5: Data Item that will save Folder URLSpecify the Data Item to which the URL of the generated folder will be saved. This time, it is not specified.
Box: Create Folder」Settings

Upload Files Step

In the Upload Files step, registered files are uploaded to the folder where they were created.

Item NameRequiredDescription
C1: OAuth2 SettingsSpecify OAuth2 settings to be used for connection to Box. The OAuth2 settings you specify must have a token obtained in advance (see “Box and Questetra Integration Settings”).
C2: File type data item whose attached files will be uploadedSpecify the Data Item “File” that contains the file to be uploaded.
C3: Folder ID that file will be uploaded (Root folder if blank)Specify the ID of the folder where the uploaded file will be saved. If you select “Folder ID” from “Insert reference…”, #{#q_folder_id} will be inserted.
C4: String type data item that will save uploaded file idsSpecify the Data Item to which the ID of the uploaded file will be saved. Insert #{#q_file_id} by selecting the File ID from the Insert reference…
C5: String type data item that will save uploaded file urlsSpecify the Data Item to which the URL of the uploaded file will be saved. Not used in this case.
Box: Upload File Settings

Add Metadata to File Step

The Add Metadata to Files step adds metadata to files uploaded to the folder. Specify the name of the template to be used, and specify the data items for which each key (attribute name) and its input values are to be stored.

Item NameRequiredDescription
C1: OAuth2 SettingsSpecify the OAuth2 setting to be used to connect to Box. The OAuth2 settings you specify require a token to be obtained in advance (see “Box and Questetra Integration Settings”). The following is a list of OAuth2 settings to be used for connection to Box.
C2: File ID to add metadata toC2: Specify the Data Item “File ID” to store the file ID to which metadata is to be added.
C3: Display Name of Metadata TemplateSpecifies the name of the template created in the Box.
C-K1: Display Name of Field 1Specify the name of the attribute for the first item in the template. In this case, specify “Upload User Name”.
C-V1: Value for Field 1This is the input value for the first item in the template. Insert #{#q_user_name} by selecting the Upload Username Value from the Insert reference…
C-K2: Display Name of Field 2Specify the name of the attribute for the second item in the template. In this case, specify “Process ID”.
C-V2: Value for Field 2This is the input value for the second item in the template. Insert #{#q_process_id} by selecting the Process ID Value from the Insert reference…
C-K3: Display Name of Field 3Specify the name of the attribute for the third item in the template. In this case, specify “Process Start Date”.
C-V3: Value for Field 3This is the input value for the third item in the template. Insert #{#q_start_date} by selecting the Process start date value from the Insert reference…
C-K4: Display Name of Field 4Specify the name of the attribute for the fourth item in the template. In this case, specify “Work Status”.
C-V4: Value for Field 4This is the input value for the fourth item in the template. Insert #{#q_status_choice} by selecting the Work Status Value from the Insert reference…
Leave ‘C-K5: Display Name of Field 5’ and after blank.
Box: Add Metadata to File Settings Items
  • If a String-type (multi-line) Data Item is specified as a text format attribute and a string value including line feeds is entered, it will be entered as a single line string delimited by blanks
  • If input values other than numbers and decimal points are specified for numeric format attributes, the auto step will result in an error.
  • Only the format yyyy-MM-dd can be entered for date format attributes
    • Automatic process errors will occur if Datetime-type or Process Start Time is entered without modifying
  • Only strings that exactly match the options can be entered in the drop-down attribute
    • If there is no matching option, the auto step will fail
  • This time, a Data Item with an initial value is specified by reference in the “Value for Field n” config item.
    • If you do not need to or do not want to change the input values in the “File Registration” process, specify a direct reference expression for the config item.

Reference: Box Template Setup

Here are the settings for the template we will be using.

Template Name: Test Template
Attribute NameFormOptionVisible / Hide
Upload User NameTextVisible
Process IDNumberVisible
Process Start DateDateVisible
Operation StatusDropdown – Single Selection
  • New file
  • Work in progress
  • Finished product
Visible

Appendix: Configuration using auto-input TIPS

The information that should be added as metadata varies widely, depending on the business unit and the nature of the file being uploaded. Please create your template with careful consideration of the information required.

On the other hand, there is also information that is common to any business. In particular, there may be cases where the same information/value is added every time in the same business. In such cases, the burden on the worker can be reduced by using automatic entry in a creative way. Here are some examples of how automatic input can be used.

Process-initiating User

In Box, the executing user is automatically recorded when a file is newly uploaded. However, all files uploaded by Questetra’s auto-steps will be uploaded by the authenticated user of the auto-step.

To use the name of the user who actually performed the upload operation as the input value for metadata in text format, specify [Process Start User] as an EL expression in the “Field Values” section of the Auto-step Settings screen.

#{processInstanceInitQuserName}

(Select “Process Start User” from [Ξ+ Insert Reference…] in the settings screen and set to insert)

Process ID

If you add the ID of the Questetra process (the numeric part of p123456) when the file is uploaded to the metadata of the Box file, the linkage between Questetra and Box will be more robust. For example, it will be possible to search a Box file by a Questetra process ID, or to search a Questetra process from a Box file.

#{processInstanceId}

(Select “Process ID” from [Ξ+ Insert Reference…] on the settings screen and set to insert.)
The numeric part of the Process ID will be entered as the template value, so specify “numeric” for the attribute format.

Process Start Date

Box automatically records the creation date (new upload time). However, in an actual workflow there may be cases where a file is uploaded several steps after the process starts. In this case, the process start date and time would be easier to search than the upload date and time (auto-step processing date and time).

Care must be taken when using a date format input value for the process start date and time. The input value for the template’s date expression has a specified format (yyyy-MM-dd) and an EL expression using “Insert by reference…” will result in an error. Set it to automatically process by rewriting it as:

#{processInstanceStartDatetime} (output yyyy-MM-dd HH:mm )

#{#dateFormatter.format(‘yyyy-MM-dd’, processInstanceStartDatetime)}

Note that if processInstanceStartDatetime is set as the initial value for a Date-type (YMD) Data Item, this conversion is not necessary because the Data Item format (yyyy-MM-dd) is followed.

 See also

%d