cibridge-schema.graphqls

# scalar types
# Identifier for the given object
scalar ID

# data type to store values (of any data type specified by the user)
scalar Value

# data type to store datedate information
scalar Date

# data type to store file information
scalar File

# GraphQL root schema
schema {
	# root query type
	query: Query

	# root mutation type
	mutation: Mutation

	# root subscription type
	subscription: Subscription
}

# Root query type
type Query{	
	# Returns all the algorithm factory templates matching the given filter criteria
	getAlgorithmDefinitions(filter: AlgorithmFilter): AlgorithmDefinitionQueryResults!

	# Returns all the algorithm instances matching the given filter criteria
	getAlgorithmInstances(filter: AlgorithmFilter): AlgorithmInstanceQueryResults!

	# Validates the given data that is proposed to be given to the algorithm
	validateData(algorithmDefinitionId: ID!, dataIds: [ID]!): String

	
	# Determines the input format from the referenced data and 	finds the chain of converter algorithms to convert the data to the specified output format
	findConverters(dataId: ID!, outFormat: String!): [AlgorithmDefinition!]!

	# Find the chain of converter algorithms to convert data from given input format to given output format
	findConvertersByFormat(inFormat: String!, outFormat: String!): [AlgorithmDefinition!]!

	
	# Returns references for all the data objects that matches the given filter
	getData(filter: DataFilter): DataQueryResults!

	# Downloads the data associated with the given data reference as a file
	downloadData(dataId: ID!): File!

	
	# Returns the notifications matching the specified criteria given in the filter object
	getNotifications(filter: NotificationFilter!): NotificationQueryResults!

	# Returns if the specified notification is closed or not
	isClosed(notificationId: ID!): Boolean!

	
	# Returns if the scheduler is empty or not
	isSchedulerEmpty: Boolean

	# Returns whether the scheduler is running or paused
	isSchedulerRunning: Boolean

	# Returns the count of the algorithms waiting in the scheduler
	getSchedulerQueueWaiting: Int

	
	# Returns all the logs that matches the given log filter
	getLogs(filter: LogFilter): LogQueryResults!

	
	# TODO: Decide on preferences strategy
	# User Preferences
	# Currently in CIShell Spec, but not used.
	# getUserPreferences(algorithm: AlgorithmDefinition): Preferences
	# getSystemPreferences(algorithm: AlgorithmDefinition): Preferences
	# getSystemPreferences: Preferences

}

# Root mutation type
type Mutation{	
	# Create instance of the given algorithm template using the data references
	createAlgorithm(algorithmDefinitionId: ID!, dataIds: [ID!], parameters: [PropertyInput!]): AlgorithmInstance!

	
	# Uploads a data file and creates the data reference in the data manager
	uploadData(file: File!, properties: DataProperties): Data!

	# Removes the referenced data from the data manager
	removeData(dataId: ID): Boolean!

	# Sets label to the referenced data
	updateData(dataId: ID, properties: DataProperties): Boolean!

	
	# Sends the response from the user for the specified notification
	setNotificationResponse(notificationId: ID!, response: NotificationResponse!): Boolean!

	# Closes the referenced notification
	closeNotification(notificationId: ID): Boolean

	
	# Cancel or uncancel the referenced algorithm based on the passed boolean value. 	Returns the algorithm's new cancelled state.
	setAlgorithmCancelled(algorithmInstanceId: ID!, isCancelled: Boolean): Boolean!

	# Pause or unpause the referenced algorithm based on the passed boolean value. 	Returns the algorithm's new pause state.
	setAlgorithmPaused(algorithmInstanceId: ID!, isPaused: Boolean): Boolean!

	# Removes the given algorithm instance from the system. 	Returns if the algorithm was successfully removed.
	removeAlgorithm(algorithmInstanceId: ID!): Boolean!

	# Schedules an Algorithm to be run immediately. If there are simply not enough resources to run it, 	it will still have to wait until there are enough resources to fulfill the request. 	Returns if the algorithm was successfully started.
	runAlgorithmNow(algorithmInstanceId: ID!): Boolean!

	# Schedule the referenced algorithm at a given date in the scheduler. 	Returns if the algorithm was successfully scheduled.
	scheduleAlgorithm(algorithmInstanceId: ID!, date: Date!): Boolean!

	# Reschedules an already scheduled Algorithm to be run at a different date. 	If the Algorithm is not scheduled already, then this method will have no effect and will return false.
	rescheduleAlgorithm(algorithmInstanceId: ID!, date: Date!): Boolean!

	# Unschedules an already scheduled, but not yet running Algorithm from the scheduler. 	Tries to unschedule an Algorithm from the scheduler.  	Returns if the algorithm was successfully started.
	unscheduleAlgorithm(algorithmInstanceId: ID!): Boolean!

	# Clears all currently scheduled Algorithms to be run. 	If an Algorithm is already running, then it will continue to run until finished. 	Returns the number of algorithms running after clearing the scheduler.
	clearScheduler: Int!

	# Pauses or unpauses the running of new Algorithms in the scheduler
	# Parameters: running - true to pause, false to unpause. 	Returns the new schedule state.
	setSchedulerRunning(running: Boolean): Boolean!

}

# Root subscription type
type Subscription{	
	# Receives the algorithm template when it is added
	algorithmDefinitionAdded: AlgorithmDefinition!

	# Receives the algorithm template when it is removed
	algorithmDefinitionRemoved: AlgorithmDefinition!

	# Receives the algorithm instance when it is updated and is optionally matched by the filter
	algorithmInstanceUpdated(filter: AlgorithmFilter): AlgorithmInstance!

	
	# Receives a new notification when its created
	notificationAdded: Notification!

	# Received a notification when it has been updated
	notificationUpdated: Notification!

	
	# Receives the reference to a data object when it is added to the data manager
	dataAdded: Data!

	# Receives the reference to a data object when it is removed from the data manager
	dataRemoved: Data!

	# Receives the reference to a data object when it is updated
	dataUpdated: Data!

	
	# Receives update when scheduler is cleared. Return value is always false.
	schedulerCleared: Boolean!

	# Receives the current scheduler state when it changes
	schedulerRunningChanged: Boolean!

	
	# Receives new logs matching the log levels specified (or all logs)
	logAdded(logLevels: [LogLevel!]): Log!

}

# type to store info related to pagination. TODO: Finalize our pagination strategy
type PageInfo {
	# Whether there is more data to return in another page
	hasNextPage: Boolean!

	# If there is a previous page of data
	hasPreviousPage: Boolean!
}

# interface used for pageable query results
interface QueryResults {
	# Pagination information
	pageInfo: PageInfo!
}

# Reference to an algorithm instance
type AlgorithmInstance {
	# Reference ID for the algorithm instance
	id: ID!

	# The input data given to the algorithm
	inData: [Data!]

	# Additional parameters given to the algorithm by the user
	parameters: [Property!]

	# The algorithm definition used to create the instance
	algorithmDefinition: AlgorithmDefinition!

	# Current state of the algorithm instance
	state: AlgorithmState

	# Scheduled run time for the algorithm instance
	scheduledRunTime: Date

	# Current progress of the algorithm instance, from 1 to 100
	progress: Int

	# Data outputted after algorithm execution
	outData: [Data!]
}

