System APIs
There are two flavors of system API available, either directly via the Message Queue, or via the internal services in the Web Application.
Message Queue API
The message queue API is based on connecting to the RabbitMQ RPC Message Queue and publishing a JSON request. These requests share a set of common attributes, as well as each having additional request specific attributes. Common Attributes are:
{
"userId":"GUID of the user",
"type":"type from list below"
}
userId is required so that returned results can be filtered based on the user's access privileges.
All requests return DataReturn Object that consists of a status field and data field. If status is ERROR, then the data field is the error message. If status is OK, then the data field is the requested data.
If the information below the return values are generally JSON serializations of objects in the vs-dtolib source project.
applicationlist
Purpose: Get a list of applications from meta data database filtered by the User's access privileges.
Additional request parameters: none
Returns: Array of Applications
application
Purpose: Retrieve details of a single application
Additional request parameters:
appId - id of the application
Returns: Application
metric
Purpose: Retrieve details of a single metric.
Additional request parameters:
appId - the id of the application
id - the id of the metric
Returns: Metric
metrichier
Purpose: Retrieves a list of all metrics in an application, and their location in the metric Hierarchy
Additional request parameters:
appId - id of the application
Returns: List of metrics.
groupchildren
Purpose: Retrieve a list of children of a specific org hierarchy group.
Additional request parameters:
appId - id of the application
id - the hierarchy path of the parent group.
Returns: List of GroupHierInfo Objects.
validsummarygroups
Purpose: Retrieves a list or groups that can be related to the requested group for summary levels in a report.
Additional request parameters:
appId - id of the application
id - the id of the group primary group.
Returns: List of GroupHierInfo Objects
groupfolderhier
Purpose: Retrieves the group type hierarchy
Additional request parameters:
appId - the id of the application
Returns: List of GroupHierInfo objects, one for every type in the hierarchy.
datalayout
Purpose: Retrieve a songle complete data layout
Additional request parameters:
id - the id of the data layout
Returns: a DataLayout object
reportdata
Purpose: Retrieve data for populating a report
Request parameters:
{ "type":"reportdata", "userId":"5dab423d-3368-4446-8cb5-bfb38b32ea59", "appId":"appid", "startDate":"start date/time of report MM/DD/YYYY HH:mm:ss", "endDate":"End date/time of report MM/DD/YYYY HH:mm:ss", "timeLevel":"Reporting time level, cum,interval,hour,day,week,month or year", "baseGroup":"Path of primary filter group", "summaryLevels":"Comma sepearted list of group types to summarize by", "metricList":"Comma seperated list of metrics", "blocksize":"Number of rows in one return block", "blockNum":"Block number to return", "timeZone":"Optional, timezone to use" }Returns: MetricDataRequestResults Object
drillgroups
Purpose: Retrieves a list of groups that are valid to drill into from a specific group
Additional request parameters:
appId - id of the application
id - the hierarchy path of the group to check.
Returns: List of GroupHierInfo
childfolders
Purpose: Retrieve a list of folders that are children of a specific group in the hierarchy.
Additional request parameters:
appId - the id of the application
id - the hierarchy path of the parent group. Returns:
detaildata
Purpose: Retrieve the data to pupulate a detail search result.
Request parameters:
{
"type":"detaildata",
"userId":"5dab423d-3368-4446-8cb5-bfb38b32ea59",
"appId":"appid",
"startDate":"start date/time of report in MM/DD/YYYY HH:mm:ss format",
"endDate":"end date/time of report in MM/DD/YYYY HH:mm:ss format",
"baseGroup":"Path to primary filter group",
"detailId":"id of the detail definition",
"fieldList":"comma separated list of detail field numbers to return",
"aggOptions":"comma separated list of agg options for fields above.(group,min,max,sum)",
"aggType":"Type of aggregation to use: none,totals,group",
"blockSize":"number of rows to return in one block",
"blockNumber":"block number to return",
"filterFields":"delimted list of fields used in filters (one field per filter) delimiter is specified in filterDelim",
"filterConds":"delimited list of filter operators, delimiter specified by filterDelim".
"filterValues":"delimited list of comparison values, delimiter specified by filterDelim",
"filterLink":"if filters defined, how to assess multiple filters: all or any",
"filterDelim":"`",
"timeZone":"Optional timezone of request"
}
Returns: DetailDataRequestResults object
detaillist
Purpose: Retrieves a list of all detail definitions in an application
Additional request parameters:
appId - the id of the application
Returns: List of DetailDef objects
detaildef
Purpose: Retrieve all details of a specific detail data definition
Additional request parameters:
appId - the id of the application
id - the id of the detail definition
Returns: a DetailDef object
validateuser
Purpose: Validates a username and password combination. Note this does not require the standard parameters.
Request parameters:
username: the users username.
password: the users password.
Returns: SecUser object for the user is the combination is valid, null otherwise.
savedisplay
Purpose: Save the parameters that define a report,chart,or detail search for easy retrieval.
Additional request parameters:
ownerUid - userId of display owner, defaults to userId
folderId - folder of display.
displayId - id of display, if null or missing, new id generated.
displayName - name of display.
displayDesc - description.
displayType - Detail,Report,Chart or Dashboard.
displayData - The data request JSON used to generate the display.
Returns: The SavedDisplay object updated with the assigned id.
getdisplay
Purpose: Retrieve a saved display
Additional request parameters:
id - the id of the display.
Returns: SavedDisplay Object
updatedisplayheader
Purpose: Update meta data info about a saved display (name, description, etc).
Additional request parameters:
display - JSON string representation of SavedDisplay Object.
Returns: SavedDisplay object updated as appropriate
updatedisplayheaders
Purpose: Update meta data info for multiple saved displays (name, description, etc).
Additional request parameters:
display - Array of JSON string representations of SavedDisplay Objects.
Returns: List of SavedDisplay objects updated as appropriate
listdisplay
Purpose: Retrieves a list of displays available to the user.
Additional request parameters: none Returns: List of SavedDisplay Objects
listfolders
Purpose: Retrieves a list of saved display folders that a user has access to.
Additional request parameters: none Returns: an object with list of SavedDisplayFolder objects, one named owned and one named shared.
savefolder
Purpose: Save a folder for organizing saved displays
Additional request parameters:
folderId - the id of the folder, new id will be genrated if null or missing.
folderName - the name of the folder.
parentId - the id of the parent folder, optional for top level folders.
Returns: SavedDisplayFolder object updated as appropriate
deletefolder
Purpose: Deletes a saved display folder
Additional request parameters:
id - the id of the folder to delete
Returns: status only
userbyname
Purpose: Retrieve info about a user by username
Additional request parameters:
username - the username to retrieve
Returns: SecUser object
userbyid
Purpose: Retrieve info about a user by userid
Additional request parameters: none
Returns: SecUser object
homepage
Purpose: Sets a user's homepage
Additional request parameters:
displayId - the id of the display to use as a home page.
Returns: status only.
changepass
Purpose: Change a user's password
Additional request parameters:
oldPassword - the user's original password.
newPassword - the new password.
Returns: -1 if user not found, -2 if old password is incorrect, 1 if successful.
deletedisplay
Purpose: Delete a saved display
Additional request parameters:
displayId - id of the display to delete
Returns: status only
timeperiods
Purpose: Retrieve a list of predefined time periods.
Additional request parameters: none Returns: List of RelTimePer objects.
ungroupedmetrics
Purpose: Retrieve a list of metrics that have not been asigned to a folder in the hierarchy.
Additional request parameters:
appId - the id of the application
Returns: List of upgrouped Metric objects.
savemethier
Purpose: Save the metric organization to the database.
Additional request parameters:
folders - List of MetricHier objects representing the folders in the hierarchy.
members - list of MetricHierMemb objects assigning metrics to folders.
Returns: status only.
listdataroles
Purpose: Retrieve a list of defined security data roles.
Additional request parameters: none
Returns: List of SecRoleDataListItem objects
listfuncroles
Purpose: Retrieve a list of defined security functional roles.
Additional request parameters: none
Returns: List of SecRoleFunc objects.
listusers
Purpose: Retrieve a list of defined users.
Additional request parameters: none
Returns: List of SecUserListItem objects.
getdatarole
Purpose: Retrieve details of specific data role.
Additional request parameters:
id - the id of the data role.
Returns: SecRoleData object.
getfuncrole
Purpose: Retrieve a details of specific functional role.
Additional request parameters:
id - the id of the role.
Returns: SecRoleFunc object.
getuser
Purpose: Retrieve details of specific user.
Additional request parameters:
id - id of the user.
Returns: SecUser object.
savedatarole
Purpose: Save details of a data role.
Additional request parameters:
data - JSON representation of a SecRoleData Object. if role id of object is empty or null, new role is created.
Returns: SecRoleData updated as appropriate.
savefuncrole
Purpose: Save a functional role definition.
Additional request parameters:
data - JSON representation of SecRoleFunc. If id is null or empty, new role is created.
Returns: SecRoleFunc updated as appropriate.
saveuser
Purpose: Save a user definition to the database.
Additional request parameters:
data - JSON representation of a SecUserObject. If id is null or missing, new user is created.
Returns: Updated SecUser Object.
deleteuser
Purpose: Delete a user.
Additional request parameters:
id - id of the user to delete.
Returns: status only.
deletedatarole
Purpose: Delete a Data Role.
Additional request parameters:
id - id of the role to delete.
Returns: status only.
deletefuncrole
Purpose: Delete a functional role.
Additional request parameters:
id - id of the role to delete.
Returns: status only.
getroleshareddisplay
Purpose: Get a list of saved displays shared to a data role.
Additional request parameters:
id - id of the role.
Returns: List of SharedDisplay objects.
getusershareddisplay
Purpose: Get a list of displays shared to a specific user.
Additional request parameters:
id - id of the user.
Returns: List of SharedDisplay objects.
getuserowneddisplay
Purpose: Get a list of displays owned by a user.
Additional request parameters:
id - id of the user.
Returns: List of SharedDisplay objects.
getbaseprivs
Purpose: Get the list of base functional privileges.
Additional request parameters: none
Returns: list of SecBasePriv objects.
getuserswithdisplays
Purpose: Get a list of users that have saved displays.
Additional request parameters: none
Returns: List of SecUserListItem Objects.
HTTP API
The HTTP API is used by the web application to access data from the back end services. In most cases, they are nothing more than a web wrapper around the Message Queue calls in the previous section. They are not currently intended for consumption outside the Vistalsigns Web Application and as such, require that the logon API be called first to establish a session.
Get Methods
/users/homepage
Purpose: Retrieve the id of the current users homepage.
Parameters: none
Returns: the id of the homepage.
/userapi/displays
Purpose: List displays for active user
Parameters: none
Returns: List of SavedDisplay object
/userapi/displays/:id
Purpose: Retrieve the details of save display
Parameters: :id - the id of the display
Returns: SavedDisplay object
/userapi/displayfolders
Purpose: Retrieve the list of saved display folders for the active user.
Parameters: none
Returns: list of SavedDisplayFolder
/userapi/displayfolders/:id
Purpose: Retrieve the details of saved display folder
Parameters: :id - the id of the folder
Returns: SavedDisplayFolder object
/users/user
Purpose: Get details of current user
Parameters: none
Returns: SecUser without the password or role information.
/top/timeperiods
Purpose: get a list of predefined time periods
Parameters: none
Returns: List of RelTimePEr
/top/groupchildren
Purpose: Get a list of children for a hierarchy group
Parameters:
appId - the id of the application
id - hierarchy path of parent group
Returns: List of GroupHierInfo objects
/callsumm/apps
Purpose: get a list of applications accessible to the user
Parameters: none
Returns: List of Application Objects
/callsumm/columns
Purpose: Retrieve a list of metrics and location in the metric hierarchy
Parameters: appid - the id of the application
Returns: List MetricHierInfo objects
/callsumm/drillgroups
Purpose: Get the list of groups available to drill from a specific group
Parameters:
appId - id of the Application
id - Hierarchy Path of parent group
Returns: List of GroupHierInfo Objects
/callsumm/summs/
Purpose: Get the list of child folders for a particular hierarchy group
Parameters:
appId - the application Idid - the id of the parent group
Returns: List of GroupHierInfo Objects
/callsumm/detaildef/
Purpose: Retrieve a specific detail definition
Parameters:
appId - the application id
id - the id of the detail definition
Returns: DetailDef object
/callsumm/ungrouped
Purpose: Retrieve the list of ungrouped metrics
Parameters:
appId - the id of the application
Returns: List of Metric objects
Note - the following admin APIs require the user to have the admin security privilege.
/admin/api/users
Purpose: Retrieve the list of Users
Parameters: none
Returns: List of SecUserListItem
/admin/api/users/withdisplays
Purpose: Retrieve a list of Users who own saved displays
Parameters: none
Returns: List of SecUserListItem
/admin/api/users/:id
Purpose: Retrieve the details of a sepcific User
Parameters: :id the id of the user
Returns: SecUserList Object
/admin/api/applications
Purpose: List all applications
Parameters: none
Returns: List of Application objects
/admin/api/applications/:id
Purpose: Retrieve details of specific Application
Parameters: :id - the id of the Application
Returns: Application Object
/admin/api/applications/:id/metrichier
Purpose: Retrieve the metric hierarchy of an application
Parameters: :id - the id of the Application
Returns: Application Object
/admin/api/applications/:id/detail
Purpose: Retrieve the list of detail definitions in an application
Parameters: :id - the id of the Application
Returns: List of DetailDef objects
/admin/api/applications/:id/detail/:detailid
Purpose: Retrieve a specific detail definition in an application
Parameters:
:id - the id of the Application
:detailId - the detail id
Returns: DetailDef object
/admin/api/funcroles/baseprivs
Purpose: List all of the base privileges
Parameters: none
Returns: List of SecBasePriv
/admin/api/funcroles
Purpose: List all of the Functional Roles
Parameters: none
Returns: List of SecRoleFunc Objects
/admin/api/funcroles/:id
Purpose: Retrieve a specific Functional Role
Parameters: :id the id of the role
Returns: SecRoleFunc Object
/admin/api/dataroles
Purpose: List all Data Roles
Parameters: none
Returns: List of SecRoleData
/admin/api/dataroles/:id
Purpose: Retrieve details of a specific data role`
Parameters: :id - the id of the role
Returns: SecRoleData Object
/admin/api/displays/owned/:userId
Purpose: Retrieve list of displays owned by a user
Parameters: :userId - id of the user
Returns: List of SavedDisplay Objects
/admin/api/displays/shared/role/:roleId
Purpose: Retrieve a list of displays shared to a data role
Parameters: :roleId - the id of the data role
Returns: List of SavedDisplay Objects
/admin/api/displays/shared/user/:userId
Purpose: Retrieve a list of displays shared to a User
Parameters: :userId - the id of the user
Returns: List of SavedDisplay Objects
/admin/api/displays/display/:id
Purpose: Retreive details of specific saved display
Parameters: :id - id of the saved display
Returns: SavedDisplay Object
Post methods
Note parameters are a JSON object in the request body
/api/v1/query
Purpose: Get report data
Parameters:
{ "type":"reportdata", "appId":"appid", "startDate":"start date/time of report MM/DD/YYYY HH:mm:ss", "endDate":"End date/time of report MM/DD/YYYY HH:mm:ss", "timeLevel":"Reporting time level, cum,interval,hour,day,week,month or year", "baseGroup":"Path of primary filter group", "summaryLevels":"Comma sepearted list of group types to summarize by", "metricList":"Comma seperated list of metrics", "blocksize":"Number of rows in one return block", "blockNum":"Block number to return", "timeZone":"Optional, timezone to use" }Returns: MetricDataRequestResults Object
/api/v1/detailquery
Purpose: Get data for a detail search
Parameters:
{ "type":"detaildata", "appId":"appid", "startDate":"start date/time of report in MM/DD/YYYY HH:mm:ss format", "endDate":"end date/time of report in MM/DD/YYYY HH:mm:ss format", "baseGroup":"Path to primary filter group", "detailId":"id of the detail definition", "fieldList":"comma separated list of detail field numbers to return", "aggOptions":"comma separated list of agg options for fields above.(group,min,max,sum)", "aggType":"Type of aggregation to use: none,totals,group", "blockSize":"number of rows to return in one block", "blockNumber":"block number to return", "filterFields":"delimted list of fields used in filters (one field per filter) delimiter is specified in filterDelim", "filterConds":"delimited list of filter operators, delimiter specified by filterDelim". "filterValues":"delimited list of comparison values, delimiter specified by filterDelim", "filterLink":"if filters defined, how to assess multiple filters: all or any", "filterDelim":"`", "timeZone":"Optional timezone of request" }Returns: DetailDataRequestResults
/userapi/displays
Purpose: Save a user display
Parameters: folderId - folder of display.
displayId - id of display, if null or missing, new id generated.
displayName - name of display.
displayDesc - description.
displayType - Detail,Report,Chart or Dashboard.
displayData - The data request JSON used to generate the display.
Returns: Status of 0 for success -1 for error.
/userapi/displayfolders/
Purpose: Saves a display folder
Parameters:
folderId - the id of the folder, new id will be genrated if null or missing.folderName - the name of the folder.
parentId - the id of the parent folder, optional for top level folders.
Returns: Status of 0 for success -1 for failure.
/users/changepassword
Purpose: Change the active user's password
Parameters: oldPassword,newPassword
Returns: -1 if user not found, -2 if old password is incorrect, 1 if successful.
/users/login
Purpose: Log a user into the system and establish a session
Parameters: username,password
Returns: Status 0 for fail, 1, for success, 2 for success but force password change.
/admin/api/users
Purpose: Save the details of a sepcific User
Parameters: JSON SecUser object
Returns: Updated SecUserList Object
/admin/api/funcroles
Purpose: Save a Functional Role
Parameters: Json SecRoleFunc object
Returns: Updatd SecRoleFunc Object
/admin/api/dataroles
Purpose: Save a Data Role
Parameters: JSON SecRoleData
Returns: Updated SecRoleData
Delete Methods
/userapi/displays/:id
Purpose: Delete a saved display
Parameters: :id - the id of the display
Returns: status Only
/userapi/displayfolders/:id
Purpose: Delete a saved display folder
Parameters: :id - the id of the display
Returns: status Only
/admin/api/users/:id
Purpose: Delete a sepcific User
Parameters: :id the id of the user
Returns: status only
/admin/api/funcroles/:id
Purpose: Delete a Functional Role
Parameters: :id - the id of the role
Returns: status only
/admin/api/dataroles/:id
Purpose: delete a Data Role
Parameters: :id - id of the role
Returns: status only