Self-Serve File Import

Self-Serve File Import

The new Self-Serve File Import tool allows you to import data into ClientSuccess - anytime, on-demand!  Admins can access the Import tool in “Global Settings > Data Exports/Imports” as shown below:

Key features include:

• Import Clients, Contacts, Products, NPS Surveys, and Usage data
• Contract Revenue data imports are not quite ready for complete self-serve, but can be imported once reviewed by our Support or Services team
• File templates are accessible right within the tool and help guide you through the data fields that are required for import
• Field legends provide a list of valid columns, labels, descriptions and tips for the type of data that is required 
• Import Preview displays the data that will be imported for validation prior to importing

Note: Please reach out to your CSM if you would like to import Contract data using the Self-Serve File Import tool.

Importing Data

File imports require careful preparation of data to avoid updating or replacing unintended data. Each row in the file represents a ‘record’ in ClientSuccess and requires a reliable and unique key (or set of keys) to match existing records in ClientSuccess.  Where a match exists the record in ClientSuccess will be updated with the fields included in the file.  Where a match does not exist a new record will be created in the system using the fields included in the file. 

There are 4 primary ways that a record can be identified:

1. ClientSuccess Id - the id assigned to that record that is already in ClientSuccess. This id will never change and is unique per record. If this field is provided this id must be VALID and is REQUIRED. This key will not create new objects in ClientSuccess as this ID cannot be set by the tenant.
2. ClientSuccess UUID - the UUID assigned to that record that is already in ClientSuccess. This id will never change is unique per record. If this field is provided this id must be VALID and is REQUIRED. This key will not create new objects in ClientSuccess as this ID cannot be set by the tenant.
3. External Id - This id is defined by the tenant based on the data in their own system or a 3rd party system. This id must be unique within ClientSuccess and can be set/updated via integrations, API, or from within the UI.
4. Natural Keys - These id’s vary by object type in ClientSuccess but represent naturally available identifiers for records that are in most cases unique. Examples included client names, contact email addresses, etc. The record type template will show which options are available for that record.

Note: to allow flexibility in how import files are processed some columns exist twice in the import specification - once as an ‘id’ lookup and once as a data field. This allows for record matching without updating the value in ClientSuccess but does mean that in some cases the column may need to be duplicated in the file in order to both match the object AND update it.

Getting Started

The import process has 5 steps: Download Template, Upload file, Match data , Review, and Complete.

Let’s start with a simple example for Client records in ClientSuccess that has both updates and creates using the External Id to identify records in the ClientSuccess system.

1) Download New Template

Please use the new template generator to get a template for each import. This should be the first step of a new import and will prevent any issues that you may experience using old templates. (Please do not attempt an import without using a newly generated from the Self-serve File import tool.) This may require a lot of upfront work, but it will have long-term benefits for any other future imports.

Note: This template used the tenant defined External Id field and requires this column to be duplicated as both a ‘lookup’ field (_id.externalId) and a data field ‘externalId’. This will result in proper identification and assigning the external id value to the record for future reference. IF the external id is being set from a different source (UI, integration, etc) and an only an update is desired the data column may be omitted. If a row is provided for an external Id that does not exist a new client will be created.

2) Upload

This step allows for selection of the file that will be processed from the support file types. 

3) Match

The match step allows for selecting a header row and mapping columns in the file to fields in the system.

Note: If the system detects a file format that it has seen before it might skip header selection as an optimization.  Columns can be mapped, ignored, or even corrected during this step. This step also gives some indications of data quality and helps map list columns to valid types from the ClientSuccess system.

Each column must be confirmed or ignored to continue to the Review step.

4) Review

The review stage shows the status of each row and whether or not it meets the validation requirements of the system. This step also allows for inline correction of data.

The import tool will also attempt to share whether the provided lookup ID will result in an update to an existing object in the system or a new object being created.

It will also show issues with ID’s that will result in the row not being able to be processed. In the example below the ID’s provided are not in ClientSuccess so they cannot be processed. By updating the ID’s those rows can be resolved during this step instead of needing to go back the the file and make updates.

After correction has been made:

Once all edits and review has been completed - continue to the next step. Only valid rows will be allowed to proceed to the next step.

5) Complete

Once submitted the status of the file import can be monitored from the import page as the system processes it.

 

Imports List

The imports list shows the status of imports that have been submitted to the system. The file that was submitted can also be downloaded for easy edits and corrections if needed.

By selecting an import a detailed summary of the processing that occurred can be reviewed. For our example above two records were successfully updated.

 

This should get you started importing your customer data.  Please reach out to your CSM or our support team support@clientsuccess.com with any questions.