Automatic CSV Import

Getting Started With Automatic CSV Import

Employee App

Front Door Intranet

Staffbase offers a more advanced (new) CSV Import feature. Staffbase recommends switching to this new beta feature for advanced capabilities and better user experience.

User Management via automatic CSV import is one of the easiest and most scalable ways to manage your users on the Staffbase platform. The functions and capabilities that the automatic CSV import offer are the same as that of the manual CSV import performed in the Staffbase Studio. The only difference is that the script runs automatically on a schedule eliminating or reducing manual efforts. Similar to manual CSV import, for automatic CSV import, you need to actively push or upload the CSV file from your local environment to the Staffbase platform. You can do this with upload and update requests to the Staffbase endpoints. These calls are always performed in succession for the automatic CSV import.

Staffbase supports both complete and partial CSV automatic imports. The implementation for both processes is similar. If you use the partial CSV import, you need to define the partialImportTag parameter for it in the code.

Contact support@staffbase.com to enable partial CSV import for your organization before implementing it.

Use this guide to get started with the automatic CSV import. The examples provided in the instruction use the command-line.

If you are using PowerShell for automating your CSV import, contact support@staffbase.com to receive template scripts for using PowerShell v5 or higher.

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.
You have a good understanding of the manual CSV import via the Staffbase Studio.

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

Upload: HTTP POST request to /users/import/csv/upload with the CSV file specified.
Optional Preview: HTTP POST request to /users/import/csv/update with dry=true.
Update: HTTP POST request to /users/import/csv/update with dry=false.

In this guide, the following CSV file is used:

External ID;First Name;Last Name;Email;Position;Department;Hire Date
A00123;John;Smith;john.smith@company.com;IT Manager;IT;01/05
A00124;Rosie;Jones;rosie.jones@company.com;Sales Representative;Sales;01/05

You can find more CSV file examples on our Support Portal.

Make an HTTP POST request to the endpoint: /users/import/csv/upload with the following details:

Parameter	Description
Host	The base URI for the hosting infrastructure on which your app is hosted.
Authorization	The API token to authorize the upload and update requests.
CSV	The path of the CSV file in your local environment.
Encoding	The character encoding used in the CSV file. Allowed values: `windows-1252` `utf-8`
Field separator	The field separator used in the file to separate the values. Allowed values: comma (`,`) semicolon (`;`) pipe (`\|`)
Partial import tag	The parameter for the partial CSV import. This is required only if you want to implement a partial CSV import.

The following cURL-command uploads a new CSV file named users_example.csv from the current directory, prettyprints the response (using json_pp) and stores it in upload.json.

curl 'https://exampleapp.staffbase.com/api/users/import/csv/upload' \
  -X POST \
  -H 'Authorization: Basic TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'csv=@./users_example.csv' \
  -F 'encoding=utf-8' \
  -F 'fieldSeparator=";"' \
  # optional parameter for partial import:
  -F 'partialImportTag="csv_import:importTag"' \
  --compressed | json_pp > upload.json

For debugging purposes, inspect the upload.json.
For example, if you are using Linux environment, inspect the dry_run.json with cat dry_run.json.

{
   "rowCount" : 2,
   "total" : 7,
   "columns" : [
      "External ID",
      "First Name",
      "Last Name",
      "Email",
      "Position",
      "Department",
      "Hire Date"
   ],
   "data" : [
      {
         "title" : "External ID",
         "rows" : [
            "A00123",
            "A00124"
         ]
      },
      {
         "title" : "First Name",
         "rows" : [
            "John",
            "Rosie"
         ]
      },
      {
         "title" : "Last Name",
         "rows" : [
            "Smith",
            "Jones"
         ]
      },
      {
         "title" : "Email",
         "rows" : [
            "john.smith@company.com",
            "rosie.jones@company.com"
         ]
      },
      {
         "title" : "Position",
         "rows" : [
            "IT Manager",
            "Sales Representative"
         ]
      },
      {
         "title" : "Department",
         "rows" : [
            "IT",
            "Sales"
         ]
      },
      {
         "title" : "Hire Date",
         "rows" : [
            "01/05",
            "01/05"
         ]
      }
   ]
}

