From version 15.4.2 it is possible to share links to rooms and from version 15.4.6 it is possible to send chemical files from external applications. This document describes the technical details of such an integration.
The browser address bar URL is automatically updated as the user interacts with the application to create bookmarkable and shareable links. Matching this scheme allows external tools to generate working links to Marvin Live.
The links have the following syntax:
http://hostname:port/rooms/ domainName / roomName ?flags
Name of the domain where the user is currently logged in, as defined in config.json’s authentication section (install guide).
Name of the meeting room the user has joined, with encoding that changes spaces to underscores and adds URL encoding.
Example: Mike's ideas becomes
The query arguments include control flags for further actions after login or joining a room.
When a user clicks on a link, they are directed to the specified domain and room, by first logging in (and logging out from a different domain if needed), and then by selecting a display name before joining the room. This means even when knowing the link, only authorized users can access the contents of a room.
External applications may send content to Marvin Live, by sending a POST request to the upload API endpoint. This endpoint accepts:
multipart requests with a single chemical structure file - which may contain more than 1 actual chemical structure
JSON requests with the source of a chemical structure file - which may contain more than 1 actual chemical structure
The response in both cases includes URL with a unique ID - located in the redirect for multipart request, and in a JSON object for JSON request, opening this URL in the client browser will make the contents of the file available in the first meeting room joined. If not authenticated, the client browser will also be taken through the login process.
Chemical file formats recognized by this module include MRV by default, but when converterService option is configured (install guide), other formats are automatically supported: SDF, SMILES, CDX, etc…
A browser file upload form produces a valid multipart request, when the form ’s
action attribute and the file input ’s
name attribute are specified as below:
When submitted, this sends the following HTTP request:
If the request succeeds, the server returns HTTP 302 Moved temporarily status code, along with a redirect URL containing a unique ID that references the parsed contents of the file. Integrating applications should open this URL in the user’s browser. This unique URL is valid for 5 minutes.
A valid request has the Content-Type of application/json and the body contains a JSON structure, with the file contents under the structures key.
If the request succeeds, the server returns a simple JSON object containing a unique URL that references the parsed contents of the file. Integrating applications should open this URL in the user’s browser. This unique URL is valid for 5 minutes.
For web applications, the simplest solution would prepare a form and programmatically submit it, to instruct the browser to perform the upload request. With a redirect in the response, the browser would then automatically open Marvin Live and take the user through the login/join process.
generate valid chemical file
prepare form with correct parameters
Since most web applications would have a host different from Marvin Live’s, the Same-Origin Policy may prevent specific solutions from functioning. In this case, the recommended solution is to enable
allowCrossOriginUploads option (install guide) and use the JSON request option.
For desktop applications, the simplest solution would send a JSON request and wait for the response. Using the URL in the response, the application would then send a browser open command to the operating system.
generate valid chemical file
send POST request with the file contents
find URL in the response