SFTP CSV File Imports

An SFTP server is available to enterprise plan users at no additional cost, providing a secure method for bulk importing data into Agility Blue. After connecting to the SFTP server, you can upload CSV files to designated folders monitored by the system. The folder you choose determines which object the data will be imported into—detailed instructions are provided below.

While importing data ad hoc is a common use case for uploading bulk information, the SFTP server is often used with automation tools to upload client, matter, and contact data on a scheduled basis, ensuring your information stays synchronized with matter management systems.

Connecting to the SFTP Server

For our enterprise customers, an SFTP CSV file import service is available . Contact support@sadiebluesoftware.com to request the credentials needed to connect to your instance.

Protocol: SFTP – SSH File Transfer Protocol
Port: 22
Logon Type: Normal/UserPass
Username, password, and host information will be provided by support.

Once connected, you will see a list of folders representing the objects where CSV files can be uploaded and imported.

Notice

All SFTP connections are initially tested using WinSCP and FileZilla clients though you may use any client that supports the ability to connect to an SFTP service. Please note that while we can’t train or troubleshoot the use of these third-party clients, we will make sure you can get connected to the service.

Example: Connect to the SFTP Using the FileZilla Client

To connect to the SFTP using the FileZilla client, first make sure that you have FileZilla installed on your computer. You can find the latest version here.

After FileZilla has been installed, run it and click on the Site Manager button. This is the first button on the toolbar. Once the site manager is open you will see the following:

• For Protocol, select "SFTP - SSH File Transfer Protocol"

• For Host, enter in your specific host address that was provided to you by support

• For Port, you can leave it blank, or put in 22 (the default port)

• For Logon Type, select "Normal"

• For User, enter in your specific username that was provided to you by support

• For Password, enter in your specific password that was provided to you by support

Click on the "Connect" button. You may be presented with a "Unknown Host Key" window the first time you connect to your SFTP. If you do, click on the checkbox labeled "Always trust this host, add this key to the cache" and click the OK button to continue.

You should now see the following folders in the center bottom panel:

You have now successfully connected to the SFTP and can proceed to drag and drop your CSV files from your computer into the appropriate folder on the SFTP. Continue reading the existing sections for detailed information about the file format the SFTP service accepts.

General Import Guidelines

The CSV file may be named however you want to name it, It’s the folder the file is uploaded in that determines where they get imported. The CSV files do need headers with the field names. The service is setup to use the RFC-4180 standard with UTF-8 file encoding to import Quote-Comma delimited CSV files.

• The service will not create references to other objects that don’t exist. For example, clients must already exist within the system in order to import matters that reference them.

• Custom fields need to be named exactly as they appear within Agility Blue and must already exist before importing them. The service will not create fields that don't already exist.

• Blank entries are interpreted as NULL values by the system.

• Quotes around values are required if there are quotes or commas as part of the value itself. For example, the following value: ABC, Inc. (An “Alphabetical” Company) would need quotes around it: “ABC, Inc. (“Alphabetical” company)”.

• Clients need to exist before importing new matters, so be sure to upload the clients file first. The system will queue files in the order they are uploaded and will perform imports one at a time.

• The service will also not create references of any objects other than the one being imported into. Task, project, matter, or client references must already exist when other objects reference them.

• Multiple choice values must be separated with an escaped newline character: \n

• The service will create new entries or update existing entries based on the guidelines set forth for the object you are importing data into.

• When creating new entries, fields that are omitted will be Null unless explicitly stated in the object’s field table.

• When updating existing entries, fields that are omitted will be ignored. This allows you to patch-update specific fields in your CSV without having to worry about affecting the values of fields you aren’t providing.

Reference Fields

You may import data into Reference fields using the following guide:

• Values can only be referenced by their unique Agility Blue ID (the “Id” column in the app).

• The IDs of the values being referenced must already exist within Agility Blue. If a value does not exist, it will be ignored.

• Duplicate values are removed prior to import.

• Existing values are replaced when updating data.

• Multiple values must be separated with an escaped newline character: \n

The sample image below shows a "Billing Contacts" custom field that references the contact object. The values 12 and 28 within the data represent the Agility Blue Ids for two different contacts that already exist within the system. The last three records showcase how multiple values can be imported with the \n separator.

The results of this import in Agility Blue for the billing contacts field:

Folder Details

The following folders are available for you to import your data into. Each object has their own set of guidelines and rules to follow, so be sure to review them prior to uploading your file to help avoid issues from cropping up during the process.

$logs

The $logs folder is used by the system to place daily log files of activity. This is the place to go to check on the status of an import and to perform any troubleshooting. Any errors that ocurred during the import will be listed in the log file.

$processed

The $processed folder is used by the system to place previously processed files. Import files are held for up to 7 days and then removed.

billingentries

The billingentries folder is where you may place a CSV file that contains billing entry records.

CSV required fields to create new records:

• "Billing Type Id" (Number-based), OR "Billing Type Billing Code" (Text-based), OR "Billing Type Description" (Text-based - The global billing type description, not an overridden profile description)

