# Functions

**LABDRIVE Functions** let you run code in the platform, in response to certain events or triggers, without needing any client-side script. They are similar to Amazon AWS Lambda functions.

Functions are useful when  **you want for the platform to behave in a specific way** in response to external events, or when you want to add your own code to be executed on demand by you.

With the LABDRIVE functions, you just upload your code and add the triggers you would like to make it execute. 

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MeP25MBz-GJCHWWVrdB%2F-MeP3-63SyebeEzNzFH3%2Fimage.png?alt=media\&token=cc9f0f9f-b5c8-4d82-8094-23fbf41c6c9a)

Users are able to define data container-level functions (*LABDRIVE functions*) that are executed on certain events:

* **CRUD Functions for files and metadata:** When files are **c**reated, **r**ead, **u**pdated or **d**eleted.

  E.g.: Every time you upload one of your astrophysics-related a file to a certain data container: 

  * Extract date, telescope, run, subrun, datatype, source, position, angle, etc from its file name or embedded metadata to the metadata catalogue, so it is searchable using the web interface or the API, 
  * Calculate each file integrity and 
  * Tag the ones in which the file name parameters do not match the embedded ones (PIC Magic Telescope)
* **Periodic functions:** Every minute, hour and day.  

  E.g.: Webhooks to other systems
* **Executed-by-demand functions:** When the user selects files using the GUI or launched using the API

  E.g.: For fetch.txt files containing a manifest of files to download, make LABDRIVE to download them and place them inside the container.

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MeP25MBz-GJCHWWVrdB%2F-MeP2txJUFh_5zyg_uuN%2Fimage.png?alt=media\&token=884e6f64-94dd-4563-bb9d-2e0816199b48)

This guide focuses in **the executed-by-demand functions** (the ones users manually trigger using the Management Interface or the API). See [Create lambda functions](https://docs.libnova.com/labdrive/get-started/broken-reference) to learn how to create your own functions.

## Real world example for a LABDRIVE Function

Let's say you have the following use case: You would like to perform a upload of your bagits. Then, you would like to perform an integrity verification to maintain the custody/integrity chain (to detect uploading errors) and finally, you would like to assign metadata to them.

There are multiple ways to achieve this behaviour in LABDRIVE, but this use case is a perfect example of combining **Workflows** and **Functions**. LABDRIVE Functions can be triggered by container's workflow changes, so it would be relatively easy to implement a 6 steps workflow:

**Upload content:** You would upload content to the container. Then, when your upload has finished, you would make a single API call (or use the Management Interface) to advance the container to the next status of the workflow. To do that, you can use the following API call:

```
  --url "$your_labdrive_url/api/container/{container_id}/step/next" \
  --header "Authorization: Bearer $your_labdrive_api_key" \
  --data ''
```

You upload your metadata as a file, as part of your package, as an Excel spreadsheet, for instance.

**Waiting for ingestion to finish:** A function will be triggered by the platform itself, that will wait for all files to be ingested. When this is completed, the function will move the container to the next status.

{% hint style="info" %}
To know if a container is still ingesting content that you have uploaded, look for the `files_pending_ingestion` property for the container. If `true`, LABDRIVE is still processing content.
{% endhint %}

**Integrity verification:** A function will be triggered by the platform itself, that will launch a bagit verification process. If the process is positive (your bags are fine), it will move the container to the “Assign metadata” steep. If not, to the “Validation errors detected”.

**Validation errors detected:** A function will send you an email, telling you the bags are not fine.

**Assign metadata:** A function will be triggered by the platform itself, that will assign all your metadata to your bags. Or, alternatively, it would wait for you to update it.

**Archive data:** A function will be triggered by the platform itself, that will launch the process to move all data to a cold storage.

You could achieve the same results using API calls client-side and managing this process in your code, but Functions deliver a more integrated approach, and allow other users to simply upload data without needing to perform scripting. As an additional benefit, you have integrated logging for the whole process, and your code performs better (as it is executed server-side).

With this approach, you would be uploading the content and making a single API call at the end of the upload.

## Launch functions using the Management Interface

1\. Locate the data container you would like to add metadata to using the **Containers menu** section or by searching. This guide assumes metadata is properly configured for the data container. See [Configuration\Metadata](https://docs.libnova.com/labdrive/configuration/metadata) for more details or [Working with data containers](https://docs.libnova.com/labdrive/get-started/working-with-data-containers) to see how to create them.

2\. Select **Check-in** in case you are not checked in the container and you have the check-in/out enabled for the data container.

3\. In the data container page, choose **Explore content**:

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MVaNm-XFEuXNvAq7xfZ%2F-MVaQrhG8X-H72fzbynC%2Fimage.png?alt=media\&token=392be951-cf87-455d-96ca-addd61a0e539)

4\. Select the file you would like to execute the function over and select the function you would like to launch in the sidebar:

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-Mb0_Ii2YzbdDUzLDpu6%2F-Mb0fRd3VQtgUSJVFzXw%2Fimage.png?alt=media\&token=7927ce0f-c425-44d6-9da3-bbe911ff55df)

It is possible to select multiple items using your mouse to **click-and-drag a box around the files or folders** that you want to select. You can also use **Ctrl** and **Shift** and use the **Select all**, **Select none** or **Invert selection** in the file browser top bar.

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MWblfdiNa2NYrnPRZo0%2F-MWbniJsyQt1RGN_zX21%2F2021-03-25_061443.gif?alt=media\&token=be279928-11bd-45eb-98b8-837af30362c4)

You can also **filter the files** in the folder you are looking at by file name, for instance, for selecting all XML or JPG files:

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MWblfdiNa2NYrnPRZo0%2F-MWbp-B7esiyOg0UfMnF%2F2021-03-25_062021.gif?alt=media\&token=1f28bc94-c9a9-4545-97e8-f78ef5d87647)

