Swate - something or someone that gets you absolutely joyed (Urban dictionary)
Swate is a Swate Workflow Annotation Tool for Excel.
Swate aims to provide a low-friction workflow annotation experience that makes the usage of controlled vocabularies (ontologies) as easy and intuitive as possible. It is designed to integrate in the familiar spreadsheet environment that is the center of a great deal of data-focused wetlab work.
The base features of Swate are:
- Gradual workflow annotation table building via the basic annotation building blocks
- No-fuss ontology term search:
- search for ontology terms quickly via autocomplete
- use is-a relational term search (e.g. search all terms that are also a 'plant organ') to constrain your annotation column to a subset of ontologies
- use Advanced term search with multiple query parameters if quick search does not do it for you
There are many more small and incremental features. Check the latest release notes for the newest additions.
You can test swate by following the steps below. If you decide to do so, please take the time to set up a Github account to report your issues and suggestions here. You can also search existing issues for solutions for your questions and/or discussions about your suggestions.
N O T E : Swate runs only on MS Excel 365, and MS Excel Online. We test on and develop for explicitly these versions. (It is possible though that some older versions like MS Excel 2019 work.)
Use the new Swate installer.
Alternative | Using the release archive
#### Using the release archive
- Install [node.js LTS](https://nodejs.org/en/) (needed for office addin related tooling)
- Download the [latest test release archive](https://github.com/nfdi4plants/Swate/releases) and extract it
- Execute the test.cmd (windows, as administrator) or test.sh (macOS, you will need to make it executable via chmod
a+x) script.
If you have administrative access in your organization, you can create a network share folder and follow this guide to make the addin available without any further downloads from your users
- Download the latest test release archive and extract it
- Launch Excel Online (this requires a Microsoft account), open a (blank) workbook
- Under the
Insert
tab, selectAdd-Ins
- Go to
Manage my Add-Ins
and selectUpload my Add-In
- select and upload the
manifest.xml
file contained in the test release archive.
The RPC API docs of Swate are available here
Documentation of the features is now a top priority as we completed the POC stage ๐. You can discuss needed docs and the available ones here
Guides will be coming in the near future.
Please use Github issues to track problems, feature requests, questions, and discussions. Additionally, you can get in touch with us on Twitter
GitHub recently added forum-like features to repositories, which makes it possible to discuss and share things you do with swate without creating issues. You are very welcome to post content in the Discussions
tab, but please use issues for bug reports/feature requests (or, if some of those result from a discussion, create a new issue referencing the discussion)
Before you contribute to the project remember to return all placeholders to your project:
- webpack.config.js
https: { key: "{USERFOLDER}/.office-addin-dev-certs/localhost.key", cert: "{USERFOLDER}/.office-addin-dev-certs/localhost.crt", ca: "{USERFOLDER}/.office-addin-dev-certs/ca.crt" },
- .db/docker-compose.yml
MYSQL_ROOT_PASSWORD: {PASSWORD}
- Server/dev.json
"Swate:ConnectionString": "server=127.0.0.1;user id=root;password={PASSWORD}; port=42333;database=SwateDB;allowuservariables=True;persistsecurityinfo=True"
-
.NET Core SDK at of at least the version in the global.json file
-
Docker with Docker-compose
-
Node.js with npm/npx
-
To setup all dev dependencies, you can run the following commands or the install.cmd file (explained further below). The first run will take some time to import the database from the .sql file:
dotnet tool restore
(to restore local dotnet tools)dotnet fake build -t setup pw:example
, which will take care of installing necessary certificates and loopback exempts for your browser. Here are the steps if you want to execute them by yourself:-
'pw:example' is an optional parameter for the setup target to use a custom password for the local MySql docker instance. If this argument is not passed the instance will be created with the password 'example'.
-
connections from excel to localhost need to be via https, so you need a certificate and trust it. office-addin-dev-certs does that for you.
you can also use the fake build target for certificate creation and installation by using
dotnet fake build -t createdevcerts
in the project root (after restoring tools viadotnet tool restore
).This will use office-addin-dev-certs to create the necessary certificates, and open the installation dialogue for you:
installing this ca certificate under your trusted root certification authorities will enable you to use https via localhost.
The paths to these certificates are then added to your webpack.config file.
-
You may need a loopback exemption for Edge/IE (whatever is run in your excel version):
CheckNetIsolation LoopbackExempt -a -n="microsoft.win32webviewhost_cw5n1h2txyewy"
-
The install.cmd executes several console commands for one of which it needs adminstratorial rights (dotnet fake build -t setup) to install the certificate mentioned above.
Open powershell as adminstrator and navigate to the Swate-folder cd your\folder\path\Swate
then use .\install.cmd
to initialize the setup.
While running a installation dialogue for the certificate will open and can be handled as described above.
By installing this repo via the install.cmd file the MySql password will default to 'example'.
By now the SwatwDB.sql dump in this repo is outdated. You can request a current version by opening an issue. In addition, the dump has become so large that it can no longer be loaded on mysql db creation and needs further input:
After following the instructions above:
- Go to
localhost:8085
and create a new database calledSwateDB
- Open powershell in the folder with the sql dump.
- Use
cmd /c "docker exec -i db_db_1 mysql -uroot -pexample SwateDB<SwateDB.sql"
- Observe in Adminer how the tables are created and slowly filled.
This project uses the SAFE Stack to create a website that uses office.js to interop with Excel.
The file OfficeJS.fs contains Fable bindings autogenerated from the office.js typescript definitions.
to debug the AddIn locally, use the build target OfficeDebug
:
fake build -t OfficeDebug
this will launch an Excel instance with the AddIn sideloaded, while also running docker with a MySql- and a Adminer instance. The MySql user/password will be root/example and can be set in .db/docker-compose.yml. Adminer can be accessed at localhost:8085, MySql at localhost:42333, and the app runs at localhost:3000 for client and localhost:8080 for the server.
However it is currently pretty hard to attach a debugger to the instance of edge that runs in the Excel window (update: you can now use EdgeDevToolsPreview for that aswell). You can circumvent this issue by additionally testing in Excel online:
- open Excel online in your favorite browser
- create a blank new workbook (or use any workbook, but be warned that you can't undo stuff done via Office.js)
- Go to Insert > Office-Add-Ins and upload the manifest.xml file contained in this repo
- You will now have the full debug experience in your browser dev tools.
Alternatively, you can debug all functionality that does not use Excel Interop in your normal browser (the app runs on port 3000 via https)