Skip to content

TransferUserSecurityPermissions API

Transfers security permissions (ACL entries) from one user to another. The target user receives all folder and document access rights that were individually assigned to the source user.

A transfer to the same user is accepted... no longer. fromUserName and toUserName may not name one account: the call is refused with 4000, because moving everything away from an account and handing it to nobody is not a transfer. It used to be accepted and reported as a success.

Endpoint

/srv.asmx/TransferUserSecurityPermissions

Methods

  • GET /srv.asmx/TransferUserSecurityPermissions?authenticationTicket=...&fromUserName=...&toUserName=...
  • POST /srv.asmx/TransferUserSecurityPermissions (form data)
  • SOAP Action: http://tempuri.org/TransferUserSecurityPermissions

Parameters

Parameter Type Required Description
authenticationTicket string Yes Authentication ticket obtained from AuthenticateUser.
fromUserName string Yes The username whose security permissions will be transferred.
toUserName string Yes The username who will receive the security permissions.

Response

Success Response

<root success="true" />

Success Response (with warnings)

<root success="true" warnings="Some permissions could not be transferred." />

Error Response

<root success="false" error="[ErrorCode] Error message" />

Required Permissions

An administrator's work (the sysadmin account or a member of [Administrators] as fromUserName) can be transferred by administrators only; anyone else is refused with 4030. Transferring work to an administrator is not restricted. See AdministrativeRoles.

System administrator. Only system administrators can transfer user data between accounts.

Example

GET Request

GET /srv.asmx/TransferUserSecurityPermissions
  ?authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
  &fromUserName=jdoe
  &toUserName=jsmith
HTTP/1.1

POST Request

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

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
&fromUserName=jdoe
&toUserName=jsmith

SOAP Request

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://tempuri.org/">
  <soap:Body>
    <tns:TransferUserSecurityPermissions>
      <tns:AuthenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:AuthenticationTicket>
      <tns:FromUserName>jdoe</tns:FromUserName>
      <tns:ToUserName>jsmith</tns:ToUserName>
    </tns:TransferUserSecurityPermissions>
  </soap:Body>
</soap:Envelope>

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;
}

Moves the permissions granted to one user on folders and documents to another user.

const root = await call('TransferUserSecurityPermissions', {
  authenticationTicket: ticket,
  fromUserName: 'jsmith',
  toUserName: 'agarcia',
});

// There is no errorCode here - branch on success, and read the optional warnings attribute.
const warnings = root.getAttribute('warnings');

An answer may carry a warnings attribute when some of the permissions could not be moved - a conflict at the destination, most often. It is absent when everything moved.

This is one of the calls to make before DeleteUser: what the account holds does not go with it.

Notes

  • Transfers individually assigned ACL entries on folders and documents. Permissions granted through user group membership are not affected.
  • If toUserName already has an explicit permission entry on a given object, the existing entry may be updated or merged.
  • The response root element is <root>, not <response>.
  • Typically used as part of a user offboarding process before deleting the source user.

Error Codes

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

errorCode When
4010 the ticket is expired or unknown
4030 there is no ticket at all
4041 no user by either name
4000 fromUserName and toUserName name the same account
HTTP 400 fromUserName or toUserName was empty; refused by model binding, so there is no error document

Every answer carries an errorCode now, including a 0 on success. The family used to write none at all, so success was the only thing a client could branch on.