Map the CSV attributes to the Staffbase Studio profile fields and upload the file to Staffbase using the HTTP POST method to the endpoint /users/import/csv/update.

On the CSV Import Mappings page you can find an overview of available attributes in the platform and how to map them with your CSV file.

You can map one column from your CSV file to multiple fields. For example, identifier maps the externalId and userName based on the same column.

Use the following parameters to:

Display preview: Set the parameter dry to true in the code to display a preview. It is important to preview and test your mapping before the actual import to avoid incorrect syncs.
Send emails or generate recovery codes: The following parameters are optional. By default, all three parameters are set to false.

sendMailsNew: Sends invitation emails to new users
sendMailsPending: Resends invitation emails to existing pending users
generateRecoveryCodes: Generates recovery codes for all users in the CSV file

While you can choose between English and German for the email invitation when manually creating a user in the Staffbase Studio, this is not the case with a CSV import.

When users are initially created via automatic CSV import, they will have the default content language (locale) of the platform.
When users are initially created via manual CSV import, they will have the content language (locale) of the admin performing the import.

The email invitation is sent based on the user’s content language. If the user’s content language isn’t English or German, there is a fallback for the invitation to English.

curl 'https://exampleapp.staffbase.com/api/users/import/csv/update' \
  -X POST \
  -H 'Authorization: Basic TOKEN' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'mappings=externalID,profile-field:firstName,profile-field:lastName,eMail,profile-field:position,profile-field:department,profile-field:hiredate' \
  -d 'sendMailsNew=false' \
  -d 'sendMailsPending=false' \
  -d 'generateRecoveryCodes=false' \
  -d 'dry=true' \
  --compressed | json_pp > dry_run.json

Preview the CSV to check all the changes you’re about to make are correct. The preview contains all the changes, such as created, updated, or deactivated users. In addition it may contain, warnings or errors, if any. For example, if you are using Linux environment, inspect the dry_run.json with cat dry_run.json.

