Commit cae87269 authored by Matija Obreza's avatar Matija Obreza

Anno manual PDF formatting

- Image sizes adjusted (pdfwidth)
parent 2f9be28f
......@@ -2,23 +2,23 @@
[[datasources]]
== Data Sources
Anno is able to load data from Excel XLSX and CSV files and through database SQL queries.
Anno is able to load data from Excel XLSX and CSV files and through database SQL queries.
Every data source *must* contain at least the following three "columns" that uniquely
identify an accession on Genesys:
. `INSTCODE`: the FAO WIEWS Institute code of the holding genebank
. `ACCENUMB`: Full identifier of the accession in your genebank
. `GENUS`: Genus of the accession
. `GENUS`: Genus of the accession
=== Excel and CSV files
To add an Excel or CSV file to the Project, click the "Add file" button in the Toolbar.
You will be prompted with an "Open file" dialog to select the source file to add to the project.
NOTE: Older versions of Excel files (with *xls* extension) are not supported.
NOTE: Older versions of Excel files (with *xls* extension) are not supported.
Excel files may contain multiple sheets that will be listed as individual data source sheets.
CSV files contain only one sheet. The data sheets from source files are listed as sub-entries of
CSV files contain only one sheet. The data sheets from source files are listed as sub-entries of
the source file. To open a data sheet and load the first 300 rows, double click the sheet name.
.Project with XLSX and CSV data sources
......@@ -31,26 +31,26 @@ additional configuration before it loads correctly.
=== CSV file configuration
CSV files are plain text files and do not provide any information about the character encoding,
separator or quote character used to separate text strings from numbers.
separator or quote character used to separate text strings from numbers.
NOTE: Use Excel XLSX files instead of CSV files when possible. Open the CSV in Excel, make sure
NOTE: Use Excel XLSX files instead of CSV files when possible. Open the CSV in Excel, make sure
data is well formatted and save it in XLSX format.
When opening a CSV data source, Anno may not be able to load the file without you providing
When opening a CSV data source, Anno may not be able to load the file without you providing
information on formatting of the file in the *CSV* tab of the CSV data sheet.
[cols="1,4", options="header"]
[cols="1,4", options="header"]
.Configuration for CSV files: Formatting
|===
|Label|Description
|Character set|CSV files generated from databases usually default to the character set of the
|Character set|CSV files generated from databases usually default to the character set of the
operating system. Use "windows-1250" for files generated on Windows, "x-MacCentralEurope" for Mac OSX.
You will have to experiment (Reload) with different options.
|Separator|Pick comma (,) or tab (blank)
|Quote character|Pick single (') or double quote (")
|===
Even by providing the best settings for the CSV file, you cannot ensure that Anno will be able to read
Even by providing the best settings for the CSV file, you cannot ensure that Anno will be able to read
all data correctly.
NOTE: Convert your CSV file to Excel XLSX format!
......@@ -61,7 +61,7 @@ Click "Reload" to load the CSV file with the new settings.
Occasionally the data files contain additional rows at the start of the document that should be ignored by Anno.
[cols="1,4", options="header"]
[cols="1,4", options="header"]
.Configuration for data files: Headers
|===
|Label|Description
......@@ -82,17 +82,17 @@ Click "Add database" in the Toolbar. This will add a JDBC connection to your dat
source element. You will be able to add individual, tailored SQL queries as actual Anno data sources.
.Adding a database as data source
image::source-database.png[role="text-center"]
image::source-database.png[role="text-center",pdfwidth=75%]
[cols="1,4", options="header"]
[cols="1,4", options="header"]
.Add Database dialog
|===
|Label|Description
|Datasource type|Select the database type from the list of supported drivers: mysql, MS SQL Server, PostgreSQL, ODBC
|Datasource name|Provide a name for the database connection to be used as the top-level label of the data source
in the Project.
|Connection URL|Edit the JDBC connection string template. You will have to provide the database host name,
|Connection URL|Edit the JDBC connection string template. You will have to provide the database host name,
port and the database instance name.
|User and Password|Valid username and password to access the database.
|Connect|Attempt to connect to the database with provided settings.
......@@ -109,14 +109,14 @@ prompt to add the database link to the Project. Otherwise fix the username, pass
string (search engines are a good resource to find a valid JDBC connect string for your database!).
.Database successfully added as data source
image::database-connected.png[role="text-center"]
image::database-connected.png[role="text-center",pdfwidth=50%]
After the connection to the database is successfully established, the database connection is added as a
After the connection to the database is successfully established, the database connection is added as a
top-level data source. You are now able to add SQL queries as individual data sources to the project.
Right-click on the database data source and select "Add SQL query".
.Database successfully added as data source
image::database-addquery.png[role="text-center"]
image::database-addquery.png[role="text-center",pdfwidth=40%]
This will create a data sheet entry under the database label, titled "Unnamed query". Double-click the entry in
the Project data source tree and update the query label and the SQL query itself.
......@@ -126,9 +126,9 @@ image::database-unnamed-query.png[role="text-center"]
Press the "Reload" button to load data from the database. This will refresh the contents of the data sheet.
NOTE: Save the Project file regularly.
NOTE: Save the Project file regularly.
You should start with a simple SQL query to the database and then create additional data sheets
You should start with a simple SQL query to the database and then create additional data sheets
in the Project as you query for additional accession data.
NOTE: All SQL queries need to include `INSTCODE`, `ACCENUMB` and `GENUS` columns! Use your SQL-JOIN-foo to write
......@@ -137,5 +137,3 @@ NOTE: All SQL queries need to include `INSTCODE`, `ACCENUMB` and `GENUS` columns
.A dummy SQL query with core columns: `INSTCODE`, `ACCENUMB` and `GENUS`
image::database-basic.png[role="text-center"]
......@@ -29,14 +29,14 @@ Load your data sheet and make sure it contains these three columns.
.Mapping the `ACCENUMB` column
image::mapping-accenumb.png[role="text-center"]
image::mapping-accenumb.png[role="text-center",pdfwidth=75%]
Once these three columns are mapped, double-clicking on a row in the data sheet row listing will
display an alert dialog with the accession data in mapped Genesys JSON format.
.Preview of data in JSON format
image::mapping-json-basic.png[role="text-center"]
image::mapping-json-basic.png[role="text-center",pdfwidth=50%]
As you continue mapping other columns, more information will be included in the JSON preview dialog.
......@@ -60,4 +60,3 @@ In both cases, the individual pieces of the data will be converted to an array o
=== Using regular expressions
*TBD*
......@@ -6,7 +6,7 @@ The *Settings Dialog* allows you to configure the current Project and specify
which Genesys server will receive your data.
.Settings Dialog
image::settings-dialog.png[role="text-center"]
image::settings-dialog.png[role="text-center",pdfwidth=75%]
The settings are stored in the Project file and will be saved and loaded with the
rest of the project configuration.
......@@ -56,7 +56,7 @@ If tokens are still valid, their values in the
dialog will be updated with the message: "Tokens are up to date."
.Authentication Dialog
image::authentication-dialog.png[role="text-center"]
image::authentication-dialog.png[role="text-center",pdfwidth=75%]
"Open link in browser" opens your default web browser application (Chrome, IE, Firefox, ...) and
......@@ -65,7 +65,7 @@ to Genesys, you will be prompted to log in before the confirmation dialog is dis
.Allow access
image::confirm-access.png[role="text-center"]
image::confirm-access.png[role="text-center",pdfwidth=75%]
Select "Yes, allow access" and Genesys will generate a short-lived *verifier code* that you must copy and paste
to the *Verifier code* field in the Anno dialog. The verifier code is a 6-character string (e.g. `td1S83`).
......
......@@ -18,9 +18,9 @@ image::anno-blank.png[role="text-center"]
The toolbar provides access to top-level functions.
.Anno Toolbar
image::toolbar.png[role="text-center"]
image::toolbar.png[role="text-center",pdfwidth=50%]
[cols="1,4", options="header"]
[cols="1,4", options="header"]
.Toolbar buttons
|===
|Label|Description
......@@ -32,4 +32,3 @@ image::toolbar.png[role="text-center"]
|Push|Opens a dialog to send data to Genesys
|Add database|Add a new database-backed data source to the project
|===
......@@ -2,8 +2,8 @@
[[workspace]]
== Workspaces and Projects
Upon starting the application, you will be presented with a *Workspace Launcher* that
allows to create a new Workspace or load an existing Workspace from disk.
Upon starting the application, you will be presented with a *Workspace Launcher* that
allows to create a new Workspace or load an existing Workspace from disk.
A *workspace* allows you to save your Anno configuration files and any JDBC drivers needed
to access your data in one location on your computer.
......@@ -14,9 +14,9 @@ When you first start the application the you will need to create a new workspace
your configuration files.
.Workspace Launcher
image::workspace-launcher.png[role="text-center"]
image::workspace-launcher.png[role="text-center",pdfwidth=75%]
Click the "Browse" button and navigate to the directory where you wish to create a new
Click the "Browse" button and navigate to the directory where you wish to create a new
workspace. You may need to create a new folder for the workspace.
Confirm your selection by pressing "OK".
......@@ -25,19 +25,19 @@ NOTE: The application will check if the selected folder is empty.
=== Loading an existing workspace
Click the "Browse" button and navigate to the directory with your existing workspace data.
Click the "Browse" button and navigate to the directory with your existing workspace data.
Confirm your selection by pressing "OK".
NOTE: The application will check if the selected folder is a valid Anno workspace folder.
.Invalid workspace folder selection
image::workspace-launcher-fail.png[role="text-center"]
image::workspace-launcher-fail.png[role="text-center", pdfwidth=75%]
=== Using the workspace
The workspace acts as a base directory for your configuration and data files. It is good practice
to copy the source files (CSV, Excel) to the workspace folder. This will help you better maintain
your settings and data files you publish on Genesys.
to copy the source files (CSV, Excel) to the workspace folder. This will help you better maintain
your settings and data files you publish on Genesys.
=== Under the hood
......@@ -55,6 +55,5 @@ contains:
. Data sources: CSV, Excel and database queries
. Column configuration and mapping to MCPD
It is good practice to maintain one project file has the configuration used to test the data and push it to the Genesys Sandbox environment,
It is good practice to maintain one project file has the configuration used to test the data and push it to the Genesys Sandbox environment,
and a separate project file is used to publish data to the Genesys production servers.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment