Standard GELLO REST Query

A GELLO query can be made to the server at the following address with a HTTP POST message.

or

POST request format using JSON

{
"Debug": string,
"Packages": [
{ "Name": string,
"Code": string
}
.....],
"ModelData": { ..... },
"Requests": [ 
{
"RequestId": string, 
"GelloCode": string
},
.....] 
}

Debug (optional) is character string with a list of debug options that control debug information returned in the reply.

ModelData (optional) If the GELLO expression contains a Context statement, the data for the context can be supplied. It must have the same GELLO type as that of the Context statement. Errors may be reported, or data may not be visible if the class of the Context statement does not match that of the ModelData.

Packages (optional) is an array of objects containing package name and source code for supplied package. This can be used to supply additional packages for loading model data and for generating GELLO results. Note - only class attributes (properties) will have any meaning in the uploaded packages, and also operations (methods) which are written in pure GELLO. Any operations which are defined by an embedded package will not be operate correctly, and most likely return null GELLO values.

Requests (required) is a JSON array containing a list of GELLO queries to be made against the Patient Context

Each request contains the following JSON object

RequestId (required) is a unique Identifier supplied by the user to identify multiple jobs within the request. It should not be empty or null. Each request should contain a unique ID.

GelloCode (required) is a string containing a valid GELLO query to be executed in the HL7 context. It may contain contain white space and line breaks, but these should be escaped according to JSON rules.

POST reply from server

{
"Results": [ 
{
"debugVarTypes": [string, .....],
"debugVars": { .... }
"debugImports" [string, .....]
"requestId": string, 
"wasSuccessful": boolean, 
"errors": [string, .....],
"result": { ..... },
},
.....] 
}

Results (required) is a JSON array containing a list of results from the GELLO queries made.

Each result contains the following JSON object. Results may appear out of order but can be collated via the RequestId parameter.

requestId (required) matches one and only one requestId in the Request.

wasSuccessful (required) contains boolean true or false, representing whether the GELLO query was successful or not.

result (optional) contains the result of the GELLO query in JSON format. The contents of this is dependent on the nature of the GELLO query. It may be missing or null if the GELLO expression failed.

errors (optional) contains a string list of any errors encountered in compiling and/or executing the GELLO query, and should contain at least one item if wasSuccessful returned false. It may be missing or empty if the GELLO expression was successful.

The following parameters will be returned when Debugging options are set.

debugVarTypes (optional) a list of formal type names for the debugVars as seen by the compiler.

debugVars (optional) a tuple object containing a list of the Let variables.

debugImports (optional) a list of package names used by the GELLO expression.

Example

Here is some example Gello you can try:

Let x:Integer = 50
Let a:Integer = 10
Let y:Real = ((a + x)*2) min 10
Let yy:Real = -y max 20
Let s:String = "12312313"
Let z:Real = y + 20.5
Let s1:String = s.concat(' ').concat(z.toChar())
s1

Request

{
"Debug": "V,I",
"Packages": [
],
"Requests": [
{
"RequestId": "1",
"GelloCode": "Let x:Integer = 50\r\nLet a:Integer = 10\r\nLet y:Real = ((a + x)*2) min 10\r\nLet yy:Real = -y max 20\r\nLet s:String = \"12312313\"\r\nLet z:Real = y + 20.5\r\nLet s1:String = s.concat(' ').concat(z.toChar())\r\ns1\r\n"
}
]
}

Reply

{
"Results": [
{
"requestID": "1",
"debugVarTypes": [
"Integer",
"Integer",
"Integer",
"Real",
"String",
"Real",
"String",
"String"
],
"debugVars": {
"#type": "Tuple",
"x": 50,
"a": 10,
"y": 10,
"yy": 20,
"s": "12312313",
"z": 30.5,
"s1": "12312313 30.5",
"_Result_": "12312313 30.5"
},
"debugImports": [
"System",
"Main"
],
"wasSuccessful": true,
"result": "12312313 30.5"
}
]
}

Formatting

Requests and Responses are formatted using JSON. Fields of JSON objects may appear in a different order to that documented. However for efficient JSON streaming in the future, some fields should be in the preferred order. In particular, Packages should precede ModelData, and ModelData should precede GELLO requests.

Compact JSON type inference[edit]
Normally, the GELLO type for data will be known before loading a JSON value into a class, however there are occasions where OCL types can be inferred from the JSON output. The following rules describe how these OCL types can be inferred.

JSON number ---> OCL "Real"

JSON string ---> OCL "String"

JSON boolean (true/false) ---> OCL "Boolean"

JSON null ---> OCL "Any" with oclIsDefined property = False

JSON array ---> OCL "Sequence(Any)". Usually the element type can be inferred also however, the array may contain mixed types.

JSON object ---> OCL class with class name contained in the "#type" class property. If this is omitted or of value "Tuple" it is assumed to be an OCL Tuple.

There are some minor exceptions to the above. A Real may have the values NaN, +Inf and -Inf, in which case it is represented as a OCL class of type "Real" with a sub property of "value" containing the string representation of the exceptional Real value. An Integer is descendant of class Real, and could be inferred from the additional regex "\-?[0-9]+/", however JSON does not make this distinction, and the GELLO engine will perform the necessary conversion if required.

A null class may be defined by creating an object with the elements #type = <class name> and #undefined = true. Optionally one can add exception messages with #exception = string

Additional GELLO IDE support requests

When used in conjunction with the GELLO IDE, some additional requests can be made. The remote GELLO server and the GELLO IDE may have different packages automatically loaded. The installedmodels request can be used to determine which models the server is built with.

request format

{
"namesOnly": boolean,
"asGello": boolean
}

namesOnly (required) list only the names of installed packages

asGello (required when namesOnly = false)

Reply format
 

{
"wasSuccessful": boolean,
"names": [ string, .... ]
"packages": [
{
"Name": string,
"Code": string
},
"models": { ..... }
.....]

wasSuccessful (returned always), returns whether query was successful.

names (returned when namesOnly = true), returns a list of installed packages.

packages (returned when namesOnly = false and asGello = true), a full listing of installed packages in Gello Package format.

Name - package name
Code - package source code

models (returned when namesOnly = false and asGello = false), a full listing of installed packages in GELLO RTTI format (currently undocumented and subject to change).

Example - list installed package names only

Request

{
"namesOnly": true 
}

Reply

{
"wasSuccessful": true,
"names": [
"System",
"XMLAny",
"iso_21090_datatypes"
]
}