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 |
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.
If dataType has a value other than string, displayFormat will =0 (undefined).
|
defaultValue |
defaultValue must be a valid format for the UserDefinedFieldDefinition dataType:
|
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.
|
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:
- The entityInformation REST API call
- Making basic query calls to the REST API
- Advanced query features of the REST API
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 |