Export and Import Attachment Files with the Command Line Tool

Contents

Overview

This article introduces how to download and upload attachment files to records in Kintone Apps using cli-kintone.

How to Download Files from Attachment Fields

Attachment files can be downloaded using the following command.

1
cli-kintone --export -a APPID -d FQDN -t APITOKEN -b <Directory to save attachment file(s)>

The -b option must be used to specify the directory to save the file in. If the specified directory does not exist, it will be created as a new directory. The API token specified with the -t option is sufficient with just the “view” permission. Refer to the API Tokens article for more information about API tokens.

Structure of the download directories

Downloaded files are stored in directories with the following structure:

  • Files in an Attachment field

    Screenshot: The file structure when in a regular attachment field.

  • Files in an Attachment field inside a Table

    Screenshot: The file structure when in an attachment field inside a table.

How to Upload Files to Attachment Fields

Check the format of the attachment field by exporting a CSV file

The following command lets the user check the output format of attachment files being exported with the -b option. This exported CSV file can then be used as a template to prepare a CSV file for uploading other attachment files. Since the purpose is to confirm the output format only, the -c option is used to limit the number of fields to be output. This makes the exported information easier to understand.

1
cli-kintone --export -a APPID -d FQDN -t APITOKEN -b <Directory to save attachment file(s)> -c "<Field code of record number field>,<Field code of attachment field>" > <Directory to save csv>\<CSV Name>.csv

The following CSV file is exported when the field code of the attachment file is attachments and the field code of the record number field is Record_number.

1
2
3
4
"Record_number","attachments"
"1","attachments-1/1-1.png
attachments-1/1-2.png"
"2","attachments-1/2-1.png"

In this example, 1-1.png and 1-2.png exist in record number 1, and 2-1.png exists in record number 2.

The paths to the exported attachment files are noted inside of the CSV file relative to the directory that was specified with the -b option. If multiple attachment files exist in a single record, the paths will be separated with line breaks in the CSV file.

Retrieve the files in an Attachment field inside a table by specifying the field code of the table with the other field codes.

Add records with attachment files

The Expense Report app from the Kintone Marketplace (External link) is used in the following examples.

STEP 1 Prepare a CSV file for adding records

First, create a local directory called “Attachments” that will contain files for the attachment file uploads. Place a file named “receipt.pdf” into the directory. Next, create a CSV file with the data shown below:

1
2
"*","expense_code","business_purpose","employee","expense_date","description","category","amount","attachments"
"*","11120","Test","Krispy","2017-06-30","Train","Transport","200","receipt.pdf"
tips
Note

Exporting a CSV file to create a template for inserting data may help reduce formatting errors for CSV files.

To add multiple attachment files, enter in the paths to the attachment files separated by line breaks. For example, adding a file called sample.xlsx to the record would look like the following.

1
2
3
"*","expense_code","business_purpose","employee","expense_date","description","category","amount","attachments"
"*","11120","Test","Krispy","2017-06-30","Train","Transport","200","receipt.pdf
sample.xlsx"

Finally, save the file as “add_record_with_attachments.csv”.

caution
Attention

When creating a CSV file by reusing and adding additional information to a file exported with cli-kintone, make sure to format the CSV file such that the line break character codes are consistent.

When handling multiple attachment files, importing a CSV file created with more than one type of line break character code may fail when importing.

When exporting, cli-kintone saves the CSV file so that the line break codes are in CRLF format. However, if the CSV file is exported using the redirection operator, the line break portion of the attachment file may be changed to LF. Be sure to check the format of the line breaks in the file before importing.

STEP 2 Import the CSV file

Once the CSV and attachment files are ready, the record can be imported by running the following command:

1
cli-kintone --import -a APPID -d FQDN -t APITOKEN -e sjis -f add_record_with_attachments.csv -b Attachments

The imported record should look like the image below.

Screenshot: An example of the record inside of a Kintone App.

caution
Attention

Note that importing duplicate values for the Expense Code field may return errors. This is due to the “Prohibit duplicate values” settings being checked for the Expense Code field.

Update records with an attachment file

In this section, the record that was registered with attachment fields in the previous section will be updated.

STEP 1 Prepare a CSV file for updating records

Refer to Update Records with the Command Line Tool to prepare a CSV file for updating records. Any attachment files that are already inside of the record but are not specified in the CSV file to update the record will be deleted. Because of this, it is recommended to keep backup of the files stored in the records in advance. Additionally, saving the CSV file to use as a template at the same time will save time by eliminating the need to run two commands.

1
cli-kintone --export -a APPID -d FQDN -t APITOKEN -b <Directory to save attachment file(s)>

Specifying ExpenseReport as the directory to store the attachment files will give the following results.

Screenshot: The attachment directory displayed in Windows.

The directory will be created and the attachment files that were registered to the record are saved.

Screenshot: The contents of the attachment directory displayed in Windows.

The existing attachment files are saved in the path, <destination directory>\attachments-10. Therefore, to add a new attachment file called sample2.docx to the record, add the path attachments-10\sample2.docx to the CSV file.

The completed CSV file is shown below, saved as update_record_with_attachments.csv.

1
2
3
4
"Record_number","attachments"
"10","attachments-10\receipt.pdf
attachments-10\sample.xlsx
attachments-10\sample2.docx"
STEP 2 Update the record

Now that sample2.docx was added to the CSV file, add the sample2.docx file to <destination directory>\attachments-10 and run the command.

1
cli-kintone --import -a APPID -d FQDN -t APITOKEN -e sjis -f update_record_with_attachments.csv -b <Directory to save attachment file(s)>

If the update is successful, it should look like the following:

Screenshot: The updated record displayed in Kintone.

The working directory should look like the following:

Screenshot: The updated working directory displayed in Windows.