Server

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserverInformation about REST API internal state

JSON Representation

PropertiesDescriptiontypeOccurs
hrefAuto referenceURI1
name"Server"String1
startDateStarting date of the serverDate1
memoryStatistics about memory usage (mega-bytes)Structure
memory.totalInitialMemoryTotal memory according to the JVM in mega-bytes, before initializing memory cacheInteger1
memory.totalMemoryTotal memory according to the JVM in mega-bytesInteger1
memory.freeMemoryFree memory according to the JVM in mega-bytesInteger1
memory.usedMemoryTotal memory - Free memoryInteger1
requestsStatistics about requestsStructure1
requests.totalCounterTotal number of requestsInteger1
requests.errorsCounterTotal number of requests in errorsInteger1
requests.totalTimeTotal elapsed time of requests millisecondsInteger1
requests.averageTimeTotal elapsed time of requests in millisecondsInteger1
requests.maxTimeLongest elapsed time of all requests in millisecondsInteger1
clientsStatistics about concurrent clientsStructure1
currentConcurrentClientsThe current number of concurrent clients in read time.
Note that  the current request to fetch this information is not included in the count.
Integer1
maxConcurrentClientsThe maximum number of concurrent clientsInteger1
statusServer status either "LOADING" or "READY"String

1

loadDate

Date of Memory cache update. This date is set at start time of

the server or when a reload is requested.

Date1
abortedDomainsArray of aborted domains. An aborted domain is a domain for which loading has failed.Array1
abortedDomains[]An aborted domainStructure0..1
abortedDomains[].nameDomain nameString1
abortedDomains[].loadingDateDate of loading start when the loading has been failedString1
license.status

License status regarding access to Central Bases and measurement base

Use CaseStatusDescription
No LicenseNO_LICENSE_KEYLicense key was not found
INVALID_LICENSE_KEYLicense key is not valid
CANNOT_ACCESS_LICENSE_KEYLicense key file is not readable
INVALID_LICENSE_FILECannot find license key file
LICENSE_EXPIREDWhen license key expired
Restricted LicenseRESTRICTED_LICENSELicense is a restricted license
GLOBAL_ACCESS_TOKENS_EXCEEDED

License is a restricted license,
and quota of global access tokens is exceeded

UNIT_ACCESS_TOKENS_EXCEEDEDLicense is a restricted license,
and quota of unit access tokens is exceeded
Unrestricted LicenseUNRESTRICTED_LICENSELicense is an unrestricted license
String1
license.hrefAuto reference to license detailURI1
license.expirationDateWhen license key expires (present only in new license key)Date1
license.endOfGraceDate30 days grace after license key expiration date (present only in new license key)Date 1
license.usersCountNumber of users connected with this license key (present only in new license key)Integer1
license.usersExcessNumber of users count exceeded after the limit (present only in new license key)Integer1
license.allowedProductsList all allowed products with this license key (present only in new license key)Array1
license.hasNewLicenseKeyType This tells are we using old or new license key typeBoolean1
domainsLocationsGet data source name and schema name for each domain. The ADMINISTRATOR role is required.Structure0..1
recommendedDbVersionThe preferred version of AIP (for compliancy with database schema)

securityMode

This is the configuration value of property security.mode from the application.properties file:

  • "default": authentication based of configuration files
  • "ldap": authentication based on LDAP protocol
  • "saml": authentication based on SAML protocol
String1
samlSingleLogout

This is the configuration value of security.saml.single.logout property from application.properties file.

  • "true": logout action is enabled for "saml" security mode
  • "false": logout action is disabled for "saml" security mode
Boolean1
languagesInstalled translationsArray1
languages[ ]An available locale languageString0..1
reportEnabledCheck whether the configuration variable report. is set report.reportGeneratorBoolean1


JSON Example

GET DEMO
{
	"href": "server",
	"name": "Server",
	"startDate": {
		"time": 1612255923923,
		"isoDate": "2021-02-02"
	},
	"memory": {
		"totalInitialMemory": 109,
		"totalMemory": 125,
		"freeMemory": 44,
		"usedMemory": 81
	},
	"requests": {
		"totalCounter": 20,
		"errorsCounter": 0,
		"totalTime": 18447419617,
		"averageTime": 922370980,
		"maxTime": 929175903
	},
	"clients": {
		"currentConcurrentClients": 0,
		"maxConcurrentClients": 1
	},
	"loadDate": {
		"time": 1612256578092,
		"isoDate": "2021-02-02"
	},
	"abortedDomains": [],
	"status": "READY",
	"version": "X.X.X-XXX",
	"recommendedDbVersion": "8.3.3",
	"license": {
		"status": "NO_LICENSE_KEY"
	},
	"securityMode": "default",
	"samlSingleLogout": false,
	"sessionTimeout": 900,
	"languages": [
		".gitkeep"
	],
	"reportEnabled": false,
	"jiraEnabled": true,
	"domainsBinding": {
		"href": "server/domains-bindings",
		"name": "Domains/schemas bindings"
	},
	"authorizations": {
		"href": "server/authorizations",
		"name": "Authorized applications definitions per users"
	}
}
}


Server Cache Management

Warning

Administrator role is required.

REST server stores portfolio objects, configuration, and snapshots in a memory cache. This memory cache is loaded as soon as the REST Server is started.

An URL allows to reload all domains in memory cache. This action may be required when a new snapshot has been added, and can be performed from a command line with a tool such as "curl":


Use Curl for automation:
C:> curl -u admin:cast -H "Accept: application/json" http://localhost:8080/rest/server/reload


For each domain, Lucene index files can be created to allow components or violations search.

Lucene index files are created at start time and reload time if these options are enabled:

application.properties
# Rebuild Lucene components index on start if outdated (true or false)
rebuildComponentsSearchIndexesOnStart=true
# Rebuild Lucene violations index on start if outdated (true or false)
rebuildViolationsSearchIndexesOnStart=false

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/reload{?parameters}

Sync clients with new domains.

Reload the domains configuration and refresh the server memory cache,
Example of use: A new application onboarding requires to create a new ED domain in the domains.properties file.

The client may receive an HTTP Status 503 "Service not available" if a server/refresh call is already in progress.

In case of intensive traffic, the service awaits for the end of current processing request to start.

This web service has the following effects

  • Reload the configuration of domains (domains.properties file)
  • Reload the server memory cache
  • Rebuild Lucene Indexes
  • Respond a “503 Service unavailable“ to any client during the reload
  • Invalidate the browser cache


GETapplication/jsonserver/refresh{?parameters}

Sync clients with new snapshots.

Refresh the server memory cache when a new snapshot has been added.
Example of Usage:  A new snapshot has been taken for an ED domain.
Example of Usage: AAD domains needs to be refreshed when a new application or a new snapshot has been added.

This processing is made in the background with no interruption for HD clients, and reduced interruption for ED clients.

This web service has the following effects

  • Reload the server memory cache
  • Rebuild Lucene Indexes
  • Respond a "503 Service unavailable to ED clients requesting Lucene index data, whereas this Lucene index is under construction for this specific domain.
  • Invalidate the browser cache

Note: If two concurrent requests are sent for 2 different domains, then these domains will be refreshed in parallel.

Note: onboarding of a new applications must be performed with the "server/reload" or the "server/domains-bindings" web service that will update the domains.properties configuration file and will trigger a "server/reload" service for these domains.


GETapplication/jsonserver/reset

Sync clients after a snapshot reconsolidation, a license key change, or a change of the license.xml file (authorizations in case of restricted license).

The web service reloads the license.key file, the license.xml file and invalidates the browser cache.

Parameters

URI Parameter

Description

Values

Default value

domainSpecify a single domain to reload (for example to refresh a domain after a snapshot)a string$all

DBMS Warm-up Service

Warning

Administrator role is required.

This service fetches data (results, components, violations) for domains hosted in central bases, in order to pre load data in memory afer a DBMS cold restart.

It avoids to penalize first user fetching data.

This service loops on each domain hosted by a central base, and trigger some queries on components, violations and assessment results.


Use Curl for automation:
C:> curl -u admin:cast  http://localhost:8080/rest/server/warmup

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/warmupWarm up DBMS after a cold restart (central base hosts only)


Lucene Index

For each domain, a Lucene index is created to allow the search for components.

Another Lucene index can be created to allow the search for violations.

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
PUTapplication/json{Domain}/components-index

Create or overwrite the components search index for a domain

Warning

Administrator role is required.

GETapplication/json{Domain}/components-indexGet index status for a domain
PUTapplication/json{Domain}/violations-index

Create or overwrite the violations search index for a domain

Warning

Administrator role is required.

GETapplication/json{Domain}/violations-indexGet index status for a domain


JSON Representation

PropertiesDescriptiontypeOccurs
hrefAuto referenceURI1
nameNameString1
status
  • upToDate : Index is up to date
  • N/A : not applicable, no index
  • toUpdate : last snapshot is more recent than the index date, an index rebuild is required
String1
dateIndex file dateDate0..1
lastSnapshotDateLast Snapshot dateDate0..1
sizeIndex file sizeInteger0..1

JSON Example

{
	"href": "ENDTOEND83/components-index",
	"name": "Components search index for applications of ENDTOEND83",
	"status": "upToDate",
	"date": {
		"time": 1496752452859,
		"isoDate": "2017-06-06"
	},
	"lastSnapshotDate": {
		"time": 1493778823000,
		"isoDate": "2017-05-03"
	},
	"size": 4145870
}


Domains Bindings

A Domain binding associates a domain name with a data source name and a schema name.

This resource is based on the use of domains.properties file.

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/domains-bindings

Get all domains bindings

Warning

Administrator role is required.

PUTapplication/jsonserver/domains-bindings

Update the domains bindings, or create new domains bindings.

A triplet (domain, data source, central) is replaced for an existing domain or an existing central, otherwise it is added.

This web service triggers the "reload" service for the domains listed in the payload, in order to update the server memory cache and Lucene index files.

This Web service overwrites the domains.properties file.

Warning

This service accepts the "Authorization" HTTP header to transmit user's credentials, so that a prior call to the login "service" is not required. Thus, we can start the Web Server with an empty list of domains, and bypass the "login" service that prevents connection when no domain is defined.

In case of exception when writing this file, an HTTP Status "403 Forbidden" is returned. Check the permissions of this file.

Warning

Administrator role is required.

Example:

Assuming there are two existing domains AED1, AED2, add a new domain:

[
	{
		"name": "AED3",
		"dataSource": "DEV_CSS2",
		"schema": "appli1_central"
	}
]

Assuming there are three existing domains AED1, AED2, AED3, change schemas for domains AED1, AED2:

[
	{
		"name": "AED1",
		"dataSource": "DEV_CSS2",
		"schema": "appliA_central"
	},
	{
		"name": "AED2",
		"dataSource": "DEV_CSS2",
		"schema": "appliB_central"
	}
]
DELETEapplication/jsonserver/domains-bindings

Update the database binding for a list of domains, or create some new domains with their own bindings.

This web service does not need to trigger the "reload".

This Web service overwrites the domains.properties file.

Warning

This service accepts the "Authorization" HTTP header to transmit user's credentials, so that a prior call to the login "service" is not required. Thus, we can start the Web Server with an empty list of domains, and bypass the "login" service that prevents connection when no domain is defined.

In case of exception when writing this file, an HTTP Status "403 Forbidden" is returned. Check the permissions of this file.

Warning

Administrator role is required.

Example:

Assuming there are two existing domains AED1, AED2, remove domain AED2

[
	{
		"name": "AED2"
	}
]

JSON Representation

PropertiesDescriptiontypeOccurs
nameDomain nameString1
dataSourceData source nameString1
schema

Schema Name

String1

JSON Example

[
	{
		"name": "AED1",
		"dataSource": "DEV_CSS2",
		"schema": "appli1_central"
	},
	{
		"name": "AED2",
		"dataSource": "DEV_CSS2",
		"schema": "appli2_central"
	}
]

Profiles

This resource is based on the use of profiles table.

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/profiles

Get all users' profiles

Warning

Administrator role is required.

PUTapplication/jsonserver/profiles

Update users' profiles. Create or replace profiles

Warning

Administrator role is required.

DELETEapplication/jsonserver/profiles

Delete users' profiles.

Warning

Administrator role is required.


JSON Representation

PropertiesDescriptiontypeOccurs
profileName.nameprofile name
String1
authorizationsAll authorizations for a userArray0..1
authorizations[ ]

An authorization defines which applications can be accessed

Structure1
authorizations[ ].allApplicationsSet applications access to all applicationsBoolean0..1

authorizations[ ].application
authorizations[ ].adgDatabase

Allow access to an application matching application name and adgDatabase name;String0..1
authorizations[ ].applicationPattern
authorizations[ ].adgDatabasePattern
Allow access to all applications matching applicationPattern regular expression and adgDatabasePatern regular expressionString0...1

authorizations[ ].tag
authorizations[ ].category
authorizations[ ].restrictions

