Modify a Field or Field Group

Custom fields and field groups can be modified. While modifying fields and field groups, users can:

• Modify one or more fields and/or field groups in a single request.

• Add child fields while modifying a field group.

• Re-arrange the Display Order of the field or field group.

While modifying fields and field groups, users cannot:

• Modify the unique identifier of the field or field group.

• Change the ID or the owner of the field.

In Use

Fields and field groups are attached or associated to templates. When a field or field group is associated with a template, it is considered in use. If a field or field group is in use:

• It cannot be deleted.
• The following attributes have modification restrictions:
• Data Type cannot be modified.
• Encryption cannot be modified.
• MinOccurs cannot increase.
• MaxOccurs cannot decrease.
• MinLength cannot increase.
• MaxLength cannot decrease.
• MinValue cannot increase.
• MaxValue cannot decrease.
• Enumeration values cannot be modified, added, or deleted. See Modifying Enumerations below.
• A child of a field group cannot be removed.
• New child fields cannot be added to the group.

If a user tries to modify or delete a field or field group that is in use, an error is returned along with a list of the templates to which the field/group is attached.

Note: The “In Use” validation occurs at the profile data level. Prior to Release 2.1, validation was at the Template level.

Request

Stand-Alone Field

Some fields cannot be modified if they are in use (see In Use above for more information). These fields are noted below.

To modify a field,

1. Specify the unique ID (system generated) for the field. The ID is required for modify and delete actions. This value cannot be modified.

2. Specify how the field is to be modified. The following table defines some of the attributes that are available, as well as any restrictions on modification. For a complete list of attributes, refer to the schema for UProfileReqRsp.
    

   Attribute	Description	Required?	Comments
   Name	Name of the field being modified	Yes
   Type	Data type of the field	Yes	Data type cannot be modified if the field is in use. Enumerations: Allowed for fields of data type String. See Modifying Enumerations below for more information.
   Action	Action to be performed on the field. Possible values are Add, Update, Delete.	Yes	An action "Add" is not applicable at the top-level/stand-alone fields.
   Description	Description of the field	No
   Encrypted	Defines whether the data associated with this field should be encrypted in the database.	No	Default is false. This attribute cannot be modified if the field is in use.
   Masked	Defines whether the field value must be masked and defines the masking pattern.	No	If the custom field is masked, the field value is masked in messaging and logging. Users can define the mask pattern.
   DefaultValue	Defines the default value of the field.	No
   Protected	If true, then special authorization is required for a user to create or modify this field.	No
   DisplayOrder	Display order determines the order in which the field displays in the UI.	No	The display order must be unique.
   Inheritable	Specifies that this field is inherited in child profiles.	No	This attribute cannot be modified if the field is in use.
   MinOccurs, MaxOccurs	Defines the cardinality of the field.	No	If this field is in use, the MinOccurs cannot increase and the MaxOccurs cannot decrease.
   Force	Specify whether this is a forced update or delete.	No	Default is false. Set to true to force and make sure Action is Update or Delete.

Modifying Enumerations

Custom fields can be defined with enumerations, which lists the allowed values for that field. Enumerations can only be defined for fields of data type string. When enumerations are specified, other restrictions (such as Min/Max Length and Min/Max Value) are ignored. When modifying an enumerated field,

• If Action=Update, all existing enumerations are deleted and replaced with the enumerations sent in the update request.

• If Action=Delete, all existing enumerations are deleted.

Field Group

To modify a field group,

1. Specify the unique ID (system generated) for the field group. The ID is required for modify and delete actions. This value cannot be modified.

2. Specify how the field group is to be modified. The following table defines some of the attributes that are available, as well as any restrictions on modification. For a complete list of attributes, refer to the schema for UProfileReqRsp.
    

   Attribute	Description	Required?	Comments
   Name	Name of the field group being modified	Yes
   Action	Action to be performed on the field group. Possible values are Update and Delete.	Yes	To add/update a child field in an existing group, the user must provide the action at the group level as "Update".
   Description	Description of the group as a whole	No
   Protected	If true, then special authorization is required for a user to create or modify this field group.	No
   Inheritable	Specifies that this field group is inherited in child profiles.	No	This attribute cannot be modified if the field is in use.
   MinOccurs	Specifies the minimum number of occurrences permitted within the group.	No	Applies to a field within a group. Cannot be increased once it is in use.
   MaxOccurs	Specifies the maximum number of occurrences permitted within the group.		Applies to a field within a group. Cannot be decreased once it is in use. A maxOccurs>1 would mean that multiple data occurrences are allowed for this field; however, the field is still only a single instance within the group.
   ModifyField	Specifies the fields that belong to this group.	No	If a field group is in use, child fields cannot be removed from the group. New child fields (create new) can be added to an existing group as long as the group is not marked as inheritable.
   Force	Specify whether this is a forced update or delete.	No.	Default is false. Set to true to force and make sure Action is Update or Delete.

 

Response

Stand-Alone Field

For a stand-alone field, the following is returned:

• Unique ID (system generated) per field

• Name of field

• Description of the field

• Data type of field

• Default value of field

• Min length of field

• Max length of field

• Min value of field

• Max value of field

• The field's Immutable property

• Display order

• Inheritability

Field within a Group

For a field within a group, the following is also returned:

• Minimum number of occurrences permitted within the group

• Maximum number of occurrences permitted within the group

Field Group

For a field group, the following is returned:

• Unique ID (system generated) per field group

• Name of the group

• Description of the group

• Whether the group is immutable

• Its child fields and all their details

• Display order

• Inheritability. This attribute can only be modified if the custom field group is not in use. See In Use above for more information.