Conditional data access

There may be times when you wish to apply one or more conditions to the data that will be displayed by the table. This might be as simple as showing only a range of data, or a more complex set up such as multi-tenant applications. This is done by providing the conditions to the access request made to get the access token. Any embedded table using that access token will then have those conditions applied to it - thus allowing this to be done securely and transparently, with no knowledge of the process to the end client.

Unlike the search options provided by the table on the page, applying a condition to the access request will cause the data to be filtered at the server, subsequently displaying only the records that match, with no visual indication to the client that other records might or might not exist.

Access conditions

An access condition is applied to the access request as the conditions parameter, which can be an object or array of objects. The condition objects have two required parameters (id or name, and value), with others optional:

Name	Required	Type	Description
id	One of id or name must be given	String	The id of the data point to perform the condition on. This can be found from your data set's Data page and click on the item in question. The id will be shown in the item inspector on the right. It will start dp- for a regular data point. Conditions on computed values (c-) and links (l-) are not currently supported.
name	One of id or name must be given	String	The data point's name that the condition should be performed upon. This can be given as an alternative to the id option as it is easier to remember. However, while the id is static, the name can be changed in the application.
op	Optional (default =)	String	Conditional operator - it may be one of =, !=, <, <=, >=, >
set	Optional (default true)	Boolean	When a new record is created, the API can set the data point to a specific value (defined by setValue or value if the former is not specified).
setValue	Optional (default undefined)	String or Number	Value to set when a new record is created.
value	Required	String or Number	The value that will be used for the conditional matching. For formatting of the value, please see below.

Please note that the following formatting must be used for the value when matching against the various data types:

• date - ISO 8601 (date only)
• datetime - ISO 8601
• number - Unformatted number
• text - Plain text
• time - ISO 8601 (time only).

Please see the API documentation for the server-side language you are using for full interface details:

• HTTP REST / cURL
• Java
• .NET
• NodeJS
• PHP

Setting values

When reading data, the value comparison is an obvious requirement. However, when writing values (e.g. creating a new record) you will likely want the conditional value to be enforced, so that the client will still be able to access their data when reloading the page! By default when creating a new row, the value of the data point used for the condition(s) will automatically be set to the value. You can disable this behavior using the set parameter, or write a different value with the setValue parameter. If using a condition other than =, you must specify setValue (since otherwise it won't know what to write).

Multi-tenant example

Consider the case where you have a data set that you wish to give multiple people read / write access, but you only want them to have access to their specific data. This can readily be done in CloudTables by creating a data point that will contain the condition value, in this case we will assume you are using a user name from your application's login system (call your data point Username), and conditional loading of data.

When requesting an access token add a conditions parameter which can be given either as valid JSON:

{
	"name": "Username",
	"value": systemUserName
}

Or can be given as HTTP parameters:

conditions[name]=Username
conditions[value]=systemUserName

where systemUserName is however your login system identifies your clients.

Multiple conditions

As well as being able to specify a single condition, it is possible to provide an array of conditions which will be used together (i.e. combined with AND logic) to restrict access to the data.

As JSON:

[
	{
		"name": "Username",
		"value": systemUserName
	},
	{
		"name": "Location",
		"value": locationName
	}
]

and as HTTP parameters:

conditions[0][name]=Username
conditions[0][value]=systemUserName
conditions[1][name]=Location
conditions[1][value]=locationName