How to update a user-defined field using the web services API
• 7 minutes to read
This guide describes how to update a user-defined field using the web services API.
Steps
The following REST code snippets use plain http requests to demonstrate how to perform the operation. The WebApi code snippet demonstrates how to perform the same operation using our nuget package SuperOffice.WebApi.
Get the user-defined field by progId or label text (FieldLabel).
GET https://{{env}}.superoffice.com/{{tenant}}/api/v1/Contact/UdefLayout/SuperOffice:1
Authorization: Bearer {{token}}
Accept: application/json; charset=utf-8
Response:
{
"UDefFieldId": 140,
"ColumnId": 8972,
"FieldDefault": "",
"FieldHeight": 17,
"FieldLabel": "My New Number",
"FieldLeft": 102,
"FieldTop": 187,
"FieldType": "Number",
"FieldWidth": 100,
"FormatMask": "",
"HideLabel": false,
"IsIndexed": false,
"LabelHeight": 17,
"LabelLeft": 0,
"LabelTop": 187,
"LabelWidth": 100,
"LastVersionId": 128,
"ListTableId": 0,
"IsMandatory": false,
"Type": "Contact",
"Page1LineNo": 0,
"ProgId": "SuperOffice:12",
"IsReadOnly": false,
"ShortLabel": "NewNumber",
"TabOrder": 12,
"TextLength": 0,
"Tooltip": "",
"UdefIdentity": 12,
"UDListDefinitionId": 0,
"Justification": "Left",
"Version": 14,
"TemplateVariableName": "cl12",
"HasBeenPublished": true,
"MdoListName": null,
"TableRight": null,
"FieldProperties": {
"IsIndexed": {
"FieldRight": {
"Mask": "Update",
"Reason": ""
},
"FieldType": "System.Boolean",
"FieldLength": 0
},
"IsMandatory": {
"FieldRight": {
"Mask": "Update",
"Reason": ""
},
"FieldType": "System.Boolean",
"FieldLength": 0
}
}
}
Make the desired property changes and save the user-defined field.
PUT https://{{env}}.superoffice.com/{{tenant}}/api/v1/Contact/UdefLayout HTTP/1.1
Authorization: Bearer {{token}}
Accept: application/json; charset=utf-8
Content-Type: application/json; charset=utf-8
{
"UDefFieldId": 140,
"ColumnId": 8972,
"FieldDefault": "",
"FieldHeight": 17,
"FieldLabel": "My Newer Number",
"FieldLeft": 102,
"FieldTop": 187,
"FieldType": "Number",
"FieldWidth": 100,
"FormatMask": "",
"HideLabel": false,
"IsIndexed": true,
"LabelHeight": 17,
"LabelLeft": 0,
"LabelTop": 187,
"LabelWidth": 100,
"LastVersionId": 128,
"ListTableId": 0,
"IsMandatory": false,
"Type": "Contact",
"Page1LineNo": 0,
"ProgId": "SuperOffice:12",
"IsReadOnly": false,
"ShortLabel": "NewerNumber",
"TabOrder": 12,
"TextLength": 0,
"Tooltip": "",
"UdefIdentity": 12,
"UDListDefinitionId": 0,
"Justification": "Left",
"Version": 14,
"TemplateVariableName": "cl12",
"HasBeenPublished": true,
"MdoListName": null,
}
Prior to publishing, make sure the Contact user-defined fields are not currently being updated.
GET https://{{env}}.superoffice.com/{{tenant}}/api/v1/Contact/UdefLayout/Publish HTTP/1.1
Authorization: Bearer {{token}}
Accept: application/json; charset=utf-8
Only if the response is False, proceed to publish and complete the delete operation.
Publish the user-defined field.
Warning
A Publish request creates a new version of all user-defined fields for the entity. Therefore, all user-defined fields will have updated UdefFieldId values.
POST https://{{env}}.superoffice.com/{{tenant}}/api/v1/Contact/UdefLayout/Publish HTTP/1.1
Authorization: Bearer {{token}}
Accept: application/json; charset=utf-8
There are several options to get one or all user-defined field, published and non-published fields.
To get published fields, use one of the following endpoints.
- GetPublishedUserDefinedFieldFromFieldLabel
- GetPublishedUserDefinedFieldFromProgId
The get none published fields, use one of the following endpoints:
- GetUserDefinedFieldFromFieldLabel
- GetUserDefinedFieldFromProgId
Get a user-defined field by progId or label text (FieldLabel).
Get By ProgId:
POST https://{{env}}.superoffice.com/{{tenant}}/api/v1/Agents/UserDefinedFieldInfo/GetUserDefinedFieldFromProgId
Authorization: Bearer {{token}}
Accept: application/json; charset=utf-8
Content-Type: application/json; charset=utf-8
{
"ProgId": "SuperOffice:11",
"OwnerType": "Contact"
}
Get By FieldLabel:
POST https://{{env}}.superoffice.com/{{tenant}}/api/v1/Agents/UserDefinedFieldInfo/GetUserDefinedFieldFromFieldLabel
Authorization: Bearer {{token}}
Accept: application/json; charset=utf-8
Content-Type: application/json; charset=utf-8
{
"FieldLabel": "My New Number",
"OwnerType": "Contact"
}
Make the desired property changes and save the user-defined field.
POST https://{{env}}.superoffice.com/{{tenant}}/api/v1/Agents/UserDefinedFieldInfo/SaveUserDefinedFieldInfo
Authorization: Bearer {{token}}
Accept: application/json; charset=utf-8
Content-Type: application/json; charset=utf-8
{
"UDefFieldId": 140,
"ColumnId": 8972,
"FieldDefault": "",
"FieldHeight": 17,
"FieldLabel": "My Newer Number",
"FieldLeft": 102,
"FieldTop": 187,
"FieldType": "Number",
"FieldWidth": 100,
"FormatMask": "",
"HideLabel": false,
"IsIndexed": true,
"LabelHeight": 17,
"LabelLeft": 0,
"LabelTop": 187,
"LabelWidth": 100,
"LastVersionId": 128,
"ListTableId": 0,
"IsMandatory": false,
"Type": "Contact",
"Page1LineNo": 0,
"ProgId": "SuperOffice:12",
"IsReadOnly": false,
"ShortLabel": "NewerNumber",
"TabOrder": 12,
"TextLength": 0,
"Tooltip": "",
"UdefIdentity": 12,
"UDListDefinitionId": 0,
"Justification": "Left",
"Version": 14,
"TemplateVariableName": "cl12",
"HasBeenPublished": true,
"MdoListName": null,
}
The response will contain all of the user-defined fields for this entity, but now the new user-defined field UDefFieldId property will contain a identity value.
The field is not yet viewable in the UI. It needs to first be published.
Publish the user-defined field.
Warning
A Publish request creates a new version of all user-defined fields for the entity. Therefore, all user-defined fields will have updated UdefFieldId values.
Before published fields, make sure there is no active publish event happening at the same time. As long as the IsAnyPublishEventActive call returns false, it is safe to proceed.
POST https://{{env}}.superoffice.com/{{tenant}}/api/v1/Agents/UserDefinedFieldInfo/IsAnyPublishEventActive
Authorization: Bearer {{token}}
Accept: application/json; charset=utf-8
To prevent anyone from overwriting your field changes, set the publish event flag for the entity.
POST https://{{env}}.superoffice.com/{{tenant}}/api/v1/Agents/UserDefinedFieldInfo/SetPublishStartSystemEvent
Authorization: Bearer {{token}}
Accept: application/json; charset=utf-8
Content-Type: application/json; charset=utf-8
{
"OwnerType": "Contact"
}
Finally issue the publish the request to activate the new field changes.
POST https://{{env}}.superoffice.com/{{tenant}}/api/v1/Agents/UserDefinedFieldInfo/Publish
Authorization: Bearer {{token}}
Accept: application/json; charset=utf-8
Content-Type: application/json; charset=utf-8
{
"OwnerType": "Contact"
}
There are several options to get one or all user-defined field, published and non-published fields.
To get published fields, use one of the following endpoints.
- GetPublishedUserDefinedFieldFromFieldLabel
- GetPublishedUserDefinedFieldFromProgId
The get none published fields, use one of the following endpoints:
- GetUserDefinedFieldFromFieldLabel
- GetUserDefinedFieldFromProgId
Get a user-defined field by progId or label text (FieldLabel).
Get By ProgId:
var config = new WebApiOptions(tenant.WebApiUrl);
config.Authorization = new AuthorizationAccessToken("8A:Cust12345.eylksjdf...321C", OnlineEnvironment.SOD);
var udefAgent = new UserDefinedFieldInfoAgent(config);
var udef = await udefAgent.GetUserDefinedFieldFromProgIdAsync(
"SuperOffice:11",
UDefType.Contact,
);
Get By FieldLabel:
var config = new WebApiOptions(tenant.WebApiUrl);
config.Authorization = new AuthorizationAccessToken("8A:Cust12345.eylksjdf...321C", OnlineEnvironment.SOD);
var udefAgent = new UserDefinedFieldInfoAgent(config);
var udef = await udefAgent.GetUserDefinedFieldFromFieldLabelAsync(
"My New Number",
UDefType.Contact
);
Publish the user-defined field to make it appear in the client user interface.
Fields are published by entity type. When published, all user-defined fields for that entity receive a new UDefFieldId number.
// make sure no one else is trying to publish at the same time
if(!await udefAgent.IsAnyPublishEventActiveAsync())
{
// state intention to start publishing new / updated fields.
await udefAgent.SetPublishStartSystemEventAsync(UDefType.Contact);
// publish user-defined field changes by entity type
var result = await udefAgent.PublishAsync(UDefType.Contact);
}
If the fields are not immediately observable in the client user interface (UI), navigate to the application with the ´?flush´ query string parameter at the end of the URL as an authenticated user. The fields should then appear in the UI.
Note
Depending on the user-case it might be a good idea to flush caches.