The Relational Add Field command allows you to create one or more fields in a User Defined Relational Table.
Arguments
The Relational Add Field command requires the following arguments: Command, Realm, Password, Table Name, Field Name, Field Type.
api_web?r=myrealm&p=mypass&c=rdbaddfield&table=mytable&fieldname=myfield&fieldtype=date&storageType=relational
The command is 'rdbaddfield', the realm is 'myrealm', the password is 'mypass', the table is 'mytable', and the field is 'myfield' of type 'date'. This command results in creation of a new field with status of 'pending' in the table 'mytable'.
If the Field Type is 'string', then the length of the column (character limit) must also be defined. Multiple fields can also be created using the command 'rdbaddmultiplefields' instead.
The field must be activated before data can be stored in it, which can be done using the rdbactivatefield command. Alternately, create fields that are active on create using rdbaddactivatefield.
The Relational Add Field command supports the following arguments:
|
Name |
Req? |
Description |
Argument |
|
Command |
Yes |
Defines the command to use. |
cmd=rdbaddfield, rdbaddmulitplefields c=rdbaddfield, rdbaddmultiplefields |
|
Realm |
Yes |
Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match. |
realm=[realm_name] r=[realm_name] |
|
Password |
Yes |
Authentication code for API access. This is required, and the command will fail if the realm and password do not match. |
pwd=[password] p=[password] |
|
Relational Table Name |
Yes |
Name of the relational data table in which to insert the new field. |
table=[table_name] |
|
Relational Field Name |
Yes |
Name of the new relational data field. |
fieldname=[field_name] |
|
Data Storage Type |
Yes |
Type of table in which to store data, currently only supports 'relational': **This argument is CASE sensitive. |
storageType=relational |
|
Relational Field Type |
Yes |
Type of data to store in the field:
|
fieldtype=[string, number,float,date] |
|
Column Length |
* |
Number of characters stored in the field. This is required if the Field is type 'string' and ignored for all other types. |
column_length=[character_limit] |
|
Description |
|
A short description of the data to store in the table. If not defined, Description will be set to the Relational Field Name. The Description supports all alphanumeric characters as well as space, underscore (_), but no other special characters. |
description=[field_description] |
|
Nullable? |
|
By default, a field does not require data to be stored. To make a field required, set nullable to 0 to indicate the field cannot be NULL. This is known as 'Required' in the UI. |
nullable=[0,1] DEFAULT==1 |
|
Unique? |
|
By default, the field contents are not required to be unique for each row. To make a field unique, set unique to 1. At least one field in a table must be unique. |
unique=[0,1] DEFAULT==0 |
|
In Browser? |
|
If the field stores data of type string, and the data will be displayed in a browser, set the In Browser option to 1. This will replace line breaks (/r/n) with HTML line breaks (<br />) |
in_browser=[0,1] DEFAULT==0 |
|
Import |
|
If the field should not allow data to be imported, set the Do Not Import option to 1. By default, the data field allows data to be imported. |
do_not_import=[0,1] DEFAULT==0 |
|
Export |
|
If the field should not allow data to be exported, set the Do Not Export option to 1. By default, the data field allows data to be exported. |
do_not_export=[0,1] DEFAULT==0 |
|
Edit Column |
|
By default, the columns can be edited. If the column should not allow editing, set the Do Not Edit Column option to 1. |
do_not_edit_column=[0,1] DEFAULT==0 |
|
Edit Data |
|
By default, the data can be edited. If the data should not allow editing, set the Do Not Edit Data option to 1. |
do_not_edit_data=[0,1] DEFAULT==0 |
|
Segment |
|
By default, the data can be used in segmentation rules. If the data should not allow segmenting, set the Do Not Segment option to 1. |
do_not_seg=[0,1] DEFAULT==0 |
|
Data |
* |
Data is an argument to define a header in order to create multiple fields using the rdbaddmultiplefields version of the command. Data is required for the Add Multiple version of the command. The following arguments can be used in the Data header:
|
data=[rdbaddfields arguments]
|
Example
Using all commands and arguments to add a single field (please note the command is wrapped for display purposes only):
api_web?r=myrealm&p=mypass&c=rdbaddfield&table=vehicles&storageType=relational&fieldname=brand&fieldtype=string&column_length=48&display_name=Vehicle%20Brand%20Name&description=Brand%20of%20vehicle%20ie%20Ford%20Hyundai%20Winnebego%20etc&nullable=1&unique=0&in_browser=1&do_not_import=0&do_not_export=0&do_not_edit_column=0&do_not_edit_data=0&do_not_seg=0
Successful results return:
SUCCESS: Field brand added to vehicles
Adding multiple fields with the same properties:
api_web?r=myrealm&p=mypass&c=rdbaddmultiplefields&table=vehicles&storageType=relational&data=fieldname,fieldtype,column_length,display_name,description,nullable,unique,in_browser,do_not_import,do_not_export,do_not_edit_column,do_not_edit_data,do_not_seg^brand,string,48,Vehicle%20Brand%20Name,Brand,1,0,1,0,0,0,0,0^make,string,48,Vehicle%20Make%20Type,Make,1,0,1,0,0,0,0,0^model,string,48,Vehicle%20Model%20Type,Model,1,0,1,0,0,0,0,0
Results
The Add Relational Field command outputs either a SUCCESS or FAILURE message.
SUCCESS
The Add Relational Field command success message returns the SUCCESS message and includes the name of the new table and the foreign key relationship. The result format is:
SUCCESS: Field [fieldname] added to [tablename]
FAILURE
The Add Relational Field command will fail for several reasons, such as if a field with the same name already exists or invalid data is defined. The result format is:
FAILURE: Problem adding field [fieldname] to Custom Relational table [tablename]