---
last_review: "2025-01-01"
last_reviewer: "-"
documented_code: [ ]
---

```{tags} tutorial, developer
```

# Scripting with LinkAhead

In this tutorial, you will learn how to write a script to work with and update data from a LinkAhead
Server.

## Prerequisites

- You should know the basics of how to use the Linkahead Python client.
- You need a configured connection to a Linkahead Server.
    - Please download and run the 
      {download}`Setup Script</.assets/tests/tutorials/pylib/scripting/setup.py>` with
      a configured connection
      to ensure that all necessary RecordTypes, Properties, and example Records exist on your
      server.

### Scenario

The setup script linked in prerequisites populates LinkAhead with some example data, including
scientists and experiments. Before you continue with the tutorial, take a look at the new Entities.

Given a {download}`Data CSV</.assets/data/scripting_tutorial.csv>` containing data on faculties and
research groups, the goal of this tutorial is to update the existing data to include this additional
information. To achieve this, you will create a new Record for each research group, and update each
experiment Record to add the research group in charge of this experiment.

## Retrieving the relevant data

The data CSV contains a row for each research group, with the faculty it belongs to, and a list of
people working in this research group separated by semicolon. In the first step, create mappings
from person to research group and from research group to faculty:

```{literalinclude} /.assets/tests/tutorials/pylib/scripting/test_scripting.py
:start-after: "# ---- Parse CSV ----"
:end-before: "# ---- Update schema ----"
:language: python
:dedent:
```

## Updating the schema and data

Now that you have all the needed information, you need to update the servers schema to support
adding it to your Records. First, create a `ResearchGroup` RecordType with `faculty` property, for
your new research group Records:

```{literalinclude} /.assets/tests/tutorials/pylib/scripting/test_scripting.py
:start-after: "# ---- Update schema ----"
:end-before: "# Update experiment recordtype to have an associated research group"
:language: python
:dedent:
```

Then, update the `Experiment` RecordType to add a `responsible_group` property, which you will use
to link the research group responsible for this experiment:

```{literalinclude} /.assets/tests/tutorials/pylib/scripting/test_scripting.py
:start-at: "# Update experiment recordtype to have an associated research group"
:end-before: "# ---- Update with data from CSV ----"
:language: python
:dedent:
```

## Updating the experiments

To assign research groups to the experiments, they should first be created as Records in LinkAhead.
For each entry in the CSV, create a Record of the new `ResearchGroup` RecordType with the correct
name and `faculty` property, and insert it:

```{literalinclude} /.assets/tests/tutorials/pylib/scripting/test_scripting.py
:start-after: "# ---- Update with data from CSV ----"
:end-before: "# Retrieve all experiments which have an associated scientist"
:language: python
:dedent:
```

Now you can update your experiments. To do this, first retrieve all experiments which have a
`responsible_scientist` from the server. Then match each retrieved Record to its research group
based on the responsible scientist, and add it to the experiments `responsible_group` property.

```{literalinclude} /.assets/tests/tutorials/pylib/scripting/test_scripting.py
:start-at: "# Retrieve all experiments which have an associated scientist"
:end-before: "# ---- Validation ----"
:language: python
:dedent:
```

## Validating your results

Lastly, you can check whether there are any experiment which were not updated:

```{literalinclude} /.assets/tests/tutorials/pylib/scripting/test_scripting.py
:start-after: "# ---- Validation ----"
:end-before: "# ---- End test1 ----"
:language: python
:dedent:
```

As you can see, the only experiment without a responsible group is `Experiment_5`, which is the
experiment assigned to `Erwin Ehrlich`, who is not included in the list of scientists in the data
CSV. This might mean that the CSV must be updated to include more research groups, that
`Experiment_5` needs another responsible scientist, or that `Experiment_5` is not associated with a
research group.

## Further Reading

Synchronisation of complex structured data can be done automatically using the LinkAhead Crawler. To
learn more, continue in the crawler tutorials.

For further information about the Python client and its features, read
the [Features of Interest](/explanation/pylib/features_of_interest.md) document.