• "Unit Price" (Decimal-based)

Optional fields:

• "Client Id" (Number-based)

• "Client Name" (Text-based)

• "Client Reference" (Text-based)

• "Matter Id" (Number-based)

• "Matter Name" (Text-based)

• "Matter Reference" (Text-based)

• “Project Id” (Number-based).

• "Task Id" (Number-based).

• "Date" (Date-based).

• "Quantity" (Decimal-based).

• "Billing Type Description Override" (Text-based).

• "Narrative" (Text-based).

• "Notes" (Text-based).

• Any custom fields defined for the object.

Rules:

• If updating an existing billing entry, the "Billing Entry Id" field must be provided (a system-generated id in Agility Blue).

• If the billing type needs to be updated on an existing billing entry, be sure to include the Billing Type Id field. If you only have the billing type code or description, each billing type id field should be empty or set to 0.

• To associate a billing entry with an existing client, provide one of the following fields:

  • Client Id (a system-generated id located in Agility Blue)

  • Client Name

  • Client Reference

• If the client needs to be updated on an existing billing entry, be sure to include the Client Id field. If you are only providing the client name or reference, each client id field should be empty or set to 0.

• To associate a billing entry with an existing matter, provide one of the following:

  • The Matter Id (a system-generated id located in Agility Blue)

  • The Matter Name

  • The Matter Reference

  • The Client Id + The Matter Name (2 separate fields)

  • The Client Name + The Matter Name (2 separate fields)

  • The Client Reference + The Matter Name (2 separate fields)

  • The Client Id + The Matter Reference (2 separate fields)

  • The Client Name + The Matter Reference (2 separate fields)

  • The Client Reference + The Matter Reference (2 separate fields

• If the matter needs to be updated, be sure to include the Matter Id field. If you are only providing the matter name or reference, each matter id field should be empty or set to 0.

• To associate a billing entry with an existing project, the Project Id field must be provided (a system-generated id in Agility Blue).

• To associate a billing entry with an existing task, the Task Id field must be provided (a system-generated id in Agility Blue).

• If multiple association levels are present (client, matter, project, and task fields), the order of priority is bottom-up, meaning the task fields will get the highest priority.

• If any provided association is not found or more than one instance is found for the association, the billing entry will not be created or updated and an error will be issued for the record.

clients

The clients folder is where you may place a CSV file that contains client records to import using the following field table.

Guidelines

• The system requires that all client names must be unique.

• When updating existing clients, you may provide either the Client Name field or the Client Reference field to locate an existing entry.

Example

Client Name,Client Reference,Client Address,Status
AGM Widget Corporation,1024,"123 Main Street, Somewhere, USA",Active
Frederick Construction Co,1025,"555 Everywhere, Nowhere, USA",Held
Omega Glass Company,1026,,Archived

Points of interest related to this example

• There are 2 custom fields defined on the client object that we are importing data into (shown in purple text above for clarity): Client Address (a rich text field), and Status (a single choice field).

• For the 3rd entry (Omega Glass Company), the Client Address field will be imported as Null, because there is no text being provided.

• Note that the Client Address field is surrounded by double quotes because the value contains commas (shown more clearly on the Text tab).

contacts

The contacts folder is where you may place a CSV file that contains contact records to import using the following field table.

Guidelines

• The system requires that all email addresses must be unique.

• When updating existing contacts, you must provide the Email Address field to locate an existing entry.

Example

Email,First Name,Last Name,Office Location,Skills
abutler@abdemo.com,Adele,Butler,Minneapolis,1
dtayler@agilitybluedemo.com,Donna,Taylor,Dallas,1\n2

Points of interest related to this example

• There are 2 custom fields defined on the contact object that we are importing data into (shown in purple text above for clarity): Office Location (a single choice field), and Skills (a custom object reference field).

• The Skills object reference field requires the Id to reference the objects. For multiple values, a \n (escaped new-line character) must separate the them. In the example, the custom object Skill has Document Review for entry Id 1 and Analytics for entry Id 2. For more details, read the section on Reference fields.

customobjects

The customobjects folder is where you may place a CSV file that contains custom object entry records to import using the following field table.

Guidelines

• The required Object Id field is used to determine which custom object the data belongs to. This value should be the same for every record in the CSV (do not mix and match object ids). To locate your object id within the app within your workspace: click on the settings gear icon on the top right navigation bar, and choose Objects. Ensure that the Id field is in view - this will be the value you use for each CSV record.

• This folder is only for creating/updating custom object entries. Do not try to use system object ids - it won't work.

• If updating existing custom object entries, the Id field must be provided (a system-generated id in Agility Blue). No other fields may be used to identify an existing custom object entry.

Example

Object Id,Name,Notes,Locations,Media Log Entries
14,Mary White,"Custodian Imported on 1/1/2025",MN,62
14,Casey Copeland,"Custodian Imported on 1/1/2025<br />Imported by R.C.W.",MN\nFL,13\n14

Points of interest related to this example

• In this example, we’ve created a custom object in Agility Blue named Custodian that has been assigned an object id of 14. We’ve created the following fields:

  • Name, a basic text field that we indicate as the reference link field.

  • Notes, a rich text field to store information about a custodian.

  • Locations, a multiple choice field used to indicate where a custodian resides.

  • Media Log Entries, a media log entry reference field where we link media log entries that a custodian is associated with.

• Note that we are using the same object, 14, for each record in the CSV to tell Agility Blue which custom object it is we’re interested in importing data into.

• On the second record (Casey Copeland), for the notes field, you may notice the text <br /> - this is an HTML line break character that causes the browser to show information on a separate line. Rich text fields may contain some HTML to help format data.

• The multiple choice Locations field requires a \n (escaped new-line character) to separate the values.

• The media log entry object reference field requires the Id to reference the objects. For multiple values, a \n (escaped new-line character) must separate the them. For more details, read the section on Reference fields.

matters

The matters folder is where you may place a CSV file that contains matter records using the following field table. The service does not create clients that do not already exist, so it's important to import clients first so that they exist for the matters to reference.

Guidelines

• The system requires that all matter names are unique per client, meaning you may have the same matter name across different clients but you cannot have duplicate matter names on the same client.

• Because matters require an existing client to be associated with. You may provide any one of the following fields. If this field is not provided, or the client does not exist, an error will be logged.

  • Client Name

  • Client Reference

  • Client Id

• When updating existing matters, you may provide either the Matter Name field or the Matter Reference field to locate an existing entry.

Example

Matter Name,Matter Reference,Client Name,Status,ESI Protocol Available,Billing Contact Email
AGM Widget Corp. vs. MGM Manufacturing Inc.,000001,AGM Widget Corporation,Open,Yes,abutler@abdemo.com
Moonrise vs. Johnson Analytics,000001,Frederick Construction Co,Open,Yes,dtayler@agilitybluedemo.com
"National Fencing v. Epsilon Construction, et al.",000002,Frederick Construction Co,Open,No,econnor@agilitybluedemo.com

Points of interest related to this example

• There are 3 custom fields defined on the matter object that we are importing data into (shown in purple text above for clarity): Status (a single choice field), ESI Protocol Available (a yes/no field) and Billing Contact Email (a basic text field).

• We are providing the Client Name field to associate these matters with to the existing clients in the system.

• Note that the Matter Name field is surrounded by double quotes for the 3rd entry (National Fencidng v. Epsilon Construction, et al.) because this value contains commas (shown more clearly on the CSV tab).

medialogentries

The medialogentries folder is where you may place a CSV file that contains media log entry records.

CSV required fields to create new records:

• "Media Type Id" (Number-based) OR "Media Type Name" (Text-based)

Optional fields:

• "Client Id" (Number-based)

• "Client Name" (Text-based)

• "Client Reference" (Text-based)

• "Matter Id" (Number-based)

• "Matter Name" (Text-based)

• "Matter Reference" (Text-based)

• "Project Id" (Number-based)

• "Task Id" (Number-based)

• "From" (Text-based)

• "To" (Text-based)

• "Reference" (Text-based)

• "Location" (Text-based)

• "Custodian" (Text-based)

• "Notes" (Text-based)

• "Date" (Date-based)

• Any custom fields defined for the object.

Rules:

• Any combination of system fields may be used for the purposes of updating existing media log entries.

• If the media type needs to be updated on an existing media log entry, be sure to include the MediaTypeId field. If you only have the media type name, each media type id field should be empty or set to 0.

• To associate a media log entry with an existing client, provide one of the following fields:

  • Client Id (a system-generated id located in Agility Blue)

  • Client Name

  • Client Reference

• If the client needs to be updated on an existing media log entry, be sure to include the ClientId field. If you are only providing the client name or reference, each client id field should be empty or set to 0.

• To associate a media log entry with an existing matter, provide one of the following:

  • The Matter Id (a system-generated id located in Agility Blue)

  • The Matter Name

  • The Matter Reference

  • The Client Id + The Matter Name (2 separate fields)

  • The Client Name + The Matter Name (2 separate fields)

  • The Client Reference + The Matter Name (2 separate fields)

  • The Client Id + The Matter Reference (2 separate fields)

  • The Client Name + The Matter Reference (2 separate fields)

  • The Client Reference + The Matter Reference (2 separate fields

• If the matter needs to be updated, be sure to include the MatterId field. If you are only providing the matter name or reference, each matter id field should be empty or set to 0.

• To associate a media log entry with an existing project, the Project Id field must be provided (a system-generated id in Agility Blue).

• To associate a media log entry with an existing task, the Task Id field must be provided (a system-generated id in Agility Blue).

• If multiple association levels are present (client, matter, project, and task fields), the order of priority is bottom-up, meaning the task fields will get the highest priority.

• If any provided association is not found or more than one instance is found for the association, the media log entry will not be created or updated and an error will be issued for the record.