Manage Delta Imports Using the (New) CSV Import API

CSV Imports is one of the easiest ways to import and sync user data into the Staffbase platform. Using the (new) CSV Import API makes it even easier to automate data syncs and keep your constantly evolving user database up to date.

In this article, we’ll look at how to do a delta import using the (new) CSV Import API.

Delta import refers to imports that sync and update only a subset of your user base. This can be very useful in different scenarios. If you want to offboard users using delta imports, by deactivating or deleting their accounts, you need to specify the intended user status in the CSV file. To do this, you can add a column called Status_code in your CSV file and populate each user’s account status. For information on setting up the file, see the examples. You can add the following account statuses for users:

• Activated
• Deactivated

During the delta import, if deactivated status is added for:

• Pending user: The account is deleted.
• Registered user: The account is deactivated.

For example:

• Multiple branches or locations
  If you have various branches or locations for your organization, you can then perform a delta import to synchronize and update only the user data of that specific location. This way, only a subset of the user database will have their data synced and updated.
• Syncing new employees
  Most organizations have a consistent influx of new employees. In this case, you may only want to sync the data of the new employees and not touch the existing user data. This is another scenario where delta import can be helpful.

• You have enabled the (New) CSV Import for your platform.
• You have the user data in CSV file format.
• The identifier for each user is defined in the CSV file.
  If you already have existing users in the platform, ensure the identifiers are set and match the identifiers in the CSV file.
• You have generated an API token with administrative access via the Staffbase Studio. Learn more.

The process of performing an automated CSV import in a nutshell.

1. Upload a CSV file by sending the POST request to /users/imports/.
2. Configure the CSV file mapping by sending the PUT request to /users/imports/{importId}/config/.
3. Optionally, Preview the import changes by sending the PATCH request to /users/imports/{importId} with state parameter set to PREVIEW_PENDING.
4. Import the file by sending the PATCH request to /users/imports/{importId}. with state parameter set to IMPORT_PENDING.

Make a POST request to the endpoint /users/imports with the path of the CSV file in your local computer.

The following cURL command uploads a new CSV file from your local computer to your Staffbase platform.

Copy To Clipboard
1curl -X 'POST' \
2  'https://exampleapp.staffbase.com/api/users/imports' \
3  -H 'accept: */*' \
4  -H 'Authorization: Basic {Token}' \
5  -H 'Content-Type: multipart/form-data' \
6  -F 'file=@showcase_user_export_2024-03-06.csv;type=text/csv'

Your CSV file is uploaded to the Staffbase platform. You can view it in the overview page of the Staffbase Studio.

Do the following to map the CSV attributes to the Staffbase Studio profile fields:

1. Make a GET request to the endpoint /users/imports.

Copy To Clipboard
1curl -X 'GET' \
2  'https://exampleapp.staffbase.com/api/users/imports?limit=20' \
3  -H 'accept: application/json' \
4  -H 'Authorization: Basic {Token}'

Copy To Clipboard
1
2{
3  "entries": [
4    {
5      "id": "64b0fbf58e05e970f88a2791",
6      "createdAt": "2023-07-14T07:40:37.478Z",
7      "fileName": "mariokart_user_export_2023-06-14.csv",
8      "fileSize": 2010,
9      "recordCount": 8,
10      "state": "DRAFT",
11      "owner": {
12        "ownerId": "645de133f3e49f6b7f78cfff",
13              }
14    }
15  ],
16  "nextCursor": "NjU0YjU3ZDBhZTBjMmQzNTc2OTk3NTU4_dHJ1ZQ",
17  "prevCursor": " NjU0MzUxMjNmNmJiMzA0ZjRiZmEzOWYy_ZmFsc2U"
18}

2. Save the id from the response. This id is the importId required in the next step.

3. Make a PUT request to the endpoint /users/imports/{importId}/config/, with delta parameter set to true.

Copy To Clipboard
1curl -X 'PUT' \
2  'https://exampleapp.staffbase.com//api/users/imports/{importId}/config' \
3  -H 'accept: */*' \
4  -H 'Authorization: Basic {Token}' \
5  -H 'Content-Type: application/json' \
6  -d '{
7  "delta": true,
8  "encoding": "UTF-8",
9  "generateRecoveryCode": false,
10  "reportMailAddress": "recipient@company.com",
11  "reportOnlyErrors": false,
12  "sendMailsNew": true,
13  "sendMailsPending": true,
14  "separator": ";",
15  "mapping": {
16        "profile-field:firstName": "First Name",
17        "profile-field:lastName": "Last Name",
18        "externalId": "Identifier",
19        "profile-field:position" : "Position",
20 "status":"Status_code"
21         
22    }
23}'
24

See CSV Import error list to help you analyze your CSV import and get more information on potential warning and error codes.

After configuring the mapping, you can preview the file.

Make a PATCH request to the endpoint /users/imports/{importId}, with state parameter set to IMPORT_PENDING.

Copy To Clipboard
1curl -X 'PATCH' \
2  'https://exampleapp.staffbase.com/api/users/imports/{importId}' \
3  -H 'accept: */*' \
4  -H 'Authorization: Basic {Token}' \
5  -H 'Content-Type: application/json' \
6  -d '{
7  "state": "IMPORT_PENDING"
8}'

You can now schedule the imports and updates based on your business requirements using this CSV import workflow. You can use any scheduling tool of your choice. For example, if you're using the cURL command-line for Unix or Linux, you can use the cron job command for scheduling.