Allow access to all applications matching a tag of a categoryString0..1
authorizations[ ].technology
authorizations[ ].restrictions
Allow access to all applications matching a technologyString0..1
authorizations[ ].restrictionsAll restrictions, applicable for authorizations defined with tag, category and technology attributesArray0..1
authorizations[ ].restrictions[ ]A restrictionStructure0..1

authorizations[ ].restrictions[ ].application
authorizations[ ].restrictions[ ].adgDatabase

Deny access to an application matching application name and adgDatabase nameString0..1
authorizations[ ].restrictions[ ].applicationPattern
authorizations[ ].restrictions[ ].adgDatabasePattern
Deny access to all applications matching applicationPattern regular expression and adgDatabasePatern regular expressionString0...1
authorizations[ ].restrictions[ ].tag
authorizations[ ].restrictions[ ].category
Deny access to all applications matching a tag of a categoryString0..1
authorizations[ ].restrictions[ ].technologyDeny access to all applications matching a technologyString0..1
rolesAll roles for a userArray0..1
roles[ ]Defines all roles available for userStructure1
roles[ ].keySpecify which role key String1

JSON Example

[
	{
		"profileName": {
			"name": "GroupWith2Apps_group_profile"
		},
		"authorizations": [
			{
				"application": "Billing platforms",
				"adgDatabase": "demo_709_central",
				"restrictions": []
			},
			{
				"application": "Dream Team",
				"adgDatabase": "adg_contrex_central",
				"restrictions": []
			},
			{
				"application": "TransactionNet",
				"adgDatabase": "ice_800_central",
				"restrictions": []
			}
		],
		"roles": [QUALITY_MANAGER]
	}
]

User Profiles

This resource is based on the use of user_profiles table.

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/user-profiles

Get all users' along with profiles assigned to each user

Warning

Administrator role is required.

PUTapplication/jsonserver/user-profiles

Update users' profiles. Create or replace profiles to users or groups

Warning

Administrator role is required.

WARNING: there is not checking of user/group names validity. 

DELETEapplication/jsonserver/user-profiles

Delete users' profiles.

Warning

Administrator role is required.

JSON Representation

PropertiesDescriptiontypeOccurs
useruser name. Excludes the group property.String1
groupLDAP group name. Excludes the user property.String1
profilesAll profiles for a userArray0..1
profiles[]Defines all profiles available for userStructure1
profiles[].nameSpecify which profiles name String1

JSON Example

[
	{
		"profiles": [
			{
				"name": "admin_profile"
			}
		],
		"user": "admin"
	},
	{
		"profiles": [
			{
				"name": "ATLAS_user_profile",
				"name": "CIO_user_profile"
			}
		],
		"user": "QualityManNoRightsOnCastOldCode"
	}
]


License Key

This resource returns license details. This resource is disabled in INTEGRATED security mode.

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/license-key

Get license key along with its status in dashboard.

Warning

Administrator role is required.

PUTapplication/jsonserver/license-key

Update license key only when key is valid.

Warning

Administrator role is required.

JSON Representation

PropertiesDescriptiontypeOccurs
href
Auto reference to license detailURI1
name"License"String1
keyLoaded valid license keyString1
status

License status regarding access to Central Bases and measurement base

Use CaseStatusDescription
No LicenseNO_LICENSE_KEYLicense key was not found
INVALID_LICENSE_KEYLicense key is not valid
CANNOT_ACCESS_LICENSE_KEYLicense key file is not readable
INVALID_LICENSE_FILECannot find license key file
LICENSE_EXPIREDWhen license key expired
Restricted LicenseRESTRICTED_LICENSELicense is a restricted license
GLOBAL_ACCESS_TOKENS_EXCEEDED

License is a restricted license,
and quota of global access tokens is exceeded

UNIT_ACCESS_TOKENS_EXCEEDEDLicense is a restricted license,
and quota of unit access tokens is exceeded
Unrestricted LicenseUNRESTRICTED_LICENSELicense is an unrestricted license
String1
expirationDate
When license key expires (present only in new license key)Date1
endOfGraceDate
30 days grace after license key expiration date (present only in new license key)Date1
hasLicenseExpired
Specify key has been expired or not (present only in new license key)Boolean1
usersMax
Maximum users allowed with this key (present only in new license key)Integer1
usersExcess
Number of users count exceeded after the limit (present only in new license key)Integer1
usersCount
Number of users connected with this license key (present only in new license key)Integer1
isLicenseExpiring
Tells is license key expiring before 30 days (present only in new license key)Boolean1
allowedProducts
List all allowed products with this license key (present only in new license key)Array1
users
Auto reference to license user detail (present only in new license key)URI1

