SF-001 Application info

Namespace: synergy/app-info 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 - is an area, functionality or capability that is described in this block.

• type - the quality or implementation of the category.

Values of the categories and types are validated and should be set according to this documentation otherwise the registration will be blocked. The following categories are mandatory but other custom ones can be added without any limitation.

category	type
application	webapp
	service
group	reporting
	registration
	design
	compliance
	computation
	search
	eln
	inventory
vendor	chemaxon
product	plexus-connect
	compound-registration
	assay
	marvin-live
	compliance-checker
	chemlocator
	navigator

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" 
    }
}