custom-field-update

Availability

Breeze 4 and Breeze 5; Connect Enterprise Web Services 6

Description

Creates a new custom field or updates the value of an existing one.

You can define up to eight custom fields on a principal or SCO. To create a custom field, call custom-field-update with at least the following fields: object-type, permission-id, name, field-type, is-required, and is-primary. If custom-field-update is successful, it returns a field-id.

To update a custom field, specify the field-id, an object-type, and a name for each field that has a value you want to change.

Be careful when defining custom fields, as retrieving those fields in a report (for example, by calling report-bulk-users) can affect the performance of the server and the database.

Request URL

http://server_name/api/xml
    ?action=custom-field-update
    &account-id=integer
    &object-type=object-type-allowedValue
    &permission-id=allowedValue
    &name=string
    &comments=string
    &field-type=allowedValue
    &is-required=boolean
    &is-primary=boolean
    &display-seq=integer
    &field-id=integer
    &session=BreezeSessionCookieValue

Parameters

Name	Type	Required	Description
`account-id`	Integer	N	The account ID in which the field is created.
`object-type`	String	Y	The type of SCO this field applies to. Required to create and update fields. Allowed values: object-type-principal object-type-meeting object-type-sco object-type-event object-type-read-only Example: `object-type=object-type-principal` The value `object-type-read-only` means that Enterprise Manager displays the value but a user cannot set it using Enterprise Manager. You can also use this value in custom applications.
`permission-id`	String	Y	The permission a principal needs on the object to set or view the field's value. The only allowed value is `manage`. Required to create a field.
`name`	String	Y	The label for the field in the user interface. Required to create a field.
`comments`	String	N	Any comments you define for the custom field, displayed as hint text in your user interface. Can be up to 60 characters long.
`field-type`	String	Y	The type of field. Allowed values are `text`, `textarea`, and `password`. Required to create a field.
`is-required`	Boolean	Y	Whether this custom field is required. Use `true` if a value must be specified for this field in each object that uses it. Otherwise, use `false`. Required to create a field.
`is-primary`	Boolean	Y	Whether this custom field can be deleted through the user interface (`true` if it cannot be deleted, and `false` if it can).
`display-seq`	Integer	N	The sequence in which Enterprise Manager or your application displays the custom field, relative to other custom fields.
`field-id`	Integer	Y	The name of a field that has a value you want to update. Required to update a field.
`session`	String	N	The value of the `BREEZESESSION` cookie. Use this parameter if you do not use a client-side cookie management library.

Filters

Results cannot be filtered or sorted.

Response structure

<?xml version="1.0" encoding="utf-8" ?> 
<results>
    <status code=allowedValue /> 
    <field field-id=integer display-seq=integer object-type=allowedValue
            account-id=integer is-primary=boolean permission-id=allowedValue 
            is-required=boolean field-type=string>
        <comments>string</comments> 
        <name>string</name> 
    </field>
</results>

Response values

Element	Attribute	Type	Description
`results`		Container	All results the action returns.
`status`		Empty, with attributes	The status of the response.
	`code`	Allowed value	A code indicating the response status (see status).
`field`		Empty, with attributes	Information about the custom field.
	`field-id`	Integer	A numeric identifier for the field.
	`display-seq`	Integer	The sequence in which Enterprise Manager or your application displays the field.
	`object-type`	Allowed value	The type of object the field describes (see type for allowed values).
	`account-id`	Integer	For Enterprise Hosted customers, the ID of the account in which the field is defined.
	`is-primary`	Boolean	Whether this custom field can be deleted (`true` if no, `false` if yes).
	`permission-id`	Allowed value	The permission needed to access the custom field (see permission-id for allowed values).
	`is-required`	Boolean	Whether a value for this custom field is required (`true` if yes and `false` if no).
	`field-type`	Allowed value	The type of data the field accepts. Allowed values are `text`, `textarea`, and `password`.
`comments`		String	The comment entered in `comments` in the request.
`name`		String	The name of the field entered in `name` in the request.

Sample request

https://example.com/api/xml?action=custom-field-update
    &object-type=object-type-principal&permission-id=manage
    &account-id=624520&name=jobtitle&comments=test&field-type=text
    &is-required=true&is-primary=false&display-seq=1

Sample response

<?xml version="1.0" encoding="utf-8" ?> 
<results>
    <status code="ok" /> 
    <field field-id="2006472106" object-type="object-type-principal" 
            display-seq="1" account-id="624520" is-primary="false" 
            permission-id="manage" is-required="true" field-type="text">
        <comments>test</comments> 
        <name>jobtitle</name> 
    </field>
</results>