JSON Example

{
	"href": "server/license",
	"name": "License",
	"key": "CAST:3;INSIGHT/P2,P3,P4:20211231:ZEDZPDYUPS",
	"status": "RESTRICTED_LICENSE",
	"expirationDate": {
		"time": 1640889000000,
		"isoDate": "2021-12-31"
	},
	"endOfGraceDate": {
		"time": 1643481000000,
		"isoDate": "2022-01-30"
	},
	"hasLicenseExpired": false,
	"usersMax": 3,
	"usersExcess": 0,
	"usersCount": 1,
	"users": {
		"href": "server/license/users",
		"name": "Registered users"
	},
	"isLicenseExpiring": false,
	"allowedProducts": [
		"P2",
		"P3",
		"P4"
	]
}

License User Details

This resource manages the list of users connected with new license key. This web service works only for new license key type and disabled in INTEGRATED security mode. 

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication.jsonserver/license/users

Get list of users connected

Warning

Administrator role is required.

DELETEapplication.jsonserver/license/users

Remove users from list

Warning

Administrator role is required.

JSON Representation

PropertiesDescriptiontypeOccurs
userIduser nameString 1
firstLoginDate
first log in date with this userIdDate1
lastLoginDate
last login date with this userIdDate1

JSON Example

[
{
"userId":"admin",
"firstLoginDate":{
"time":1637605800000,
"isoDate":"2021-11-23"
},
"lastLoginDate":{
"time":1637605800000,
"isoDate":"2021-11-23"
}
}
]

Roles definition

This resource returns definition for each roles available in dashboard.

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/roles-definition

Get user roles definition available in dashboard.

JSON Representation

PropertiesDescriptiontypeOccurs
keyrole keyString1
namerole nameString1
descriptionrole descriptionString1

JSON Example

[
	{
		"key": "ADMIN",
		"name": "Admin ",
		"description": "The Admin has rights to access all applications and he has role provides permission to execute reload, reset and refresh dashboard memory, create, update and delete categories and tags."
	},
	{
		"key": "QUALITY_MANAGER",
		"name": "Quality Manager ",
		"description": "The Quality manager role provides permission to add and remove objects from the Action Plan and to use the Engineering Dashboard - Action Plan Recommendation feature."
	},
	{
		"key": "QUALITY_AUTOMATION_MANAGER",
		"name": "Quality Automation Manager ",
		"description": "The Quality automation manager role provides permission to add and remove objects from the Education list."
	},
	{
		"key": "EXCLUSION_MANAGER",
		"name": "Exclusion Manager ",
		"description": "The Exclusion manager role provides permission to add and remove objects from the Exclusion list."
	},
	{
		"key": "CODE_RESTRICTED",
		"name": "Code Restricted ",
		"description": "The Code restricted role prevents users from viewing source code in the Engineering Dashboard."
	}
]

All applications

This resource returns all applications available across all domains from rest API cache.

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/all-applications

Get all applications available across all domains .

Warning

Administrator role is required.

For JSON representation and JSON example check here Application Structure Resources - 2.5#Application

All technologies

This resource returns all technologies available across all domains from rest API cache.

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/all-technologies

Get all technologies available across all domains .

Warning

Administrator role is required.

JSON Representation

This web service returns simple list from REST API cache.

JSON Example

[HTML5, JEE, SQL, JAVA]

Users-Groups

This resource returns list of users and groups based on security mode. This resource is not available in INTEGRATED security mode.

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/users-groups?{parameters}

Get users and groups list for the default security mode, and LDAP/SAML when LDAP is configured

Warning

Administrator role is required.

Query Parameters

Parameter

Description

Values

Default value

prefixSpecify the starting letters of the user name or group name. For LDAP 3 letters are required.a textN/A

JSON Representation

PropertiesDescriptiontypeOccurs
nameuser or group nameString1
type user/group String1

JSON Example

[
	{
		"name": "QualityAutoManNoRightsOnBigBen",
		"type": "user"
	},
	{
		"name": "StaticFileGroupWithNoApps",
		"type": "group"
	},
	{
		"name": "ExclusionManNoRightsOnDreamTeam",
		"type": "user"
	}
]