User Documentation

  1. Home
  2. Docs
  3. User Documentation
  4. Inventory of Materials and Methods
  5. Batch register entries in a Collection

Batch register entries in a Collection


It is possible to register several samples at once via file upload. Two methods are currently available:

  1. Batch registration via Excel template file (XLS Batch Register Objects)
  2. Batch registration via TSV template file (TSV Batch Register Objects)



In openBIS versions prior to 20.10.6, the XLS batch registration is not recommended to register several hundreds of entries. The use of the TSV batch upload to register several hundreds of entries is recommended in those cases.


Batch registration via Excel template file 


To register several entries of the same type with an Excel file:

  1. Navigate to the relevant collection (e.g. Samples).
  2. Select XLS Batch Register Objects from the More drop-down menu (see figure above)
  3. Download the template file and fill in the relevant information. (Example file: SAMPLE-COLLECTION-REGISTRATION-SAMPLE-STORAGE_POSITION-template)
  4. Upload the file.




In most cases, Object types have the option to auto-generate codes set to true in the admin UI. In this case, openBIS automatically generates codes and identifiers when Objects are registered. If that is not the case, the code needs to be manually entered by the users in the Excel template. The current template does not have a Code column. This can however be manually added if codes should be provided by the user and not automatically generated by openBIS.  If codes should be manually entered and are missing, openBIS will show the error message “UserFailureExceptionmessage: Code cannot be empty for a non auto generated code.” 


Controlled vocabularies


For Controlled Vocabularies fields, i.e. fields with a drop down menu, you can enter either the code or the label of the terms in the Excel file.

Please note that codes are not case-sensitive, but labels are.

Codes and labels of vocabulary terms can be seen under Utilities -> Vocabulary Browser.


Assign parents


  1. Assign already existing parents


If the parents you want to assign to your Objects are already registered in openBIS, in the Parents column of the Excel file, you can assign the relationship, by providing the identifier of the parent (i.e. /SPACE code/PROJECT code/OBJECT code). If you want to add multiple parents to one Object, every identifier should be in a new line in the corresponding Excel cell. A new line in an Excel cell is entered with the keyboard shortcuts Alt + Enter.



 Note: no other separators (e.g “,” or  “;”) should be used, otherwise an error will be thrown.


2. Register Objects and assign parents in the same batch registration process. 


If you want to register a few Objects and at the same time establish a parent-child relationship between some of them, you can do so by using the $ and Parents columns. In the example below we want to register 2 Objects, antibody 1 and antibody 2. We want to assign antibody 1 as parent of antibody 2. In the $ column corresponding to antibody 1 we need to enter numbers or letters proceeded by the $ symbol (i.e. $1, or $parent1). In the Parents column of antibody 2, we need to use the same value used in the $ column for antibody 1.




Date format

For date fields, the expected format is YYYY-MM-DD.


Register storage positions and samples in the same XLS file


A sample and its storage position can be registered together, as shown in the template provided above:


  • The info in the $ column of the sample spreadsheet should match the Parents column in Storage Positions spreadsheet. In the $ column you can enter numbers or letters proceeded by the $ symbol (i.e. $1, $2 or $parent1, $parent2).


Batch registration via TSV template file


  1. Select TSV Batch Register Objects from the More drop-down menu
  2. Select the Object type (E.g. Sample or Storage)
  3. Download the template file and fill in the relevant information
  4. Upload the file


Rules to follow to fill in the template .tsv file


  1. Identifiers:
    1. Identifiers are given by /SPACE code/PROJECT code/OBJECT code, e.g /MATERIALS/EQUIPMENT/INS1. Users can provide their own identifiers, or these can be automatically generated by openBIS.
    2. To have identifiers automatically generated by openBIS, completely remove the identifier column from the file.
  2. Lists. In fields that have lists to choose from (called Controlled Vocabularies), the code of the term needs to be entered. Term codes can be seen under Utilities -> Vocabulary Browser.
  3. Parents. Use the following syntax to enter parents: identifier1, identifier2, identifier3.
  4. Parents annotations. Use the following syntax to annotate parents: identifier:xxx;COMMENTS:xxxx\identifier:yyy;COMMENTS:yyyy. Where COMMENTS is the property used for the annotation in this case (to be replaced with the actual property used).
  5. Date fields. The expected syntax for dates is YYYY-MM-DD.


Advantages of XLS batch registration vs the old batch registration


  1. XLS batch registration uses labels instead of codes in the column headers in the template file.
  2. Fields which are Controlled Vocabularies can use labels instead of codes.
  3. The template can be used as it is, and no modifications are necessary by removing the identifier column, as it was in case of the old batch registration.
  4. Upload of samples and storage positions can now be performed using single template file. 


The old batch register mode is being maintained for backward compatibility and will be phased out.