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.

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.

Naming Conventions for Custom Fields

Account administrators define the name of most custom fields. Each custom field must have a unique name. Some SuiteProjects Pro 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 SuiteProjects Pro 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.

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 SuiteProjects Pro 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 SuiteProjects Pro, 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.

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>