All the sample information and associated data at BioMAX is handled by ISPyB. ISPyB is also used to generate identifying labels for the dewars shipped to and from MAX IV. Creating a shipment in ISPyB with a complete list of Unipucks and samples is also necessary to use the sample changer at BioMAX, regardless of whether the samples are shipped or brought in person by the users. Every shipment should have a unique name. Including the experiment date in the name is helpful for frequent users to locate the shipment.

Below follows a step-by-step guide to show how to handle sample shipments to MAX IV. Click on each of the following links to display information for each step. You can also refer to this complementary video.


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 misidentification 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 containing the date of the experiment, as this will make it easy for you or staff to locate the shipment in ISPyB. Do not use reuse names for shipments, as this practice prevents the automated mapping of Unpipuck positions in the sample dewar to ISPyB.
  • 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.

  • Create the list of samples that you are sending in the shipment as described in the following section.

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, since you will not be able to upload or save information from an unknown sample. Note that so far samples previously declared in DUO are not automatically entered in ISPyB!. To enter a new protein in ISPyB, follow these steps:

  • Go to the Samples tab.
  • In the left hand side menu, select Create -> New sample.
  • If you or a collaborator in the proposal has entered any proteins, they will be listed in a table at the top of the page. If there are none listed or your protein is not present, click on the Create a new protein/crystal form link in the “Create a new sample” pane.
  • In the next page, click on the screate a new protein button.
  • Enter the protein acronym and protein name in the input box and click Save.
  • Next you will have the chance to enter and save the crystal form and crystal properties, however this information is not necessary to fill up the sample list.

Once your protein or proteins are declared in ISPyB, 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. We strongly recommend to use the excel sheets as it is easy to recover the filled in samples in case of problems later. 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 the 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.

  • 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”.
  • 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.
    • When the dewar arrives at MAX-IV, staff will scan the ISPyB label, and the shipment status will be set to “Arrived”.

Note: At BioMAX You are responsible for organizing the courier for the transport of both incoming and departing dewars. Please be prepared to order the return shipment before the beamtime, and be sure to attach the return papers from your courier to the dewar. ISPyB will generate some paperwork related to shipping, with useful information for dewar owners and internally at MAX IV, including a tag per dewar, please also attach those to the dewar. This is specially important for remote experiments. Failure to include all the required return paperwork will result in delays shipping the dewar back.

After the data collection is done, local users should de the following:

  • Attach the return address papers from your courier and the paper from ISPyB to the dewar(s)
  • Put dewar in the designated area outside BioMAX (“Dewar departure point”).
  • Please be aware you need to order courier yourself and please check that the return address is complete.
  • Let the Delivery department (Godsmottagningen, phone number as written on the printed out dewar labels) know that your dewar is ready for pickup.
  • In case of unexpected problems:
    • Place the dewar in the waiting area, “Dewar not ready for departure” and notify your Local Contact to make other arrangements.
    • 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.

For remote users, all the previous steps will be taken care of by staff, provided that you have enclosed the courier return papers in the dewar case.

If you are sending to and from outside EU and need customs declarations:

  • You need to fill in a Proforma invoice to send along with the shipment. This can be retrieved from DHL or from here: Pro Forma Invoice to MAX IV: customsDeclarationProForma_sendToMAXIV.pdf and Pro Forma Invoice from MAX IV: customsDeclarationProForma_returnFromMAXIV.pdf
  • Be sure to use a proper description of the content of the shipment, as an example: “Dry shipper containing small frozen protein crystals for scientific experiments. Crystals are non-hazardous. Dewar contains non-flammable gas (liquid N2).”
  • Value can not be 0, use a reasonable value.
  • The shipment address sheet from your courier and Proforma invoice need to be attached to the dewar(s)