UserDefinedFieldDefinition

IMPORTANT  The SOAP API entered a limited enhancement phase in Q4 2020. Access deactivation for version 1.5 began in Q1 2022 and will enter its concluding phases in October 2022. Access to version 1.6 will be deactivated in Q4 2024. Visit our SOAP API lifecycle FAQ article to learn more.

This entity defines a user-defined field (UDF) in Autotask. User-defined fields are custom fields that each Autotask customer can add to certain Autotask entities. These fields hold data that is unique to the Autotask user's company and cannot be mapped to the standard Autotask field sets.

NOTE  Not all entities use UDFs. To determine if an entity can use UDFs, locate it in the and click to open the entity's topic. Alternately, use the API calls The getEntityInfo() SOAP API call and getUDFInfo().

Entity details

You can also retrieve this information with the Web Services API call The getEntityInfo() SOAP API call.

Entity Name: UserDefinedFieldDefinition
Can Create:
Can Update:
Can Query:
Can Delete:  
Can Have UDFs:  

Number of UDFs allowed for each entity

There is a limit to the number of active UDFs allowed per entity. If the addition of a new UDF, or the activation of an existing UDF, causes the total number of active UDFs to exceed the entity’s limit, the call will fail.

The limit varies between entities, as indicated below:

SOAP REST
Account Companies
AccountLocation CompanySiteConfigurations
Contact Contacts
Contract Contracts
InstalledProduct ConfigurationItems
Opportunity Opportunities
Product Products
Project Projects
SalesOrder SalesOrders
 

ServiceBundles

 

Services

Subscription Subscriptions
Task Tasks
Ticket Tickets

Each entity has a maximum number of active user-defined fields that you can define. For more information, refer to Managing user-defined fields.

IMPORTANT  You can only query by one user-defined field at a time.

To learn how to make PUT, PATCH, and POST requests to entities that support UDFs, refer to Creating resources via POST request in the REST API, Updating data via PUT request with the REST API and Updating data via PATCH request with the REST API.

Conditions and requirements

General

  • A user-defined field (UDF) cannot be deleted via the API.

  • API calls to multi-select and reference UDFs are not supported.

  • NOTE  Contract UDF "Contact-Old"
    Contract.ContactName stores the contact name as a string. Starting with 1.5.9, Autotask accepts a string for Contract.ContactName, but will also attempt to match the string to a currently active Contact. If an active contact is found, Contract.ContactName will be assigned that contact's ContactID.
    If no match is found, the Contract.ContactName field will be cleared and the ContactName string will be stored in a Contract UDF named Contact-Old (Autotask will create this UDF if needed).

Special field attributes

Field Conditions and Requirements
CRMToProjectUDF

CrmToProjectUdf requires that UserDefinedFieldDefinition.UdfType = Project; otherwise, an error is thrown.

CrmToProjectUdfId must reference a UserDefinedFieldDefinition.id. The referenced UserDefinedFieldDefinition must be an Opportunity type. Both UserDefinedFieldDefinition entities (the Project type and the Opportunity type) must be the same DataType.

DataType

After creation, DataType cannot be updated via the API.

  • For a UserDefinedFieldDefintion with DataType = List, DefaultValue cannot be set during creation because DefaultValue is reference to a UserDefinedFieldListItem. The UserDefinedFieldListItem cannot be created before the associated UserDefinedFieldDefinition. Refer to UserDefinedFieldListItem.
  • If DataType = string, DisplayFormat determines if the field is single line or multi-line. If DataType = string and DisplayFormat = 0, DisplayFormat will default to 1 (single line).

If DataType has a value other than string, DisplayFormat will =0 (undefined).

  • When creating UDFs of type Text (Email), the value provided must be a valid email address.
DefaultValue

DefaultValue must be a valid format for the UserDefinedFieldDefinition DataType:

  • String (single or multi-line) - Accepts an alphanumeric string.
  • Date - Accepts any valid date format.
  • Numeric - Accepts numbers. UserDefinedFieldDefinition.NumberOfDecimalPlaces defines how many decimal places are allowed.
  • List - List values are defined by the UserDefinedFieldListItem entity; default value must be a UserDefinedFieldListItem.ValueForDisplay where UserDefinedFieldListItem.UdfFieldID = UserDefinedFieldDefinition.id
IsEncrypted

IsEncrypted will = false unless the UdfType = Product or SiteConfiguation in which case it takes the value provided. IsEncrypted cannot = true if IsProtected = false.

NOTE  The API respects Data Protection Permissions. Users without the correct DPPs cannot view or update protected UDFs. Encrypted data can never be queried via the API.
IsFieldMapping UserDefinedFieldDefinition instances can be created via the API with IsFieldMapping = True (as of 02/2016). UserDefinedFieldDefinition.IsFieldMapping cannot be updated. When IsFieldMapping=True, updates are only allowed for IsActive and Sort Order.
IsPrivate

This field can only be set to true for protected Asset UDFs of type String. When set to true or false, Autotask will create an audit trail.

  • Changes made to these fields by the API will be logged as edits (but not views) of the field in its history.
  • Queries on these fields by the API will be logged as views of the field in its history.
IsProtected IsProtected will = false unless the UdfType = Product or Site Configuration in which case it takes the value provided.
IsVisibleToClientPortal IsVisibleToClientPortal will always = false unless the UDFType is Asset or Ticket in which case it will take the provided value.
MergeVariableName A value for the field MergeVariableName must be unique. It can contain only alpha characters (letters) and must begin with "var", for example, varCustomData.
NumberOfDecimalPlaces NumberOfDecimalPlaces must be > 0 and <= 4. If no value is provided it will default to 2.
SortOrder SortOrder must be > 0. If no value is provided or the value is <0, it will default to 1.
UDFType

After creation, UDFType cannot be updated via the API.

If UDFType=Ticket or Task, then IsRequired cannot = True. The required status for Ticket and Task UDFs is now set on the ticket category Details tab.

 

Field definitions

The following table describes the standard Autotask field objects for this entity.

  • To retrieve more detailed information specific to a particular Autotask implementation, use the Web Services API call The getFieldInfo() SOAP API call.
  • For information on entity UDFs, use getUDFInfo().
  • For String datatypes, the number in parentheses ( ) indicates the maximum number of characters allowed.
  • LT indicates Local Term.

For more information about fields marked as picklists, review our Understanding picklists article.

Field Name Label Datatype Read Only Is Required Reference Name Picklist
CreateDate Create Date datetime      
CRMToProjectUDF CRM to Project UDF id long        
DataType Data Type integer    
DefaultValue Default Value string (1024)        
Description Description string (128)        
DisplayFormat Display Format integer      
id ID long    
IsActive Active boolean        
IsEncrypted Encrypted boolean        
IsFieldMapping Field Mapping boolean      

IsPrivate

Is Private

boolean

 

 

 

 
IsProtected Protected boolean        
IsRequired Required boolean        
IsVisibleToClientPortal Visible To Client Portal boolean        
MergeVariableName Merge Variable Name string (100)        
Name Name string (45)      
NumberOfDecimalPlaces Number Of Decimal Places integer        
SortOrder Sort Order integer        
UDFType UDF Type integer