# Algorithm definition for creating algorithm instances
type AlgorithmDefinition {
	# ID that uniquely identifies the algorithm definition
	id: ID!

	# Input parameters required by the algorithm
	parameters: InputParameters

	# Formats and number of data inputs the algorithm accepts
	inData: [String!]

	# Formats and number of data the algorithm produces
	outData: [String!]

	# A human-readable short name for the algorithm
	label: String

	# A description which provides more details on workings of the algorithm
	description: String

	# If the output Data produced by an instance of this algorithm should be a child 	of the first input Data item (if applicable). If this is set to false or is 	not set at all, then it is up to the algorithm to set up these relationships.
	parentOutputData: Boolean

	# Type of the algorithm. If no type is set, then it is assumed to be of type AlgorithmType.STANDARD
	type: AlgorithmType

	# Specifies if the algorithm can be run remotely. 	If this property is not set, then it is assumed that it cannot be run remotely.
	remoteable: Boolean

	# Specifies where on the menu an algorithm is to be placed if a menu bar is used. 	Otherwise, it can act as a primitive hierarchical classification of the algorithm.
	menuPath: String

	# For converter algorithms, specifies the types of conversion which can be lossy or loseless
	conversion: ConversionType

	# A comma separated list of the authors of the abstract algorithm
	authors: String

	# A comma separated list of the developers who implemented the algorithm in code
	implementers: String

	# A comma separated list of the developers who integrated the algorithm code as a compliant CIShell algorithm
	integrators: String

	# A URL to relevant documentation for the algorithm
	documentationUrl: String

	# A formal reference to a paper explaining the abstract algorithm
	reference: String

	# A URL to a paper explaining the abstract algorithm
	referenceUrl: String

	# A comma separated list of the programming languages used to implement and integrate the algorithm code
	writtenIn: String

	# Additional metadata information apart from standard metadata
	otherProperties: [Property!]
}

# Specifies parameter inputs required for the algorithm
type InputParameters {
	# Identifier for the input parameters object
	id: ID

	# Title to be displayed if presented to the user
	title: String

	# Description
	description: String

	# List of specific parameters
	parameters: [ParameterDefinition!]
}

# Paginated Algorithm Definition Query Results
type AlgorithmDefinitionQueryResults implements QueryResults  {
	# A list of matching algorithm definitions
	results: [AlgorithmDefinition!]!

	# Pagination information
	pageInfo: PageInfo!
}

# Paginated Algorithm Instance Query Results
type AlgorithmInstanceQueryResults implements QueryResults  {
	# A list of matching algorithm references
	results: [AlgorithmInstance!]!

	# Pagination information
	pageInfo: PageInfo!
}

# Input type for filtering algorithms based on
input AlgorithmFilter {
	# list of algorithm definition IDs to match on
	algorithmDefinitionIds: [ID!]

	# list of AlgorithmInstance IDs to match on
	algorithmInstanceIds: [ID!]

	# list of algorithm states to match on
	states: [AlgorithmState!]

	# List of reference ids to the input data to match on
	inputDataIds: [ID!]

	# list of formats of the input data to match on
	inputFormats: [String!]

	# list of formats of the output data to match on
	outputFormats: [String!]

	# A list of key/value pairs to match on in the algorithm metadata
	properties: [PropertyInput]

	# Maximum number of items to fetch while filtering
	limit: Int

	# Number of items to skip while matching
	offset: Int
}

# Specifies the current state of the algorithm instance
enum AlgorithmState {
	# The algorithm was cancelled by the user
	CANCELLED

	# The algorithm encountered error during the run
	ERRORED

	# The algorithm finished executing
	FINISHED

	# The algorithm is created and waiting to be scheduled
	IDLE

	# The algorithm is paused
	PAUSED

	# The algorithm is running currently
	RUNNING

	# The algorithm is scheduled and waiting to be executed
	SCHEDULED

	# The algorithm is waiting for user input
	WAITING
}

# The specific types of algorithm
enum AlgorithmType {
	# A type of algorithm for converting data of one type to another. 	TODO: make converters be a separate entity from Algorithms
	CONVERTER

	# A type of algorithm for providing pre-generated data for use in the CIShell platform
	DATASET

	# The default type of algorithm
	STANDARD

	# A type of algorithm which checks either an incoming or outgoing file to be sure it is of the type specified
	VALIDATOR
}

# For the converter algorithms, it specifies if any data is lost in the conversion
enum ConversionType {
	# Specifies the type of data conversion where no data is lost
	LOSSLESS

	# Specifies the type of data conversion where some data can be lost
	LOSSY
}

