UserDefinedFieldDefinitions

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  You can refer to the Online Help to find root and child access URLs of the entity you wish to query. Refer to Finding resource and child access URLs of REST API entities for more information.

Entity details

Entity Name: UserDefinedFieldDefinitions

Entity Path:

/atservicesrest/v1.0/UserDefinedFieldDefinitions
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.

NOTE  Not all entities use UDFs. To determine an entity's scope of UDF support, locate it in the and click to open the entity's topic. Alternately, use the GET call against the entity path listed for the entity in its topic.

Entity Name: UDF limit
Company: 200
CompanySiteConfiguration (Site Configuration information): 500
Contact: 100
Contract: 50
ConfigurationItem: 500
Opportunity: 200
Service:
Service Bundle:
Project: 200
Product: 200
SalesOrder: 100
Subscription: 100
Task: 100
Ticket: 300
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. 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
crmToProjectUdfId

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 UserDefinedFieldListItems.
  • 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 set on the ticket category Details tab.

 

Field definitions

The following table describes the standard Autotask fields for this entity. Refer to the following articles for more information about working with these fields:

To learn how to query picklist endpoints, refer to Understanding picklists.

Notes

  • For string datatypes, the number in parentheses ( ) indicates the maximum number of characters allowed.
  • LT indicates Local Term.
  • If this entity has child collections, they will appear in a Child collection access URLs or an Entity URLs and relationships drop-down in the Entity details section of this article.
  • You can call the /query/count/ endpoint of a resource to determine how many records a collection holds.
Field Name Datatype Read-Only Is Required Reference Name Picklist
createDate datetime      
crmToProjectUdfId long        
dataType integer    
defaultValue string (1024)        
description string (128)        
displayFormat integer      
id long    
isActive boolean        
isEncrypted boolean        
isFieldMapping boolean      

isPrivate

boolean

 

 

 

 
isProtected boolean        
isRequired boolean        
isVisibleToClientPortal boolean        
mergeVariableName string (100)        
name string (45)      
numberOfDecimalPlaces integer        
sortOrder integer        
udfType integer    

Additional resources