This article will guide you through importing user data from CSV to BioStar 2 database via BioStar 2 API.
Part 1.
There are a couple of steps that needs to be done before importing user data from CSV via BioStar 2 API.
Part 1-a.
First, you need get the list of user fields that is on the BioStar 2 server which can be processed as CSV columns.
The following API is used to list all user fields that are on BioStar 2.
GET /api/users/csv_option
After you run the API successfully, you'll receive a 200 HTTP status code with a response body that contains a list of all the user fields on BioStar 2 like below. These values will be used later on in this article.
Part 1-b.
Next, you need to upload the csv file to the server install path.
The following API is is used to upload a file (.csv or .tgz) to BioStar 2 Server Installation path, so that the file can be further processed for importing user data to the database.
POST /api/attachments
Uploaded file will be located in {{BioStar 2 Installation Path}}\nginx\html\downloadIf there's a file with the same name, it will be overwritten. [Body form-data]
file: csv file to upload
If you successfully run the API, you'll receive a 200 HTTP status code with a response body that has the 'filename'.
This 'filename' value will be used later on in this article.
At this point, you have successfully uploaded the csv file to the BioStar 2 server install path !
Part 2.
Now, we are ready to import user data from csv.
The following API imports user data from a .csv file to the BioStar 2 database.
POST /api/users/csv_import
[Body Parameters]
| Parameter | Type | Required | Description |
|---|---|---|---|
| File:fileName | String | Y | File Name of the .csv file. Input 'filename' value from the response body of POST /api/attachments |
| File:uri | String | Y | Put the same value as above |
| CsvOption:start_line | Number | Y | Specify row number to start data import |
| CsvOption:import_option | Number | Y | Options when same ID exist in Biostar 2 1 = Preserve Data 2 = Overwrite Data |
| Query:columns | Array | Y | List of fields on BioStar 2. Use GET /api/users/csv_option to get this list |
| Query:headers | Array | Y | List of fields on .csv file. The order of these fields should match to the corresponding user fields in Query:columns |
* For 'File:fileName' and 'File:uri', use 'filename' value from the response body of POST /api/attachments.
* For 'Query:columns', use 'rows' value from the response body of GET /api/users/csv_option.
* Fields listed on Query parameter are used for field mapping between .csv file and BioStar 2 database.
For example, the first field listed on Query:headers (.csv) will be matched with the first field of Query:columns (BioStar 2).
* To change this mapping, adjust the sequence on Query:headers as desired.
* To skip a field from mapping, put empty string("") on the intended field.
* Number of fields in 'Query:headers' should match the number of fields in 'Query:columns'. If you do not have the fields in the csv file, just put empty string("").
* If the CSV file to import contains data for custom user fields and the fields do not exist on the server, then the data for the fields will be ignored during the import process.
[Example Request Body]
{
"File": {
"uri": "testing.csv",
"fileName": "testing.csv"
},
"CsvOption": {
"start_line": 2,
"import_option": 2
},
"Query": {
"headers": [
"user_id",
"name",
"department",
"user_title",
"phone",
"email",
"user_group",
"start_datetime",
"expiry_datetime",
"csn",
"secure_credential",
"access_on_card",
"mobile_start_datetime",
"mobile_expiry_datetime",
"csn_mobile",
"qr",
"26 bit SIA Standard-H10301",
"HID 37 bit-H10302",
"HID 37 bit-H10304",
"HID Corporate 1000",
"HID Corporate 1000 48bit",
"face_image_file1",
"face_image_file2",
"pin",
"tom_aoc",
"tom_scc"
],
"columns": [
"user_id",
"name",
"department",
"user_title",
"phone",
"email",
"user_group",
"start_datetime",
"expiry_datetime",
"",
"",
"",
"",
"",
"",
"",
"",
"",
"",
"",
"",
"",
"",
"",
"",
""
]
}
}
If there aren't any issues on the import process, the API will should "Success" response.
[Example Successful Response Body]
{
"Response": {
"code": "0",
"link": "https://support.supremainc.com/en/support/home",
"message": "Success"
}
}
If there are issues (duplicate email, etc.), the response will show "Request is successful but partially" and will include a filename that contains records which caused the errors. This file can be downloaded by using GET /download/:csv_filename
If there are errors preventing the import process such as incorrect datetime format, the API call will fail and you'll receive an error code.
