This library provides the basic connectivity with EBX5. It allows to read, insert, update and delete data stored in EBX5. A previous version of the library was using keyring to persist the password into the secure store provided by the operating system (Windows and macOS). Use of keyring requires an additional install on Linux, and access to the server. Without server access, we cannot use keyring.

This is the base library, which requires to specify location and name of each reference in EBX5. fishstatr is a companion library, which uses a user-created Metadata structure to allow programs to discover available objects in EBX5, their attributes and connections. Using this library allows the program to access reference-data, whithout having to know the exact location: it allows users to move things in EBX5 wthout breaking the programs which as they use a code-list’s Acronym instead of the excat location.

Faoexb5 needs to know how to connect to the EBX5 server. This can be done in two different ways: 1) ebx5_connection.yaml file created by or using environment variables (EBX5_URL,EBX5_USERID, EBX5_SECRET, BRANCH, INSTANCE). For use with a shiny app, the best way is to setup the environment variables in the Rstudio connect app settings panel. If this is not possible (hqlprsws1 server), or for local use you cerate the YAML file (explained below). With the yaml file present (user PC), or the environment variables your shiny app will work without code change.

How to use

SetupEBXConnection()

The first time you use the faoebx5 package you must setup the EBX5 connection details. The faoebx5 library reads the settings from a file, so that you do not have to provide it for every request.

library('faoebx5')
library('dplyr')
#SetEBXCredentials(
#    username = "SilvaLu", 
#    password="secret", 
#     meta_branch = 'Fishery',
#     meta_instance = 'Fishery',
#    ebx_soap_url="https://my-ebx5.com/ebx-dataservices/connector")

EBXRead()

This function reads code list data from EBX5. The user needs read-only permission for the given dataset, and table.

#cl_fao_level1 <- EBXRead(branch='Fishery',
#'           instance='Fishery',
#'           folder='Country',
#'           table='CountryItem')
#cl_fao_level1

Warning!

Please, be aware that the next three functions can modify the original data. Your account needs to have rights to do update the original data.

EBXInsert()

EBXInsert(),EBXUpdate() and EBXRemove() should be used carefully, as they change the original data stored in the EBX database. The user account used cannot be read-only, and must have been granted write permission on the dataset and on the table.

In order to uniquely identify the rows, the primary key(s) of the table needs to be specified (usually the Identifier) .

#cl_insert <- data.frame(
#            Identifier = 99999,
#            FAO_Code = 7L,
#            NameEn = "XXXX_English",
#            NameFr = "XXXX_French",
#            NameEs = "XXXX_Es"
#)

Once we have created the data frame with the new rows, the next step is to run the function InsertEBXCodeList() specificating the arguments: data with data frame composed by the news rows to be inserted, cl_name the code list name, folder the folder name, branch the branch name, and instance the instance name.

#EBXInsert(
#           branch='Fishery',
#           instance='Fishery',
#           folder='Metadata',
#           table='Test_table',
#           data=cl_insert)
#)
#
#cl_read <- EBXRead(
#           branch='Fishery',
#           instance='Fishery',
#           folder='Metadata',
#           table='Test_table')
#cl_read

EBXUpdate()

EBXUpdate() function updates or inserts exiating information in the database. In this example, we just changed the data stored in the column NameEs from XXXX_Es to Name spanish.

#cl_update <- data.frame(
#            Identifier = 99999,
#            FAO_Code = 7L,
#            NameEn = "XXXX_English",
#            NameFr = "XXXX_French",
#            NameEs = "Name spanish"
#)
#
#EBXUpdate(
#           branch='Fishery',
#           instance='Fishery',
#           folder='Metadata',
#           table='Test_table',
#           data=cl_update)
#)
#
#cl_read <- EBXRead(
#           branch='Fishery',
#           instance='Fishery',
#           folder='Metadata',
#           table='Test_table')
#cl_read

EBXRemove()

EBXRemove() deletes rows in the database. For a delete, you only have to specify the primary key.

#cl_delete <- data.frame(
#            Identifier = 99999
#)
#
#EBXRemove(
#           branch='Fishery',
#           instance='Fishery',
#           folder='Metadata',
#           table='Test_table',
#           data=cl_delete)
#)
#
#cl_read <- EBXRead(
#           branch='Fishery',
#           instance='Fishery',
#           folder='Metadata',
#           table='Test_table')
#cl_read

faoebx5 library