CreatePropertySetDefinition API¶

Creates a new custom property set definition. A property set is a set of custom metadata fields that can be applied to documents, folders, and/or users. The property set name is stored in uppercase and must be unique across the system. This API always creates a public (non-private) property set. To create a private property set, use CreatePropertySetDefinition1.

Endpoint¶

/srv.asmx/CreatePropertySetDefinition

Methods¶

• GET /srv.asmx/CreatePropertySetDefinition?authenticationTicket=...&PropertySetName=...&PropertySetCaption=...&AppliestoDocuments=...&AppliestoFolders=...&AppliestoUsers=...&DomainNames=...
• POST /srv.asmx/CreatePropertySetDefinition (form data)
• SOAP Action: http://tempuri.org/CreatePropertySetDefinition

Parameters¶

Response¶

Success Response¶

<response success="true" error="" />

Error Response¶

<response success="false" error="A category with this name already exists." />

Required Permissions¶

The calling user must be a System Administrator.

Anonymous access is not permitted.

Behavior¶

• PropertySetName is trimmed and automatically converted to uppercase before storage.
• PropertySetName must contain only letters (A-"Z), digits (0-"9), and underscores (_). Special characters and spaces are not allowed.
• When DomainNames is empty or omitted, the property set is global -" available in every library.
• When DomainNames is specified, the property set is domain-restricted -" it only appears in the listed libraries.
• This API always creates the property set with PrivatePropertySet = false (visible to all users including anonymous). To control visibility from anonymous users, use CreatePropertySetDefinition1.
• Internally, a new database table named CUSTOM_<PropertySetName> is created to store the property set rows.
• At least one of AppliestoDocuments, AppliestoFolders, or AppliestoUsers should be true; creating a property set that applies to nothing is technically allowed but has no practical use.

Example¶

GET Request¶

GET /srv.asmx/CreatePropertySetDefinition
    ?authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
    &PropertySetName=ProjectMetadata
    &PropertySetCaption=Project+Metadata
    &AppliestoDocuments=true
    &AppliestoFolders=true
    &AppliestoUsers=false
    &DomainNames=Engineering,Finance
HTTP/1.1
Host: yourserver

POST Request¶

POST /srv.asmx/CreatePropertySetDefinition HTTP/1.1
Host: yourserver
Content-Type: application/x-www-form-urlencoded

authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c&PropertySetName=ProjectMetadata&PropertySetCaption=Project+Metadata&AppliestoDocuments=true&AppliestoFolders=true&AppliestoUsers=false&DomainNames=Engineering

JavaScript¶

Every call answers XML with HTTP 200, success or not, so success is the thing to branch on and errorCode is the number to report.

async function call(action, params) {
  const response = await fetch(`/srv.asmx/${action}?${new URLSearchParams(params)}`);
  const root = new DOMParser()
    .parseFromString(await response.text(), 'text/xml')
    .documentElement;

  if (root.getAttribute('success') !== 'true') {
    throw new Error(`${root.getAttribute('errorCode')}: ${root.getAttribute('error')}`);
  }
  return root;
}

Creates a property set. The name is stored upper case and has to be unique across the server; the caller must be a system administrator. The set starts with no fields - add them with AddPropertySetField.

await call('CreatePropertySetDefinition', {
  authenticationTicket: ticket,
  PropertySetName: 'PROJECTMETADATA',
  PropertySetCaption: 'Project metadata',
  AppliestoDocuments: true,
  AppliestoFolders: false,
  AppliestoUsers: false,
  DomainNames: 'Finance'          // leave empty for a set every library can use
});

DomainNames is declared optional, so an empty value reaches the operation and means "every library": the definition comes back with <DomainRestrictions Global="TRUE" />.

Notes¶

• PropertySetName is stored as the internal key and also forms the database table name (CUSTOM_<name>). It cannot be changed after creation without using UpdatePropertySetDefinition.
• PropertySetCaption is the visible display name in the UI.
• After creating the definition, add fields to it using AddPropertySetField.

Related APIs¶

• CreatePropertySetDefinition1 -" Same as this API but adds a PrivatePropertySet parameter to control anonymous access.
• AddPropertySetField -" Add a field to the new property set definition.
• AddPropertySetFieldOption -" Add option values to a dropdown/list/radio field.
• DeletePropertySetDefinition -" Delete a property set definition.
• UpdatePropertySetDefinition -" Rename or update the properties of a property set definition.
• GetPropertySetDefinition -" Get the full definition of a property set including its fields.

Error Codes¶

The errorCode values this operation returns, checked against a running server: