TransferUserGroupMemberships API¶

Transfers user group memberships from one user to another. The target user is added to all user groups where the source user is currently a member.

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/TransferUserGroupMemberships

Methods¶

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

Parameters¶

Response¶

Success Response¶

<root success="true" />

Success Response (with warnings)¶

<root success="true" warnings="Administrative role memberships were not transferred: only administrators can transfer them." />

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.

User Managers, and library managers when both users are local to libraries they manage.

The role groups ([User Managers], [Audit Managers], [Policy Managers], [R&D Managers], [Administrators], [Search & Category Administrators]) are moved by administrators only, as only administrators add or remove their members. For anyone else they stay with fromUserName, the other memberships still move, and the answer carries the warnings attribute above. Otherwise a User Manager could take a role - a Policy Manager's, say - by transferring its holder's memberships to themselves.

Example¶

GET Request¶

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

POST Request¶

POST /srv.asmx/TransferUserGroupMemberships 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:TransferUserGroupMemberships>
      <tns:AuthenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:AuthenticationTicket>
      <tns:FromUserName>jdoe</tns:FromUserName>
      <tns:ToUserName>jsmith</tns:ToUserName>
    </tns:TransferUserGroupMemberships>
  </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 one user's user group memberships to another user.

const root = await call('TransferUserGroupMemberships', {
  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 carries a warnings attribute when role-group memberships were left behind because the caller is not an administrator. 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¶

• The toUserName is added as a member of each user group where fromUserName is a member.
• Groups where toUserName is already a member are skipped without error.
• Role groups (ids up to 1000) move only when the caller is an administrator; see Required Permissions.
• The response root element is <root>, not <response>.
• Typically used as part of a user offboarding process before deleting the source user.

Related APIs¶

• TransferUserDomainMemberships - Transfer domain memberships
• TransferUserDomainManagerRoles - Transfer domain manager roles
• DeleteUser - Delete a user after transferring their data

Error Codes¶

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

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.