Oftentimes you have external data coming from a REST HTTP API and want access to it through the Pathomation software platform for digital pathology and virtual microscopy. Importing the data as Pathomation form data may not always make sense for a variety of reasons.

PMA.core allows you to link external rest APIs and use them as regular form data. This works by invoking a user-defined command line application which must exist in the system that hosts PMA.core. Such applications can be:

• curl
• python
• custom cli utilities

PMA.core executes the application for a given image path and can also supply extra command line arguments. Once the application has finished, PMA.core reads the standard output stream and expects a JSON response, in which it attempts to read values for particular fields.

To configure your external HTTP API data link to PMA.core, click on the Add button in the External API data section of the External Data page, of the administrator front-end UI.

On the next page you will be prompted to add

• Name: A name for the new connection to distinguish this connection from others
• Command: The name or path of the application to execute
• Arguments: Command line arguments to pass to the application
• Fields: Field names to expect in the JSON output, once the command is executed

In the arguments field you can specify any number of command line arguments that are required for the correct execution of the command. For example, if you want to run a python script, the value for the command should be “python” and the arguments should be the name of the script, e.g. “my-script.py”.

Additionally, PMA.core can identify the following keywords in the arguments string and replace them with their actual values whenever the REST API data source is consulted:

1. [path]: Gets replaced with the path of the image for which the external API is consulted.
2. [filename]: Gets replaced with the filename of the image for which the external API is consulted.
3. [filename_no_ext]: Gets replaced with the filename, without the extension, of the image for which the external API is consulted.
4. [barcode]: Gets replaced with the barcode text, if any, of the image for which the external API is consulted.
5. [oidc]: Gets replaced with the calling user's OpenID token, if applicable.
6. [session_id]: Gets replaced with the calling user's session id.

For example, if you have configured PMA.core to allow logging in via an OAuth 2.0 SSO provider, you can pass the user's access token to the external API, supposing it uses the same authentication provider. Here's a curl example:

• Command: curl
• Arguments: -G -X GET –header “Accept: application/json” “https://my-api-url” –data-urlencode “token=[oidc]” –data-urlencode “pathOrUid=[path]”

PMA.core can read top level field values from a JSON response. You can specify a list of fields it should attempt to read, each separated in a new line.

You can test the result of the command from this page. Simply fill out an image path for which the command should run and PMA.core will display the raw results of the command in a pop up:

After creating the connection you can now use the FormData API to request data by using the Query ID as the Form ID, the same way you request native PMA.core Form Data.

This is the same API that is used to provide external data in downstream applications like PMA.studio, PMA.slidebox, PMA.control etc.