TransferUserTasks API¶

Transfers all open workflow tasks from one user to another. Used when a user is leaving or is temporarily unavailable.

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

Methods¶

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

Parameters¶

Response¶

Success Response¶

<root success="true" />

Success Response (with warnings)¶

<root success="true" warnings="Some tasks 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/TransferUserTasks
  ?authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
  &fromUserName=jdoe
  &toUserName=jsmith
HTTP/1.1

POST Request¶

POST /srv.asmx/TransferUserTasks 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:TransferUserTasks>
      <tns:AuthenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:AuthenticationTicket>
      <tns:FromUserName>jdoe</tns:FromUserName>
      <tns:ToUserName>jsmith</tns:ToUserName>
    </tns:TransferUserTasks>
  </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 workflow tasks queued against one user to another user.

const root = await call('TransferUserTasks', {
  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 tasks 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 all open (not yet completed) workflow tasks assigned to fromUserName.
• If some tasks cannot be transferred (e.g., due to workflow rules), a warnings attribute is included in the success response describing the issue.
• The response root element is <root>, not <response>.
• Typically used as part of a user offboarding process. Run all relevant TransferUser* APIs before deleting a user.

Related APIs¶

• TransferUserDomainMemberships - Transfer domain memberships
• TransferUserDocumentOwnerships - Transfer document ownerships
• TransferUserWorkflowDefinitions - Transfer workflow definition 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.