Custom Fields

Account administrators can define custom fields for supported record types in the OpenAir UI. For information about record that support custom fields, see Record Types and Forms Supporting Custom Fields. For more information about defining and using custom fields in the OpenAir UI, see Custom Fields.

Custom Field Definitions

You can use the XML API or SOAP API to:

Read custom field definitions. To read the definitions of all custom fields for a specific object type, for example, read CustField objects with equal to method and an argument CustField object including only the association property.
Update the Value list [valuelist] in the custom field definition (CustField object), depending on the custom field type.

Note:

Client applications cannot use the XML API or SOAP API to:

Add new custom fields.
Update custom field definitions except for Value list [valuelist].
Delete custom fields.

Custom Field Values

You can use the XML API or SOAP API to:

Read custom field values inline with standard object property values when reading objects. See Reading or Setting Custom Field Values Inline.
Set custom field values inline with standard object property values when adding or updating objects. See Reading or Setting Custom Field Values Inline.
Look up and update objects matching a custom field value. See Look Up and Update Objects Matching a Custom Field Value
Read only custom field values (CustomField objects) for the object referenced by internal ID using the custom equal to to method. See Read Methods.
Update only custom field values (CustomField objects) for the object referenced by internal ID using the custom equal to to method.

Reading or Setting Custom Field Values Inline

Note:

When reading or setting custom field values inline, custom fields are referenced by the custom field name with a suffix of two underscores followed by a lowercase c character. See Naming Conventions for Custom Fields.

Review the instructions in the following tables to read or set custom field values inline when reading, adding or updating an object using the XML API:

Command	Instructions
`Read`	Set the `enable_custom` attribute to `1`. List both standard object properties and custom fields to be returned in the `_Return` argument, if passed. If omitted or empty, the response includes all standard object properties and custom field values for each returned object. List both standard object property values and custom field values to match or not to match in the search query argument object when using the `equal to` or `not equal to` methods.
`Add` `CreateUser` `Modify`	Set the `enable_custom` attribute to `1`. Include all standard object properties and custom fields you want to set in the argument object.

Command

Instructions

Read

Set the enable_custom attribute to 1.

List both standard object properties and custom fields to be returned in the _Return argument, if passed. If omitted or empty, the response includes all standard object properties and custom field values for each returned object.

List both standard object property values and custom field values to match or not to match in the search query argument object when using the equal to or not equal to methods.

Add

CreateUser

Modify

Set the enable_custom attribute to 1.

Include all standard object properties and custom fields you want to set in the argument object.

Review the instructions in the following tables to read or set custom field values inline when reading, adding or updating objects using the SOAP API:

Command	Instructions
`read()`	Use your account-specific WSDL. List both standard object properties and custom fields to be returned in the `fields` property of each `ReadRequest` object passed. If omitted or empty, the response includes all standard object properties and custom field values for each returned object. List both standard object property values and custom field values to match or not to match in the search query argument object when using the `equal to` or `not equal to` methods.
`add()` `createUser()`	Use your account-specific WSDL. Include all standard object properties and custom fields you want to set in each argument object.
`modify()`	Use your account-specific WSDL. Set the `update_custom` attribute to `1`. Include all standard object properties and custom fields you want to set in each argument object.

Command

Instructions

read()

Use your account-specific WSDL.

List both standard object properties and custom fields to be returned in the fields property of each ReadRequest object passed. If omitted or empty, the response includes all standard object properties and custom field values for each returned object.

List both standard object property values and custom field values to match or not to match in the search query argument object when using the equal to or not equal to methods.

add()

createUser()

Use your account-specific WSDL.

Include all standard object properties and custom fields you want to set in each argument object.

modify()

Use your account-specific WSDL.

Set the update_custom attribute to 1.

Include all standard object properties and custom fields you want to set in each argument object.

Note:

Setting custom fields inline is not possible when using the upsert() call.

Look Up and Update Objects Matching a Custom Field Value

Review the instructions in the following tables to look up and modify objects matching a custom field value using the SOAP API:

Command	Instructions
`modify()`	Set the `lookup_custom` attribute to the custom field `name` with a suffix of two underscores immediately followed by a lowercase `c` character. See Naming Conventions for Custom Fields. Include the custom field you want to match instead of the internal ID.

Command

Instructions

modify()

Set the lookup_custom attribute to the custom field name with a suffix of two underscores immediately followed by a lowercase c character. See Naming Conventions for Custom Fields.

Include the custom field you want to match instead of the internal ID.

Note:

The lookup_custom attribute cannot be used with an upsert() call.

Naming Conventions for Custom Fields

Account administrators define the name of most custom fields. Each custom field must have a unique name. Some OpenAir features use custom fields that are either added automatically when enabling the feature or that needs to be created by an account administrator before the feature can be used.

When reading or updating CustField or CustomField objects, the custom field name is the same as the Name on the custom field properties form in the OpenAir UI.

When reading or setting custom fields values inline with standard object properties, the API references custom fields by the name with a suffix of two underscores immediately followed by a lowercase c character. For example, a custom field with the name my_custom_field is listed as my_custom_field__c in the account-specific WSDL.

Note:

XML naming rules apply to custom field names.

The name must start with a letter or an underscore.
The name cannot start with the letters xml in any letter case combination.

The custom field names such as 1MyCustomField and xmlMyCustomField, for example, cannot be read or set inline with standard object properties and are not included in the account-specific WSDL.

Uniqueness for Custom Fields

Custom fields for an object type can be set up to accept unique values across all the objects of this type in the OpenAir UI, depending on the type of custom field. Uniqueness is useful for a custom field holding a foreign key such as an object ID in a system outside of OpenAir, for example. To find out whether the custom field values must be unique, read the custom field definition (CustField object type ) and inspect the value of the unique property. If the unique property is set to 1, custom field values must be unique. If the unique property is set to 0, the custom field can have the same value in different objects.

If you try to set a duplicate value when adding or updating an object and the custom field values must be unique, the object is saved and all standard object properties and custom fields are saved except those failing the uniqueness validation. The API response includes error status 1106 and an error code 1104 for each custom field that failed the uniqueness validation.

Default Values in Custom Fields

Custom fields can be set up to have a default value, depending on the type of custom field. When adding objects using the API, a custom field will be set to its default value unless a valid value is passed for the custom field.

Value Lists for Custom Fields

Custom fields can be set up to have a list of possible values, depending on the type of custom field. The custom field must be set to one of the listed value except in the case of Dropdown and Text custom fields. If you try to set the custom field to a value that is not in the value list when adding or updating an object, the object is saved and all standard object properties and custom fields are saved except those failing the accepted values validation. The API response includes error status 1106 and an error code 1105 for each custom field for which the value passed is not in the value list for this custom field.

Note:

The Value list [valuelist] is the only custom field definition (CustField) property that can be modified using the XML API or SOAP API.

Custom Field Value Format

Some custom field types only accept values in a specific format.

For example, allocation grid custom field values are set as a string with each value-number pairs on a separate line.

Sample Code (SOAP API) – C#

myProject.my_allocation_grid__c = "Marc Collins,0\nBill Carter,0\nMarie Porter,50\nEd Ellis,50";

Sample Code (XML API)

            <my_allocation_grid__c>"Marc Collins",0
"Bill Carter",0
"Marie Porter",50
"Ed Ellis",50</my_allocation_grid__c>

Date Custom Field Value Format

The XML API handles custom date field values as strings using the format YYYY-MM-DD.

When reading object, the API returns custom date field values in the format YYYY-MM-DD. If using a custom date field in the search query object with the equal to or not equal to methods, you must pass the custom date field value as a string using the format YYYY-MM-DD. Using the Date element for custom date field values results in an error.

When adding or modifying objects, you must pass custom date field values as a string using the format YYYY-MM-DD. If you use the Date element for custom date field values, the custom date fields are set to 0000-00-00.