# Reference to data stored on the server
type Data {
	# Reference ID to the data
	id: ID!

	# format of the data
	format: String!

	# A short label to give the Data object for shorter displays. It is recommended to keep the string length below 20 characters
	name: String

	# The label to give the data object if displayed
	label: String

	# The parent data object of the data object. 	This is used when a data object is derived from another data object to show the hierarchical relationship between them. 	This property can be null, signifying that the data object was not derived from any other data object, 	such as when loading a new data object from a file.
	parentDataId: ID

	# Specifies the general type of the data
	type: DataType

	# Flag to determine if the Data object has been modified and not saved since the modification. 	This is used to do things like notify the user before they exit that a modified Data object exists and ask if they want to save it.
	isModified: Boolean

	# Other metadata information related to the data
	otherProperties: [Property!]
}

# Paginated Algorithm Definition Query Results
type DataQueryResults implements QueryResults {
	# A list of matching algorithm references
	results: [Data!]!

	# Pagination information
	pageInfo: PageInfo!
}

# Input type to filter data objects
input DataFilter {
	# list of data IDs to match on
	dataIds: [ID!]

	# Filter the data objects based on the given formats
	formats: [String!]

	# Filter the data by modified state
	isModified: Boolean

	# Filter the data by data types
	types: [DataType!]

	# A list of key/value pairs to match on in the algorithm metadata
	properties: [PropertyInput]

    # Maximum number of items to fetch while filtering
    limit: Int

    # Number of items to skip while matching
    offset: Int
}

# Input type for uploading new data or updating existing ones
input DataProperties {
	# format of the data
	format: String

	# A short label to give the Data object for shorter displays. It is recommended to keep the string length below 20 characters
	name: String

	# The label to give the data object if displayed
	label: String

	# The parent data object of the data object. 	This is used when a data object is derived from another data object to show the hierarchical relationship between them. 	This property can be null, signifying that the data object was not derived from any other data object, 	such as when loading a new data object from a file.
	parent: String

	# Specifies the generic type of the data
	type: DataType

	# Other metadata information related to the data
	otherProperties: [PropertyInput!]
}

# Enum type to specify the general type of data objects
enum DataType {
	# The data model is abstractly a database
	DATABASE

	# The data model is abstractly a matrix
	MATRIX

	# the data model is a 'model' object
	MODEL

	# The data model is abstractly a network
	NETWORK

	# The data model is abstractly a data plot
	PLOT

	# The data model is a JPEG object
	RASTERIMAGE

	# The data model is an 'R Instance' object
	RINSTANCE

	# The data model is abstractly a table
	TABLE

	# The data model is abstractly a plain text file
	TEXT

	# The data model is abstractly a tree
	TREE

	# The data model is abstractly an unknown type
	UNKNOWN

	# The data model is a PostScript file
	VECTORIMAGE
}

# Type to create client side notifications
type Notification {

	# Identifier for the object
	id: ID

	# Type of the notification
	type: NotificationType

	# Short title of the notification
	title: String

	# Message of the notification
	message: String

	# Detailed description for the notification
	detail: String

	# A stack trace of the error to be shown, where applicable
	stackTrace: [String!]

	# List of parameters which includes the type, name, description and options for dropdown boxes
	formParameters: [ParameterDefinition]

	# Says if the notification is closed
	isClosed: Boolean

	# If the notification type is FORM, response from the user as a list of key:value mappings
	formResponse: [Property!]

	# If the notification type is QUESTION, whether the user pressed Yes or No
	questionResponse: Boolean

	# If the notification type is CONFIRM, whether the user pressed Ok or Cancel
	confirmationResponse: Boolean
}

# Paginated Notification Query Results
type NotificationQueryResults implements QueryResults  {
	# A list of matching notification references
	results: [Notification!]!

	# Pagination information
	pageInfo: PageInfo!
}

# Input filter to match notifications
input NotificationFilter {
	# list of notification IDs to match on
	ids: [ID!]

	# Filter the data by isClosed state
	isClosed: Boolean

	# Maximum number of notifications that will be matched against the filter
	limit: Int

	# Number of items to skip while matching
	offset: Int
}

