SF-001 Application info

Namespace: synergy/app-info
Status: Draft
 Version: 0.2
 Last updated: 27.10.2017

Introduction

The ability to discover information about applications in a hosted environment is essential in an integration perspective. Such information include features/services offered by the application and applications’ type and/or identity. This documents describes how such information is gathered and how it is offered by Chemaxon Synergy to registered applications.

Registering application

Basic protocol

Each application MUST provide a JSON document which contains information about application’s address, name, identity and supported features.

Example
{
displayName: "Fibonacci",
address: "http://localhost:8102",
identities: [
{category: "service", type: "computation"}
],
features: [{
namespace: "synergy/app-info",
attributes: {
url: "http://localhost:8102/services/app-info"
}
},{
namespace: "synergy/health",
attributes: {
url: "http://localhost:8102/services/health"
}
},{
namespace: "synergy/icon",
attributes: {
url: "http://localhost:8102/services/app-icon"
}
}]
}

  • displayName - application name displayed in Synergy

  • address - base url address of the application

  • features - list of available features with configuration

  • identities - list of application identities

This JSON should be exposed at a publicly available URL with a content type of “application/json; charset=utf-8”.

Identities

Application is easily categorised by its list of identities which can be used for navigation, grouping and integration based on identity. Application identity is described by category and type . Application can have more than one identity (see examples).

  • category - determines application category: ie. application - application with web interface, service - application without web interface providing its services (i.e. REST)

  • type - application type should reflect the purpose of the application (see table below)

category

type

application (with UI)

registration

 

eln

 

inventory

 

project-management

 

data-analysis

 

reporting

 

...

service (without UI)

search

 

computation

 

compliance

 

...

chemaxon (vendor specific)

...

Features

Every application SHOULD have list of SF-XXX features. Every feature contains a namespace and map of attributes describing the configuration required for a given feature.

  • namespace - sensible identifier of the feature (like product/feature-name, workflow-name/feature-name and so on), synergy/* is the reserved namespace for the features used by the synergy

  • attributes - map of feature attributes. Number of items inside attributes is not limited and it depends on the feature what attributes are necessary for using the feature

Synergy also defines few features required from applications for its own functionality.


feature

namespace

documentation

Application Info

synergy/app-info

SF-001

Healthcheck

synergy/health

SF-002

Application Icon

synergy/icon

SF-003

Web endpoints (optional)

synergy/web

SF-004

Discovering applications

Basic protocol

Synergy provides /api/discover endpoint where applications can send HTTP GET request for list of available applications and their application info. Request has to be authenticated using JWT token header (see authentication page ) either for current user or service itself.

Example

HTTP GET https://team1.synergy.example.com/discovery

Response
[{
displayName: "Fibonacci",
address: "http://localhost:8102",
identities: [
{category: "service", type: "computation"}
],
features: [
{
namespace: "synergy/app-info",
attributes: {
url: "http://localhost:8102/services/app-info"
}
},{
namespace: "synergy/health",
attributes: {
url: "http://localhost:8102/services/health"
}
},{
namespace: "synergy/icon",
attributes: {
url: "http://localhost:8102/services/app-icon"
}
}]
},{
displayName: "Plexus Analysis",
address: "http://localhost:9005",
identities: [
{category: "plexus", type: "analysis"},
{category: "application", type: "data-analysis"}
],
features: [
{
namespace: "synergy/app-info",
attributes: {
url: "http://localhost:9005/plexus-analysis/synergy/analysis/app-info"
}
},{
namespace: "synergy/health",
attributes: {
url: "http://localhost:9005/plexus-analysis/synergy/analysis/health"
}
},{
namespace: "synergy/icon",
attributes: {
url: "http://localhost:9005/plexus-analysis/synergy/analysis/app-icon"
}
},{
namespace: "synergy/web",
attributes: {
mainEntryPoint: "http://localhost:9005/plexus-analysis/login"
}
}]
}]

Configuration

Application info uses synergy/app-info namespace and single url attribute.

Example
{
namespace: "synergy/app-info",
attributes: {
url: "http://localhost:8102/services/app-info"
}
}