{
   "allChanges" : {
      "A00123" : {
         "eMail" : {
            "new" : "john.smith@company.com",
            "old" : null
         },
         "importTags" : {
            "new" : [
               "csv_import:importTag"
            ],
            "old" : []
         },
         "locale" : {
            "new" : "en_US",
            "old" : null
         },
         "profile-department" : {
            "new" : "IT",
            "old" : null
         },
         "profile-firstName" : {
            "new" : "John",
            "old" : null
         },
         "profile-hiredate" : {
            "new" : "01/05",
            "old" : null
         },
         "profile-lastName" : {
            "new" : "Smith",
            "old" : null
         },
         "profile-position" : {
            "new" : "IT Manager",
            "old" : null
         }
      },
      "A00124" : {
         "eMail" : {
            "new" : "rosie.jones@company.com",
            "old" : null
         },
         "importTags" : {
            "new" : [
               "csv_import:importTag"
            ],
            "old" : []
         },
         "locale" : {
            "new" : "en_US",
            "old" : null
         },
         "profile-department" : {
            "new" : "Sales",
            "old" : null
         },
         "profile-firstName" : {
            "new" : "Rosie",
            "old" : null
         },
         "profile-hiredate" : {
            "new" : "01/05",
            "old" : null
         },
         "profile-lastName" : {
            "new" : "Jones",
            "old" : null
         },
         "profile-position" : {
            "new" : "Sales Representative",
            "old" : null
         }
      }
   },
   "created" : {
      "data" : [
         {
            "config" : {
               "locale" : "en_US"
            },
            "created" : "2021-06-21T10:00:00.000Z",
            "emails" : [
               {
                  "value" : "john.smith@company.com"
               }
            ],
            "externalID" : "A00123",
            "profile" : {
               "avatar" : null,
               "department" : "IT",
               "firstName" : "John",
               "hiredate" : "01/05",
               "lastName" : "Smith",
               "location" : null,
               "phoneNumber" : null,
               "position" : "IT Manager",
               "publicEmailAddress" : null
            },
            "role" : {
               "type" : "reader"
            },
            "status" : "pending",
            "tags" : [
               "csv_import:importTag"
            ],
            "updated" : "2021-06-21T10:00:00.000Z"
         },
         {
            "config" : {
               "locale" : "en_US"
            },
            "created" : "2021-06-21T10:00:00.000Z",
            "emails" : [
               {
                  "value" : "rosie.jones@company.com"
               }
            ],
            "externalID" : "A00124",
            "profile" : {
               "avatar" : null,
               "department" : "Sales",
               "firstName" : "Rosie",
               "hiredate" : "01/05",
               "lastName" : "Jones",
               "location" : null,
               "phoneNumber" : null,
               "position" : "Sales Representative",
               "publicEmailAddress" : null
            },
            "role" : {
               "type" : "reader"
            },
            "status" : "pending",
            "tags" : [
               "csv_import:importTag"
            ],
            "updated" : "2021-06-21T10:00:00.000Z"
         }
      ],
      "total" : 2
   },
   "deactivated" : {
      "total" : 0
   },
   "deleted" : {
      "total" : 0
   },
   "updated" : {
      "total" : 0
   },
   "userExternalIDToEmail" : {
      "A00123" : "john.smith@company.com",
      "A00124" : "rosie.jones@company.com"
   },
   "userExternalIDToNotificationEmailAddress" : {
      "A00123" : "john.smith@company.com",
      "A00124" : "rosie.jones@company.com"
   },
   "errors" : [],
   "infos" : [],
   "warnings" : [],
   "newEmailInvitesCount" : 2,
   "pendingEmailInvitesCount" : 0
}

See also the CSV Import References page to help you analyze your CSV import and get more information on potential warning and error codes.

After testing the mapping, you can set the parameter dry to false and import the file.

Use the example request code snippet from step 2 and modify the dry parameter.

curl 'https://exampleapp.staffbase.com/api/users/import/csv/update' \
  -X POST \
  -H 'Authorization: Basic TOKEN' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'mappings=externalID,profile-field:firstName,profile-field:lastName,eMail,profile-field:position,profile-field:department,profile-field:hiredate' \
  -d 'sendMailsNew=false' \
  -d 'sendMailsPending=false' \
  -d 'generateRecoveryCodes=false' \
  -d 'dry=false' \
  --compressed | json_pp > dry_run.json

Schedule the imports and updates based on your business requirements. 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.

It is recommended to check the state of your CSV import periodically to ensure everything is working as expected. This can also help if you want to run multiple partial imports in succession.

A HTTP GET request to the /users/import/csv/latest endpoint will return information on the latest import. The response will contain the completed and running parameters that will describe the state of the import.

The combination of these parameter’s values will provide you with the status of the import.

Parameter Values	Import State
`completed: true` `running: false`	Status: Completed Import is complete and the system is ready for another import.
`completed: false` `running: true`	Status: In Progress The import is currently running on the system.
`completed: false` `running: false`	Staus: In Preparation The first step (/users/import/csv/upload) of the import was completed and the second step (/users/import/csv/update) has not yet been started. The current import must be either completed by running the second step of the process or removed.

The system will be ready for a new import when the status is Completed. If the parameters describe an In Progress or In Preparation status, a new import cannot be started.

Automatic CSV Import

Prerequisites

Import process overview

1. Step: Upload the CSV file

Example request

Example response

2. Step: Map the attributes and preview the import

Example request

Example response

3. Step: import the file

Example request

Schedule the imports

Check the status of the latest import