The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
ELab-Client-0.020
River stage zero No dependents
++
/ ELab::Client

NAME

ELab::Client - Access the eLabFTW API with Perl

VERSION

version 0.020

SYNOPSYS

  use ELab::Client;

  my $elab = ELab::Client->new(
                    host => 'https://elab.somewhere.de/',
                    token => 'ae...d4',
              );

  my $e = $elab->post_experiment(4,
                    title => "Replacement experiment title",
                    body => "Replacement body text"
              );

METHODS

API interface

This interface is intended to be compatible to the elabapy Python client.

get_backup_zip($datespan)

  use File::Slurp;
  write_file('backup.zip', get_backup_zip('20200101-20210101'));

Generates a zip file with all experiments changed in a given time period. The period is specified as FROM-TO in the format YYYYMMDD-YYYYMMDD.

Requires sysadmin permissions.

get_items_types()

  my $t = $elab->get_items_types();

Returns a list of database item types with their type id's. The return value is an array reference, with the array items being hash references for each item type.

get_item_types()

Alias for get_items_types()

get_status()

  my $s = $elab->get_status();

Returns a list of possible experiment states. The return value is an array reference, with the array items being hash references for each status type.

get_experiment_states()

Alias for get_status()

  my $result = add_link_to_experiment(2, link => 5)

Adds to an experiment a link to a database item with given id. Returns a hash reference with status information.

  my $result = add_link_to_item(2, link => 5);

Adds to a database item a link to another database item with given id. Returns a hash reference with status information.

add_tag_to_experiment($id, ...)

  my $result = add_tag_to_experiment(2, tag => "awesome");

Adds to an experiment the given tag (a string). Returns a hash reference with status information.

add_tag_to_item($id, ...)

  my $result = add_tag_to_item(42, tag => "broken");

Adds to a database item the given tag (a string). Returns a hash reference with status information.

create_item($type)

  my $e = $elab->create_item($type);

Creates a new database item of type $type. The return value is a hash reference with status information and the id of the new item.

create_experiment()

  my $e = $elab->create_experiment();

Creates a new experiment. The return value is a hash reference with status information and the id of the new experiment.

create_template()

  my $t = $elab->create_template();

Creates a new template. The return value is a hash reference with status information and the id of the new template.

get_upload($id)

  my $data = $elab->get_upload($id);

Get an uploaded file from its id. The result is the raw binary data of the uploaded file.

get_bookable()

  my $b = $elab->get_bookable();

Returns a list of bookable items (i.e., equipment etc). The result is an array reference.

get_all_experiments(...)

  my $a = $elab->get_all_experiments(limit => 15, offset => 0);

Lists the stored experiments, at most limit and starting at offset. The return value is an array reference, where each element is a hash reference describing an experiment (not fully, but abbreviated).

get_experiment($id)

  my $e = $elab->get_experiment($id);

Returns an experiment. The return value is a hash reference with the full experiment information.

get_all_items(...)

  my $a = $elab->get_all_items(limit => 25, offset => 0);

Lists database items, with maximum number limit and starting at offset. The return value is an array reference, where each element is a hash reference corresponding to a database item.

get_item($id)

  my $i = $elab->get_item($id);

Returns a database item. The return value is a hash reference with the full item information.

get_tags()

  my $t = $elab->get_tags();

Returns the tags that are in use.

get_all_templates()

  my $t = $elab->get_all_templates();

Lists the available templates. The return value is an array reference, where each element is a hash reference describing a template.

get_template

  my $t = $elab->get_template($id);

Returns a template. The return value is a hash reference with the template information.

post_experiment($id, ...)

  my $e = $elab->post_experiment(13,
                    title => "Updated experiment title",
                    body => "Updated experiment body text"
        );

Updates an experiment, overwriting previous values or (in the case of 'bodyappend') appending to the existing text. The following parameters can be given:

  category    The (id of the) experiment status
  title       The experiment title
  date        The date
  body        The experiment body text
  bodyappend  Text that is appended to the experiment body text

post_item

  my $i = $elab->post_item(4,
                    title => "Database item",
                    body => "This is a piece of expensive equipment."
        );

Updates a database item, overwriting previous values or (in the case of 'bodyappend') appending to the existing text. The following parameters can be given:

  category    The (id of the) database item type
  title       The item title
  date        The date
  body        The item body text
  bodyappend  Text that is appended to the item body text

post_template($id, ...)

  my $t = $elab->post_template(4,
                    title => "New template title",
                    body => "Lots of text"
        );

Updates a template, overwriting previous values. The following parameters can be given:

  title       The item title
  date        The date
  body        The item body text

upload_to_experiment($id, ...)

  my $e = $elab->upload_to_experiment(13, file => "mauterndorf.jpg");

Uploads a file given by its name and appends it to the specified experiment. The return value is a hash reference with status information.

upload_to_item

  my $e = $elab->upload_to_item(13, file => "mauterndorf.jpg");

Uploads a file given by its name and appends it to the specified database item. The return value is a hash reference with status information.

create_event(...)

  my $e = $elab->create_event(
    start => "2019-11-30T12:00:00",
    end   => "2019-11-30T14:00:00",
    title => "Booked from API",
  );

Creates an event in the scheduler for a bookable item. The return value is a hash reference with status information and the id of the generated event.

destroy_event($id)

  my $e = $elab->destroy_event(1);

Deletes the event with the given id.

get_all_events()

  my $e = $elab->get_all_events();

Returns a list reference with information on all events.

get_event($id)

  my $e = $elab->get_event(1);

Returns a hash reference with information on the event specified by id.

Low-level methods

elab_get($url)

  my $hashref = decode_json $self->elab_get("events/$id");

Sends a GET requrest to the server, and returns the response as JSON.

elab_delete($url)

  my $hashref = decode_json $self->elab_delete("events/$id");

Sends a DELETE requrest to the server, and returns the response as JSON.

elab_post($url, $data)

  my $hashref = decode_json $self->elab_post("events/$id", $self->buildQuery(%args));

Sends a POST requrest to the server, with the posted data supplied as an urlencoded string (starting with '?' for convenient use of buildQuery). Returns the obtained data as JSON.

AUTHOR

Andreas K. Huettel <dilfridge@gentoo.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by Andreas K. Huettel.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.