Using ISPyB to manage samples is mandatory when using the sample changer since the software only supports importing sample information through ISPyB. Even for experiments that do not involve the sample changer, it is strongly recommended to use ISPyB to ship samples to MAX IV. If this is not possible for whatever the reason, refer to the
general shipping instructions.

Note: You are responsible for organizing the courier for the transport, however ISPyB will assist in generating all the paperwork related to shipping, including shipping and return labels with the correct address and information, organising the samples and communicating with MAX IV as of the status of the dewars.

This is a step-by-step guide to show how to ship samples to MAX IV. Click on each of the following links to display information for each step.



Users with scheduled beamtime at MAX IV can log in to ISPyB at any time to set up a shipment.

  • Please log in with your MAX IV account (the same one used to log into DUO).
  • Please select the role you want to use (usually “user” is the only option)
  • Please select the proposal you want to use

The first step to set up the shipment is to assign a contact from your home laboratory. This is the person whose name will appear in the shipping labels and who will receive notifications about the dewar. This step is not required if you will transport the dewar to MAX IV yourself.

  • On the top menu bar, go to Lab-contacts

    If your contact is already in the list:

    • Click on the “card name” (in the first column) to select the name of a contact person from your home lab and verify that all the information is up to date.

    If your contact is NOT already in the list:

    • On the left hand side menu, choose “Create → LabContact”
    • Search your name
    • Please fill in full details of your address, how to reach you and courier details of current shipment! The proper address is important to ensure the dewars arrive back safely to your home institute.
    • Save the card


The next steps are to generate the ID and shipping labels for your dewars, list the containers in the dewars and notify BioMAX staff. Although you may bring dewars to MAX IV yourself, declaring the shipment in ISPyB is necessary to enter the required sample information to use the sample changer.

  • Choose “Create Shipment”

Fill in the shipment details. The information of this form will generate an ID label used to identify your dewar at MAX IV and two shipping labels, one for sending the dewar to MAX IV and another one for returning. Note: Even if you are using your own shipping labels, or bringing the dewar to MAX IV yourself, it is important to attach the ID label to the dewar to avoid misindentification while at MAX IV.

  • The value for the “label” entry will appear as the name of the dewar in the shipment list and the ID label. If you ship many dewars, choose names that are meaningful to you and will let you identify each dewar easily.
  • The number of dewars you enter in the form will be automatically updated if you add dewars or other components to the shipment later on.
  • Select the contact person or persons in your home lab. This information is required even if you use your own shipping labels, since this is also the contact for notifications about the shipment.
  • Save the entered information.
  • If you wish to review or edit the information after saving the form contents, click on “View shipments” in the left hand side menu. That will show a list of your shipments. Click on the edit icon in the leftmost column in the list to reopen the form.

After saving the form, you will be redirected to the shipment components screen, showing your shipment details.

  • Click on the “Print component labels” icon under the Component labels column to ensure that the information on the labels is correct. If not, go back to “Lab Contacts” tab and revise the information.
  • If everything is correct, print the labels.
  • If needed, add up more dewars to the shipment by clicking on the “Add a Component to this shipment” link. You will have to fill the displayed form to generate a label for each dewar.
  • After filling up the information for each of the dewars, you can go list all the dewars created by clicking on “View all Components in this Shipment”.
  • Create the list of samples that you are sending in the shipment as described in the following section.
  • Choose “Send Shipment to MAXIV” in left corner to process the dewars with printed labels (you can also add more dewars later if you wish and process them separately).Note: Although it will still possible to make changes or add samples after clicking the “Send shipment” button, despite the warning in ISPyB, you will not be able to do this anymore once the dewar is at the beamline. If you fail to list the correct sample information in advance of the beamtime, you will have to create another shipment for this purpose.
  • Fill in the shipping date and the estimated arrival date for the shipment and save. The Component status should be “Sent to MAXIV” on the shipment information list. This will let beamline staff know that the shipment is on its way.
  • Please attach the dewar label and the shipping label on your dewars, and enclose the return label within the dewar box.


You can enter the container and samples present in the shipment after setting up the dewars as described in the previous section and before you send the shipment to MAX IV. If you are sending crystals of a new protein, it is important that you create an entry for the protein under the “Samples” tab in the top menu first; you will not be able to upload or save information from an unknown sample.

The simplest way to enter the sample information is to set up all the dewars in the shipment first and then use the “Upload Shipment from Excel file” or “Fill Shipment online” from the Shipment components page, but you can also do this for each dewar separately. The following points are applicable regardless of the chosen method:

  • For the puck name, pick the label or name printed on the puck itself, in order to prevent mismatches between the position of the pucks in the sample changer dewar and the position assigned in the software. We strongly advice not to send unlabeled pucks, unless the samples are barcoded.
  • The protein acronym can be selected from a drop down list containing all the names you have declared in the “Samples” tab.
  • The sample name is used for the dataset name and it must be unique for each sample, to avoid files being overwritten.
  • Other fields may be used as information to characterize the sample or calculate the strategy, but they may not be in use. Please contact staff if you want to know if a field is currently being used or not by the processing software.

Fill Shipment online

  • Select the dewars and pucks from the tabs in the edition bar. You may also add more containers interactively.
  • Click on the “Change sample name automatically” button to autofill the sample name after the protein acronym has been selected.
  • Use the copy and paste icons in the rightmost Action column to paste input fields onto several rows.

Upload Shipment from Excel file

  • Download a Excel template with prefilled sheets for each dewar (up to seven pucks per dewar). NOTE! Currently the Dewar_1_n tabs are write protected, so in order to write you need to right click on the tab, deselect the protect sheet function and provide password: “ispyb”.
  • Fill up at least the compulsory information (in red) for all the sample present in each puck and save the spreadsheet as an xls file.
  • Upload the file. If there are any errors, correct the spreadsheet and upload it again.

After the data collection is done and dewars are complete:

  • Fill up the dewar(s) with more liquid nitrogen if needed, enough to last until return of dewars. MAX IV staff handling the dewars will dry them prior to shipping.
  • Attach the return label you printed out together with the initial label to the dewar(s).
  • Put dewar in the designated area outside BioMAX (“Dewar departure point”).
  • Arrange the transport back with your courier company.
  • Let the Delivery department (Godsmottagningen, phone number as written on the printed out dewar labels) know 1. dewar bar code 2. expected pickup time.
  • In case of unexpected delay of return sending, put the dewar in the waiting area, “Dewar not ready for departure”, and notify your Local Contact to make an agreement.