> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superoffice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to update a user-defined field using the web services API

> Describes how to update a user-defined field using web services

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][1].

[1]: https://www.nuget.org/packages/SuperOffice.WebApi

<Tabs>
  <Tab title="RESTful REST API">
    1. Get the user-defined field by progId or label text (FieldLabel).

       ```http theme={null}
       GET https://\{\{env\}\}.superoffice.com/\{\{tenant\}\}/api/v1/Contact/UdefLayout/SuperOffice:1
       Authorization: Bearer \{\{token\}\}
       Accept: application/json; charset=utf-8
       ```

       **Response:**

       ```json theme={null}
       \{
           "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
           \}
           \}
       \}
       ```

    2. Make the desired property changes and save the user-defined field.

       ```http theme={null}
       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,
       \}
       ```

    3. Prior to publishing, make sure the Contact user-defined fields are not currently being updated.

       ```http theme={null}
       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.

    4. Publish the user-defined field.

           <Danger>
             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.
           </Danger>

       ```http theme={null}
       POST https://\{\{env\}\}.superoffice.com/\{\{tenant\}\}/api/v1/Contact/UdefLayout/Publish HTTP/1.1
       Authorization: Bearer \{\{token\}\}
       Accept: application/json; charset=utf-8
       ```
  </Tab>

  <Tab title="HTTP RPC Agent API">
    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

    1. Get a user-defined field by progId or label text (FieldLabel).

       **Get By ProgId:**

       ```http theme={null}
       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:**

       ```http theme={null}
       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"
       \}
       ```

    2. Make the desired property changes and save the user-defined field.

       ```http theme={null}
       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.

    3. Publish the user-defined field.

           <Danger>
             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.
           </Danger>

       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.

       ```http theme={null}
       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.

       ```http theme={null}
       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.

       ```http theme={null}
       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"
       \}
       ```
  </Tab>

  <Tab title="SuperOffice.WebApi">
    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

    1. Get a user-defined field by progId or label text (FieldLabel).

       **Get By ProgId:**

       ```csharp theme={null}
       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:**

       ```csharp theme={null}
       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
           );
       ```

    2. 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.

       ```csharp theme={null}
       // 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.
  </Tab>
</Tabs>

<Note>
  Depending on the user-case it might be a good idea to [flush caches][4].
</Note>

[4]: ../../../caching/flush-cache


## Related topics

- [How to create a user-defined field using the web services API](/en/api/web-services/howto/custom-objects/rest-create-udef-field.md)
- [How to delete a user-defined field using the web services API](/en/api/web-services/howto/custom-objects/rest-delete-udef-field.md)
- [How to get all user-defined fields using the web services API](/en/api/web-services/howto/custom-objects/rest-get-all-udef-fields.md)
- [How to set a user-defined list item on a Udef field (services)](/en/api/web-services/howto/custom-objects/set-udef-listitem-value.md)
- [SuperOffice.WebApi.Agents.UserDefinedFieldInfoAgent](/en/api/reference/webapi/SuperOffice.WebApi.Agents.UserDefinedFieldInfoAgent.md)
- [SuperOffice.WebApi.Data.UserDefinedFieldInfo](/en/api/reference/webapi/SuperOffice.WebApi.Data.UserDefinedFieldInfo.md)