# Input to send the user response to a notification
input NotificationResponse {

	# If the notification type is FORM, response from the user as a list of key:value mappings
	formResponse: [PropertyInput!]

	# If the notification type is QUESTION, whether the user pressed Yes (true) or No (false)
	questionResponse: Boolean

	# If the notification type is CONFIRM, whether the user pressed Ok (true) or Cancel (false)
	confirmationResponse: Boolean

	# If the notification should be closed as part of the response
	closeNotification: Boolean
}

# Specifies the general type of notifications
enum NotificationType {
	# Type of alert notifications to inform the user of important fact and requires user confirmation before preceeding
	CONFIRM

	# Type of notifications to report an error or a problem that has occured
	ERROR

	# Type of notifications to ask form inputs from user
	FORM

	# Type of notifications to simply inform the user about a situation
	INFORMATION

	# Type of notifications that asks the user whether an action should proceed or not. It can be a simple YES or NO question.
	QUESTION

	# Type of notifications to warn user of a situation which requires user's attention
	WARNING
}

# Object type for logging
type Log {
	# Level at which the logs will be logged
	logLevel: LogLevel

	# Log message
	message: String

	# An optional list of strings for logging errors
	stackTrace: [String!]

	# Timestamp when the log was triggered
	timestamp: Date
}

# Paginated Log Query Results
type LogQueryResults implements QueryResults  {
	# A list of matching log references
	results: [Log!]!

	# Pagination information
	pageInfo: PageInfo!
}

# Filter input type to match logs with certain criteria
input LogFilter {
	# Matches all the logs specified in the log level list
	logLevel: [LogLevel!]

	# Matches all the logs logged since a certain timestamp
	logsSince: Date

	# Matches all the logs logged before a certain timestamp
	logsBefore: Date

	# Maximum number of log objects to be fetched per query
	limit: Int

	# Number of items to skip while matching
	offset: Int
}

# Severity level for the logs
enum LogLevel {
	# The most granular log level. Used for debugging and may be irrelevant to anyone but the algorithm developer.
	DEBUG

	# Indicates a problem occured while executing algorithm or services.
	ERROR

	# Used for providing information about and while hte algorithm is executing. Does not indiate a problem.
	INFO

	# Indicates the algorithm will still be executed, but that outputs may not be what was expected.
	WARNING
}

# Generic Property type to store key:value mappings
type Property {
	# Key of the property
	key: String!

	# Value mapped to the key. The data type for the field is left for the user to decide
	value: Value!

	# Type of attribute the property stores eg. integer, boolean, etc.
	attributeType: AttributeType
}

# Definition of the attributes for the user entered parameters which includes name, type and options for dropdown boxes
type ParameterDefinition {
	# Identifier for the attribute
	id: String!

	# Name for the attribute
	name: String!

	# Description
	description: String!

	# Type of the attribute
	type: AttributeType!

	# cardinality of values (a single value, an array or a list) the attribute can have
	cardinality: Int!

	# The default values the attribute can take. A default values are an array of String objects
	defaultValues: String

	# Options for the dropdown boxes
	options: [Property!]
}

# Generic Property input type to pass key:value mappings over queries and mutations
input PropertyInput {
	# Key of the property
	key: String!

	# Value mapped to the key. The data type for the field is left for the user to decide
	value: Value!

	# Type of attribute the property stores eg. integer, boolean, etc.
    attributeType: AttributeType
}

# Specifies several primitive data types for ParameterDefinition
enum AttributeType {
	# Boolean has only two possible values: true and false
	BOOLEAN

	# A single byte signed two's complement integer. It has a minimum value of -128 and a maximum value of 127
	BYTE

	# A 2-Byte unicode character. It has minimum value of 0 and maximum value of 65,535
	CHARACTER

	# A double-precision 8-Byte IEEE 754 floating point
	DOUBLE

	# A single-precision 4-Byte IEEE 754 floating point
	FLOAT

	# A 4-Byte signed two's complement integer
	INTEGER

	# A 8-byte signed two's complement integer
	LONG

	# A 2-Byte signed two's complement integer
	SHORT

	# A sequence of characters
	STRING
}