and then, launch your function from the side bar.

5\. Some functions are going to execute immediately, while others may require several hours. To **track the function progress**, you can use the link provided in the confirmation window that LABDRIVE shows when you launch the function:

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-Mb0_Ii2YzbdDUzLDpu6%2F-Mb0gASQxb090995gRP0%2Fimage.png?alt=media\&token=ebe44773-e645-4bf4-9bc0-0c8a4f45f6c4)

You can also go to the **Container** and select **Functions**, to see the ones in execution and their outcome:

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-Mb0hH1CoUB1Bc4ZgwNB%2F-Mb0nEuqWVUomgrGh18e%2Fimage.png?alt=media\&token=2f5ebae4-95ff-4edc-ba49-8ff832b5c2a4)

Some functions will process and change your content, while others may **create new files in the container.** When a function **produces a new report or file,** it is shown as an **Asset** when you open the function execution details page:

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-Mb2W3abcgT7H8g62xP6%2F-Mb2Wpnt5giGbmxsDBR4%2Fimage.png?alt=media\&token=d9e0d519-1b65-4646-95d1-761211d7e7b9)

## Launch functions using the API

{% hint style="info" %}
API examples here are just illustrative. Check the [LABDRIVE API documentation](https://docs.libnova.com/labdrive/developers-guide/api-extended-documentation) for additional information and all available methods.
{% endhint %}

1\. Sign in to the LABDRIVE Management Interface

2\. Obtain your LABDRIVE API key by selecting your name and then **Access Methods:**

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MVaHSX-G_bFFXPQn-Od%2F-MVaJWnwSfyMMFbO42X1%2Fimage.png?alt=media\&token=7047e304-094c-4c46-a50e-102ba2513abe)

### Launch the function

3\. Basically, to execute a function you need to know the function ID and the container or file IDs you want to execute it over (or apply it to). You can **get all functions** that are loaded in the LABDRIVE platform using the following method:

```
$ curl --request GET \
      --url "$your_labdrive_url/api/functions" \
      --header "authorization: Bearer $your_labdrive_api_key"
```

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-Mb5n8n3jTCv63mtXqXw%2F-Mb5nhp0S5E8PvvU6oTz%2Fimage.png?alt=media\&token=0572bf83-7d7d-4620-9e7a-d20b675c17f0)

4\. Some functions receive parameters. To call them, use the following method:

```
$ curl --request POST \
      --url "$your_labdrive_url/api/container/{your container id}/file/0/function/{your function id}" \
      --header "authorization: Bearer $your_labdrive_api_key" \
      --data '{your parameters here}'
```

For instance, this function requests the file IDs and the path as parameters:

```
$ curl --request POST \
      --url "$your_labdrive_url/api/container/171/file/0/event/32" \
      --header "authorization: Bearer $your_labdrive_api_key" \
      --data '{"extra":{"filename":"","ids":["985248"],"path":"/"}}'
```

For small functions that are immediately completed, LABDRIVE will answer with a **Success/error code**, but for more complex functions, LABDRIVE will **create a job** to execute them, so you can **track the execution** progress. 

When the function is launched, LABDRIVE will provide the job id in the response:

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-Mb5n8n3jTCv63mtXqXw%2F-Mb6QSaZ8q4XDMvBwSEV%2Fimage.png?alt=media\&token=2ce12199-a832-4027-b505-b3a2a65c8555)

Then, you can do three things: 

### Monitor its execution

Some functions may take hours to complete. You can use the /job API endpoint with the job\_id returned in the previous method to monitor its progress:

```
$ curl --request GET \
      --url "$your_labdrive_url/api/job/{your job id}" \
      --header "authorization: Bearer $your_labdrive_api_key" \
      --data '{}'
```

### See function output log

For each job, you can get its log using the `/job/{job id}/messages`:

```
$ curl --request GET \
        --url "$your_labdrive_url/api/job/{job id}/messages" \
        --header "authorization: Bearer $your_labdrive_api_key" \
        --data '{}'
```

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-Mb6RkFBcrgGpJvzxTm-%2F-Mb6TcCOyaM_lViXjCqF%2Fimage.png?alt=media\&token=0ff39e87-b613-446c-ab2e-d7875c7461e2)

### Review created assets/files

And, finally, some functions could create new **assets** (files). For example, your function could produce a report in a PDF file, or if the function is to compress data, it will create a ZIP file, for instance.

You can list the assets a job has created with the `/job/{job id}/assets` method:

```
$ curl --request GET \
        --url "$your_labdrive_url/api/job/{job id}/assets" \
        --header "authorization: Bearer $your_labdrive_api_key" \
        --data '{}'
```

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-Mb6RkFBcrgGpJvzxTm-%2F-Mb6UFKijjGnOSUc4TGm%2Fimage.png?alt=media\&token=4b515c57-bb20-46aa-98bc-1a598c914361)

And download the asset like any other file with the `file_id`, using the API or any other available download method (remember to include the "-L" in your call):

```
$ curl --request GET \
       --url "$your_labdrive_url/api/file/{your file id}/download" \
       --header "Content-Type: application/json" \
       --header "authorization: Bearer $your_labdrive_api_key" \
       --data '{}' -L --output my_execution_report.html
```

![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-McNz0ohEMh5NVWhnAcg%2F-McNz4JDsIiccbQisaye%2Fimage.png?alt=media\&token=0416b548-dd9c-4e22-8544-2c0c0f731514)

## Create a LABDRIVE Function

Please see the [Functions documentation in the Developer's guide](https://docs.libnova.com/labdrive/developers-guide/functions)