REST Service Specifications¶
The REST service provides a API with the ability to add, edit, get and delete information stored in a NEXUS IC database. These REST service ensures all request are made through the NEXUS Storage engine which allows security and cohesion to be maintained and respected within the NEXUS database data.
Usage¶
ICWeb.dll/web/?requestType=REQUESTTYPE[&hash=HASHTOKEN][&extra_options=EXTRA_OPTIONS]
Required Parameters¶
- requestType - The type of request
- hash - A valid pre-authenticated security token is required for every request except RequestType=getSecurity requests.
- extra_options - Are optional additional settings which can be used to change, filter or may be required for certain request types. (see Specific Parameters for RequestTypes below)
requestType
This is a string, it specifies the REST request type. Valid options for this are as follows:
- getSecurity: this is used to authenticate a username and password and get a security token for future requests.
- setSecurity : this is used to change a already authenticated users password.
- getData : this is essentially the same as a Select query on a NEXUS IC metatable
- setData : this is essentially the same as an update query on NEXUS IC metatable.
- insertData : this is essentially the same as an add query on NEXUS IC metatable.
- deleteData : this is essentially the same as an delete query on the NEXUS IC metatable.
- getTrafficLight : this is used to get traffic light specific requests
- getChart : this get either the chartlist if no extra params are sent with this request or the chart data itself
- emailData : used to email Library items to the current user. [Depreciated - use Get Repository Item]
- getObject : used to just return a metatable’s metaData, rows will always be empty.
- getVersion : returns the version and schema for the NEXUS database. This requries no parameters and doesn’t require authentication
hash
In is a hash token provided to the user and used in order to prove credentials are valid for subsequent requests. The hash is generated on the server and will expire after 60 minutes of inactivity. To get a hash token you must perform a requestType=getSecurity
request. When performed if the request is successful the result will contain valid hash token which can be used to prove credentials on all subsequent requests.
Specific Parameters for RequestType¶
For each type of request, there are a set of valid parameters to allow NEXUS to process the request correctly.
setData
- metatable : the Table_Def “Name” field string or the TD_ID value of the Table from Table_Def
- filter : is a json object string used to return only a filtered subset of data from a metatable (further details below). This must ensure that only one row is returned
- rows: JSON array containing the data to updated the row with. The format of the value of each row is determined by the metaData part of any request to this metatable
getData
- metatable : the Table_Def “Name” field string or the TD_ID value of the Table from Table_Def
- filter (optional) : is a json object string used to return only a filtered subset of data from a metatable (further details below)
- sortJson (optional): is json object with property attribute which is the field to sort on and direction attribute which is ASC or DESC of the data set returned
- start (optional): the row in which to start returning data from
- limit (optional): the number of rows after the starting row which to return data to
- resultFormat (optional): the type of object the requester wants returned (defaults to JSON)
- maxSize (optional): Used in conjunction with resultFormat=thumbnail argument to specific the max size (either height or width depending on source aspect ration) of the thumbnail image returned
- addAigData (optional): special request used to get multiple AIG associated with Components, specifically used for the Child screen in IC Web -> Asset -> Children panels
insertData
- metatable : the Table_Def “Name” field string or the TD_ID value of the Table from Table_Def
- rows: JSON array containing the data to be inserted, supports multiple rows. The format of the value of each row is determined by the metaData part of any request to this metatable
[
{"TD_ID": 336, "Workpack_ID":3, "Workpack_Name": "2015 ROV"},
{"TD_ID": 335, "Workpack_ID":2, "Workpack_Name": "ESDT"}
]
deleteData
- metatable : the Table_Def “Name” field string or the TD_ID value of the Table from Table_Def
- filter : is a json object string used to return only a filtered subset of data from a metatable (further details below)
getTrafficLight
- trafficLightKey : Set the trafficlight id to either pull Component data or legend data
- componentIds (optional): If set the request will return traffic light data if blank it will return the legend data
getSecurity
- username : Specifies the username for authentication
- password : Specifies the password for authentication
setSecurity
- password : Specifies the password for authentication
- newPassword : Used to set a new password value for an already authenticated user
getChart
- chartId (optional): The chart id of the chart you want from the list of charts. chartid and rowid are required for chart data.
- rowId (optional): he currently focused row’s primary key. chartid and rowid are required for chart data
emailData (Depreciated)
- metatable : the Table_Def “Name” field string or the TD_ID value of the Table from Table_Def
- filter : is a json object string used to return only a filtered subset of data from a metatable (further details below). This filter must ensure only one row is returned
getObject
This is identical to “getData” request but returns no rows. Its primary use is to retrive the metaData for a NEXUS metatable.
getVersion
No parameters
Filter¶
Filters are a JSON array, each array item consists of a json object with either 1 or 2 elements. There must be an element called “method” and depending on the method value it may be necessary to have a second element called “params”. The filter is made up one or more these objects, these represent a pseudo SQL where statement and allow you to build complex queries to return data.
Examples
[
{
"method": "where",
"params": {
"field": "Workpack_ID",
"compareType": "ctGreaterEqual",
"value": 353
}
}, {
"method": "and"
}, {
"method": "isNull",
"params": {
"field": "Name"
}
}
]
Filter Method Types
The method element determines the type of this filter item
- where This is a normal condition check and requires the params FieldName, CompareType and FieldValue to be specified
- and combines conditions requiring left and right to be true.
- or combines conditions requiring either the left or the right to be true.
- openNesting Represents a leading bracket ie “(” and does not require a params attribute
- closeNesting Represents a trailing bracket ie ”)” and does not require a params attribute but can only be present if there is a preceding opennesting.
- not The inverse of the next defined valid filter object (where, isnull, isnotnull) in the array and does not require a params attribute
- isNull True if the field’s value is null, requires param FieldName to be set.
- isNotNull True if the field’s value is not null, requires param FieldName value to be set
- sort Sorts the result set by the fields specified - Requires field and value parameters; value is either “ASC” or “DESC”. Sort can also be done as a seperate request arguments - see “Sort” below
- distinct Ensures the resultset contains unique rows. No parameters required
Methods available for View_Node
View_Node is used for the asset tree and as such has 2 special commands which can be used on it:
- childrenOf Returns all child assets of selected item in viewnode, params must have the FieldName = “VN_ID” and FieldValue needs to be set to the object you want to find the children of
- parentOf Returns all parents assets of selected item in viewnode, params must have the FieldName = “VN_ID” and FieldValue needs to be set to the object you want to find the parents of
Params
Params is a JSON object containing 1-3 attributes. Allowed attrubutes are: “field”, “comparetype”, “value”:
{
"field" : "Name",
"compareType" : "ctEqual"
"value" : "Test Value"
}
Params is only sometimes required depending the method called - see Methods types above
field
Specifies the NEXUS metatable field on which you which to perform the filter on. It must be an alphanumeric string in quotes and match a field name in the NEXUS schema.
value
This is a single value or array of values, this can be of type alphanumeric, number, float, boolean. The type of value specified must match the underlying type of the field.
yyyy/mm/dd hh:mm:ss
.compareType
CompareType actually relates directly to the NEXUS Metatable type TCompareType. It can be any of the following:
- ctEqual For when FieldName = FieldValue
- ctLess For when FieldName is less than FieldValue
- ctGreater For when FieldName is greater than FieldValue
- ctLessEqual For when FieldName is less than or equal too FieldValue
- ctGreaterEqual For when FieldName is greater than or equal too FieldValue
- ctLike For when FieldName is like FieldValue - NB FieldValue can contain SQL wildcard character ‘%’
- ctIn For when FieldName is contained with FieldValue - NB in this case FieldValue is a JSON array of integers
sort¶
Usage:
sort=[{"property":"FIELDNAME","direction":"ASC|DESC"}]
FIELDNAME : = a field in the NEXUS metatable that you want to sort on. ASC|DESC : the sort direction either ‘ASC’ or ‘DESC’ for ascending and descending respectively.
Ie ICWeb.dll/web/?requesttype=getdata&metaData=Header&sort=[{“property”:”Northing”,”direction”:”ASC”}] returns all Header business object data and sorts it ascending on the Northing field.
start and limit¶
If you have a large data set returned it can be beneficial to get just a subset of rows from the data. You can do this by appending the URL variables start and/or limit to any of the requests listed above:
start=x
limit=y
Where x and y are numbers X = the start row (with 0 being the first row) Y = the maximum number of rows to display starting from X (0 = all rows)
Ie
ICWeb.dll/web/?requesttype=getdata&metaData=Header&limit=200
– will return Header data from the first row entry to the 200 entryICWeb.dll/web/?requesttype=getdata&metaData=Anomaly?start=20&limit=50
– will return rows 21 to the to 71 of the Anomaly tableIf you request a start value above the number or data rows available you will get an empty array If you request a limit higher than is the remaining rows from the start row you will get all the remaining data, starting from the start value. By default start and limit are 0 so if not defined this returns all data rows.
resultFormat and maxSize¶
Format type can be set if you wish for something other than JSON to be returned. Allowed types are as follows:
- json - This will return a JSON text object and is the default if the format argument is left off.
- icon - This will specifically the icon image used in Comp_Icon or Boolean_Value table
- image - This will return an single image or binary file
- binary - Same as image
- thumbnail - This is the same as image but returns a max 200 pixel thumbnail of the image file. You can include “MaxSize” parameter with this request which will change the max size to something other than 200 pixels.
If request type image or binary you can supply an option parameter “imagefield” - this conatins the fieldname in the NEXUS metatable that contains the image data. If imagefield is left off the request then the NEXUS metatable must contain a field called “UNC” which containes the image or binary data (ie the Repository metatable).
trafficLightKey and componentIds¶
trafficLightKey is the unique Traffic Light ID used to indicate which traffic light system the requester wants data about. TrafficLightKey is required for any requestType=getTrafficLight. If the ComponentIDs parameter is also set in the request then the request returns all Traffic Light data values for those componentIds will be returned. If omitted then the Traffic Light Legend data is returned instead. componentIds is a jsonArray string
Authentication¶
Almost all requests can only be preformed once a user is authenticated. The user is authenticated by performing a Request “requestType=getSecurity”. In order for that authentication request to be successful you must pass in a “username” and “password” parameters. If the values of these 2 parameters matches values in the database a unique hash token will be returned back to the requester. From that point on, all requests requiring authentication should then use the returned hash token as the value of the “hash” parameter in subsequent requests. You can also change your password via the setSecurity requestType. To do this you must first authenticate. Once authenticated then are required to send a request with requestType=setSecurity which must include a authenticated hash, your existing password as a “password” parameter and the new password in a “newPassword” parameter. If successful you will get a success response back. See getSecurity above.
Tip
If Single Sign On (SSO) is enabled on your account your username must be in the format username@domain
. IE - joe.blogs@mycompany.com
Returned JSON results¶
The results return from a query have a number of attributes. “Success” is a boolean and is always returned it will be true if the request was in the correct format. It will be false if the syntax or attributes passed have caused an error; if it is false there will also be a “msg” attribute returned with the error message. ie
{
success: false,
msg: "Unknown meta table "Ta". Could not find table name in meta tables."
}
Successful results are returned with the success attribute, a metaData attribute, RowCount attribute and Rows attribute. Please note that RowCount will return the total number or results available not the total number returned in the json. This is because you can use the “limit” to return less than all results (see Starting Row and Limit above).
rows¶
rows is an array of all the values returned from the data base, if no results are found it will be an empty array. Each element in the Rows array is a JSON object containing the a “value” attribute and possibly a “display” attribute. Value is the raw data from the database and will always be present display will be present if it is different from the value. Display is used for thing that are lookup into other sections of Nexus. For example if your results return Component_ID this is the Unique ID of a single component in the database but the Name of that component is more useful to the users so as a result the data will be retuned like this:
"rows" :[{
"Component_ID": {
"value": 364,
"display": "Tanks"
},
"CT_ID": {
"value": 21,
"display": "Pressure Tank"
}
}, {
"Component_ID": {
"value": 369,
"display": "Wharf 22"
},
"CT_ID": {
"value": 52,
"display": "Temporary Wharf"
}
}]
This allows you do display user friendly names to users but allows gives you the true value if this is a primary or foreign key to perform future queries on a selected item. This is useful as you need to use “value” value if you wish to use this field in a filter. IE - using the example above if you wanted all result where the CT_ID = “Pressure Tank” you would need to use 21 as the “value” in your filter request for CT_ID not the “Pressure Tank”.
metaData¶
The Metatable attribute contains information describing the data returned. It contains the following properties:
- “defaultField” : this is the name of the field who’s value you can use to display to represent the entire row’s data as a single entry.
- “totalProperty” returns the value of the Counter of the number of rows returned (this is mostly for ExtJS and is likely to dissappear in future revisions)
- “root” show the attribute which contains the data values - again this was for ExtJS and is likely to disappear in future revisions
- “fields” contains an array of every field that will be retuned and includes information about those fields. See below.
fields¶
Fields have the following attributes:
- FieldName: This is the fieldname
- FieldTitle: This is the User friendly fieldname or the displayable name for things like fields or column title
- Comments: User defined comments about a field - can be used in tool tips
- FieldType: This is integer representing what data type the field is stored in; see below for a list of types
- FieldSize: When displayed in Nexus this is the size of the field used in characters
- EditorType: This is integer representing what data type the field is shown as when it is being changed. Not used yet.
- IsForeignKey: Boolean if this links to another Table in Nexus
- IsPrimaryKey: Boolean if this is the tables primary key field
- Format: the data/time format if applicable
- DefaultFormat: the data/time format if applicable
- DisplayFieldType: This is an integer representing what data type you should display this data as; See below for a list of types
- Category: Data is sometime lumped into groups for display if set this will contain the name of the group this field belongs too
- CategoryColumns: How many columns this category has.
- CategoryAlignTop: not implemented yet
- FormOrder: Integer describing the order of the field in the form,
- FormColumns: The number of fields per line to display if displaying as a form,
- VisibleForm: Boolean which indicates if this fields should be shown or hidden from the user on a form,
- ShowCaption: If a captions should be shown,
- GridOrder: Integer describing the order of the field in the grid
- BlankText: The default value to display if it is a blank field
- VisibleGrid: Boolean which indicates if this fields should be shown or hidden from the user on a grid,
- AllowImport: not implemented yet
- AutoValue: If this is auto incrementing field (mostly used for primary keys)
- HasDefaultValue: If this field has a default value.
- PreventEditing: not implemented yet.
- UpperValue: If an numeric value this contains the highest value this number can be
- LowerValue: If an numberic value this contains the lowest value this number can be
- Link_ID: For Passthrough fields, contains the Table_Def key for the table this links too.
- FD_ID: The Unique Field ID of this field in the nexus system
- LL_ID: The Lookup List ID if this field is a NEXUS Lookup List field
- Required : If the field is a required field
- BooleanType : If the field is a boolean fieldtype
- GridCaption : The caption to display for the column when in a grid.
FieldType and DisplayFieldType values:
EditorType and DisplayEditorType values:
Request Examples¶
- Return all data from the Header metatable:
- ICWeb.dll/web/?metatable=Header&requestType=getData&hash={9112936E-F2A1-4B64-BC71-90C0725A8004}
- Return all data from the Table which is defined in Table_Def with the TD_ID = 436:
- ICWeb.dll/web/?metatable=436&requestType=getData&hash={9112936E-F2A1-4B64-BC71-90C0725A8004}&filter=[{“method”:”where”,”params”:{“field”:”TD_ID”,”compareType”:”ctEqual”,”value”:436}}]
- Return all data from header metatable where Workpack_ID is greater than or equal to 353 and Event_No is equal to 2:
- ICWeb.dll/web/?metatable=Header&requestType=getData&hash={9112936E-F2A1-4B64-BC71-90C0725A8004}&filter=[{“method”:”where”,”params”:{“field”:”Workpack_ID”,”comparetype”:”ctGreaterEqual”,”value”:353}},{“method”:”and”},{“method”:”where”,”params”:{“field”:”Event_No”,”comparetype”:”ctEqual”,”value”:2}}]
Expanded out the filter JSON Looks like this
[
{
"method": "where",
"params": {
"field": "Workpack_ID",
"comparetype": "ctGreaterEqual",
"value": 353
}
},
{
"method": "and"
},
{
"method": "where",
"params": {
"field": "Event_No",
"comparetype": "ctEqual",
"value": 2
}
}
]
- Return all data from the Anomaly metatable where Component_ID is 353 and the KP is greater than 2, or Name has the string ‘pipeline’ anywhere in it:
- ICWeb.dll/web/?metatable=Anomaly&requestType=getData&hash={9112936E-F2A1-4B64-BC71-90C0725A8004}&filter=[{“method”:”opennested”},{“method”:”where”,”params”:{“field”:”Component_ID”,”comparetype”:”ctEqual”,”value”:353}},{“method”:”and”},{“method”:”where”,”params”:{“field”:”KP”,”comparetype”:”ctGreater”,”value”:2}},{“method”:”closenested”},{“method”:”or”},{“method”:”where”,”params”:{“field”:”Name”,”comparetype”:”ctLike”,”value”:”%25pipeline%25”}}]
Expanded the JSON Looks like this:
[
{
"method": "opennested"
},
{
"method": "where",
"params": {
"field": "Component_ID",
"comparetype": "ctEqual",
"value": 353
}
},
{
"method": "and"
},
{
"method": "where",
"params": {
"field": "KP",
"comparetype": "ctGreater",
"value": 2
}
},
{
"method": "closenested"
},
{
"method": "or"
},
{
"method": "where",
"params": {
"field": "Name",
"comparetype": "ctLike",
"value": "%pipeline%"
}
}
]
- Return data from data from rows 53 to 57 of the Anomaly businessobjects where Component_ID is 353 and the KP is greater than 2, or Name is not null and it will sort the data in descending order of Code_ID:
- ICWeb.dll/web/?metatable=Anomaly&requestType=getData&hash={9112936E-F2A1-4B64-BC71-90C0725A8004}&start=52&filter=[{“method”:”opennested”},{“method”:”where”,”params”:{“field”:”Component_ID”,”comparetype”:”ctEqual”,”value”:353}},{“method”:”and”},{“method”:”where”,”params”:{“field”:”KP”,”comparetype”:”ctGreater”,”value”:2}},{“method”:”closenested”},{“method”:”or”},{“method”:”isnull”,”params”:{“field”:”Name”}}]&limit=5&sort=[{“property”:”Code_id”,”direction”:”DESC”}]
The filter expanded out :
[
{
"method": "opennested"
},
{
"method": "where",
"params": {
"field": "Component_ID",
"comparetype": "ctEqual",
"value": 353
}
},
{
"method": "and"
},
{
"method": "where",
"params": {
"field": "KP",
"comparetype": "ctGreater",
"value": 2
}
},
{
"method": "closenested"
},
{
"method": "or"
},
{
"method": "isnull",
"params": {
"field": "Name"
}
}
]
Reports¶
Usage¶
ICWeb.dll/web/generateReport?key=KEY&format=FORMAT&recipient=EMAIL&hash=HASHTOKEN
ICWeb.dll/web/getReportParams?key=KEY&hash=HASHTOKEN
Desciption¶
The generateReport and getReportParams requests can be uses to have NEXUS email generate and email a report to someone.
URL Parameters¶
- key - This is the report template id of the NEXUS report
- format - This is the file format the report will be in
- recipient - This is the single email address of the recipient to recieve the report. (optional - if omitted will used the email address of the account making the request)
- hash - The authenticated hash token the server has provided you with from a getSecurity request
Format Specifics¶
format - Can be:
rtf - For rich text formatted filehtml - For a zip containing hyper text markup language filesxlsx - For an Excel formatted file
Request Body Parameters¶
If a call to getReportParams returns any rows then the report requires parameters to be inputted from the user. These must be passed via the generateReport request in the body of the request in JSON format. The format of this json should be a Json object containing an attribute for each report parameter. The attribute should have the same name as the “parameterName” returned from the getReportParams and the value of the element be either a single value representing the value or for multiselect report parameters it may be an array of integers.
Request Responses¶
getReportParams
getReportParams will return a Json similar to the ones outlined above (See Returned JSON results). The fields returned in the metaData contain the following attributes:
The “rows” returned in the reponse will contain a single row with a element for each “parameterName” the value of each element will be last values a user used for this report.
generateReport
generateReport will simply return {"success":true}
if success.
If not successful it will return an error response with an appropriate message.
Video List¶
Usage¶
ICWeb.dll/web/getVideoList?eventId=HEADER_ID&hash=HASHTOKEN
Description¶
This call returns JSON containing a list of video files associated with an event.
URL Parameters¶
- eventId - This is the Header ID of an event
- hash - The authenticated hash token the server has provided you with from a getSecurity request. See Authentication
Results¶
The resulting request returns the rows from the Video_File metatable in the same format as the requestType=getData format above.
Export Grid¶
Usage¶
ICWeb.dll/web/exportGrid?metatable=METATABLE&format=csv|txt&emailResult=true|false&fields=FIELDS&filter=FILTER&hash=HASHTOKEN
Desciption¶
This call will return either a CSV or txt file contining the data of a metatable if a particlar format as defined by the FIELDS paramaeter.
Required URL Parameters¶
- metatable - This is either a string or interger which is the NEXUS metatable name or Table_ID of a NEXUS metatable
- format - This has to be either csv or txt depending on the format you want of the returned file.
- emailResult - A string begin either true or false representing a Boolean value. This indicated if you want the file returned or your want the server to just email the file and return if the email request was successful.
- fields - This is string representing an array of ordered fields that you want included in the data. ie
&fields=["Name","CV_ID","Status"]
- hash - The authenticated hash token the server has provided you with from a getSecurity request. See Authentication
Optional URL Parameters¶
- filter - A filter for the data included in the file. Format and use is identical to when you getData. See Filter above
Results¶
The resulting request can return 2 different response depending on if emailResult = “true” or “false”.
- If emailResult = true and the request is successful the response returns a response with a status 200 with the text {success: true}.
- If emailResult = false and the request is successful the file will be return (either a CSV or TXT file depending on what is specified in the format parameter)
Note: the hash parameter will determin the user making the request and if you request the file be emailed then the requesting user must have an email address specificed in their NEXUS account information or else you will get an error.
Get Repository Item¶
Usage¶
ICWeb.dll/web/getRepositoryItem?emailResult=true|false&filter=FILTER&hash=HASHTOKEN
Desciption¶
This call return a repository item to the requester. It will be will return in the response or via an email depending on the setting of the emailResult parameter.
Required URL Parameters¶
- emailResult - A string begin either true or false representing a Boolean value. This indicated if you want the file returned or your want the server to just email the file and return if the email request was successful.
- hash - The authenticated hash token the server has provided you with from a getSecurity request. See Authentication
- filter - A filter to identify a single row from the Repository metatable. The filter must ensure that one and only one result is returned or else you will get an error. Format and use is identical to when you getData. See Filter above
Results¶
The resulting request can return 2 different response depending on if emailResult = “true” or “false”.
- If emailResult = true and the request is successful the resposne returns a response with a status 200 with the text {success: true}.
- If emailResult = false and the request is successful the repository file will be return as the response.
Note: the hash parameter will determin the user making the request and if you request the file be emailed then the requesting user must have an email address specificed in their NEXUS account information or else you will get an error.