UpdateUsers

Description

This service updates one or more existing users.

Arguments

Argument	Type	Description
auth (optional)	Auth	The Auth type supplies credentials and optionally, a host name for licensing. The userId and password can be specified with HTTP BASIC or WS-SECURITY instead.
allowEmptyValues	boolean	Specify true in order to honor empty values that are sent in the user argument. (This removes the current value that is specified on the user account). Default is false.
groupAction	GroupListAction	Specifies whether to add, replace, or remove groups.
user (required)	UserInfo	Used to identify a specific user or list of users for update. Specify multiple user arguments to update multiple users.
options	UserResponseOptions	Specifies whether the service should continue if an error is encountered or stop. Also enables you to limit the data that is returned in the response.

Response

UserHolder is returned. The UserHolder response contains one or more UserIdentifiers and additional information from the users preferences. For more specific information, see UserHolder.

Usage

Use the UpdateUsers call when you need to update one or more user accounts in SBM. Use the following arguments to handle how users are updated by the service:

allowEmptyValues – Enables you to send an empty value in the user argument that is honored by the update. For example, if you need to remove the e-mail address for one or more users, set allowEmptyValues to true and send an empty value in the phoneNumber element of each user argument you send. The default value is false, which means that empty values in the user argument are not honored.
CAUTION:
Use care when updating existing user accounts. Important user information might be mistakenly altered or removed if an existing user match is found and the user parameters you send are incorrect or empty. For example, to delete the phone number for one or more users, do not just clear the phone number value and set allowEmptyValues to true. This will remove all the other user preference settings including the product access (which will be set to None if you send an empty value). When you want to clear values using allowEmptyValues, you must also provide values for elements in UserInfo that you want to preserve.
groupAction – Enables you to add, replace, or remove existing group membership for a user account on update. If you specify ADD-GROUPS, then the user is added to each group that is specified in the user argument. If you specify REPLACE-GROUPS, then each group that is specified in the user argument replaces the current group membership designated for the user. If you specify REMOVE-GROUPS, then the user is removed from the groups that are specified in the user argument.
user – Enables you to specify one or more specific user accounts to be updated. If you want to update multiple users, you must specify each desired user by providing the UserIdentifier in a list of multiple user arguments. To delete users, specify true in the isDeleted element of the user argument.

Use the following elements in the options parameter to control how this call is processed and what data is returned:

multiOption – Enables you to specify whether the service should continue if an error is encountered, or stop and throw an error. If any failures occur, each successive error message is appended to the string that is returned. Multiple error messages are separated by a single newline. Failures do not result in a return before all users have been processed.
sections and specifiedSections – Enables you to specify which parts of a user record should be returned. This allows you to limit the data that is returned for a given user. The sections that aren't specified are not included in the response. For example, if you only need basic user information in the response, use the sections parameter to return only the STANDARD section.

For more information on the options elements, see UserResponseOptions.

Faults

Invalid database pointer.
The user ID is not valid.
The user lacks sufficient permission.

XML

The following XML is a snippet of the payload this is sent with UpdateUsers. This XML shows an update against Nancy's user account. In this example, Nancy is added to the CR Submitters group, her preferred application is set to IDM, and the tab order is set to begin with IDM when she logs in.

<urn:UpdateUsers>
    <urn:auth>
        <urn:userId>Admin</urn:userId>
        <urn:password></urn:password>
        <urn:hostname></urn:hostname>
        <urn:loginAsUserId></urn:loginAsUserId>
    </urn:auth>
    <urn:allowEmptyValues>false</urn:allowEmptyValues>
    <urn:groupAction>ADD-GROUPS</urn:groupAction>
    <urn:user>
        <urn:id>
            <urn:displayName>Nancy</urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:loginId>Nancy</urn:loginId>
        </urn:id>
        <urn:accessType>ACCESS-USER</urn:accessType>
        <urn:email></urn:email>
        <urn:emailCC></urn:emailCC>
        <urn:timezone></urn:timezone>
        <urn:offsetFromGMT>-25200000</urn:offsetFromGMT>
        <urn:dstSavings>3600000</urn:dstSavings>
        <urn:datePreference>DATE-FORMAT-FROM-LOCALE</urn:datePreference>
        <urn:timePreference>TIME-FORMAT-12HOUR</urn:timePreference>
        <urn:namespaceName></urn:namespaceName>
        <urn:phoneNumber>888-888-8888</urn:phoneNumber>
        <urn:locale>en_US</urn:locale>
        <urn:isDeleted></urn:isDeleted>
        <urn:contact></urn:contact>
        <urn:maxNotes>10</urn:maxNotes>
        <urn:maxChangeHistory>10</urn:maxChangeHistory>
        <urn:maxItemsPerPage>20</urn:maxItemsPerPage>
        <urn:group>
            <urn:displayName>CR Submitters</urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
        </urn:group>
        <urn:fieldsMask>1</urn:fieldsMask>
        <urn:notesMask>4</urn:notesMask>
        <urn:changeHistoryMask>4</urn:changeHistoryMask>
        <urn:browserMask></urn:browserMask>
        <urn:preferredSolution>
            <urn:displayName></urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:uniqueName></urn:uniqueName>
            <urn:tabName>IDM</urn:tabName>
        </urn:preferredSolution>
        <urn:solutionData>
            <urn:solution>
                <urn:displayName></urn:displayName>
                <urn:id></urn:id>
                <urn:uuid></urn:uuid>
                <urn:uniqueName>ISSUE_DEFECT_MANAGEMENT</urn:uniqueName>
                <urn:tabName>IDM</urn:tabName>
            </urn:solution>
            <urn:homeReport>
                <urn:displayName>Built-In: All Active Items I Own</urn:displayName>
                <urn:id></urn:id>
                <urn:uuid></urn:uuid>
            </urn:homeReport>
            <urn:preferredProject>
                <urn:displayName>Animation Pro</urn:displayName>
                <urn:id>6</urn:id>
                <urn:uuid></urn:uuid>
                <urn:fullyQualifiedName></urn:fullyQualifiedName>
            </urn:preferredProject>
        </urn:solutionData>
        <urn:solutionData>
            <urn:solution>
                <urn:displayName></urn:displayName>
                <urn:id></urn:id>
                <urn:uuid></urn:uuid>
                <urn:uniqueName>INCIDENT_MANAGEMENT</urn:uniqueName>
                <urn:tabName>Incident Mgmt</urn:tabName>
            </urn:solution>
            <urn:homeReport>
                <urn:displayName>Built-In: All Active Items I Own</urn:displayName>
                <urn:id></urn:id>
                <urn:uuid></urn:uuid>
            </urn:homeReport>
            <urn:preferredProject>
                <urn:displayName>IM Project</urn:displayName>
                <urn:id>3</urn:id>
                <urn:uuid></urn:uuid>
                <urn:fullyQualifiedName></urn:fullyQualifiedName>
            </urn:preferredProject>
        </urn:solutionData>
    </urn:user>
    <urn:options>
        <urn:extraOption>
            <urn:name></urn:name>
            <urn:value></urn:value>
        </urn:extraOption>
        <urn:multiOption></urn:multiOption>
        <urn:sections>SECTIONS-ALL</urn:sections>
        <urn:specifiedSections></urn:specifiedSections>
    </urn:options>
</urn:UpdateUsers>

In this example, Nancy and Carmen are removed from the CR Submitters group:

<urn:UpdateUsers>
    <urn:auth>
        <urn:userId>Admin</urn:userId>
        <urn:password></urn:password>
        <urn:hostname></urn:hostname>
        <urn:loginAsUserId></urn:loginAsUserId>
    </urn:auth>
    <urn:allowEmptyValues>false</urn:allowEmptyValues>
    <urn:groupAction>REMOVE-GROUPS</urn:groupAction>
    <urn:user>
        <urn:id>
            <urn:loginId>Nancy</urn:loginId>
        </urn:id>
        <urn:isDeleted></urn:isDeleted>
        <urn:group>
            <urn:displayName>CR Submitters</urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
        </urn:group>
    </urn:user>
    <urn:user>
        <urn:id>
            <urn:loginId>Carmen</urn:loginId>
        </urn:id>
        <urn:isDeleted></urn:isDeleted>
        <urn:group>
            <urn:displayName>CR Submitters</urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
        </urn:group>
    </urn:user>
</urn:UpdateUsers>

In this example, the John Doe is deleted from the system:

<urn:UpdateUsers>
   <urn:auth>
      <urn:userId>admin</urn:userId>
      <urn:password></urn:password>
      <urn:hostname></urn:hostname>
      <urn:loginAsUserId></urn:loginAsUserId>
   </urn:auth>
   <urn:allowEmptyValues>false</urn:allowEmptyValues>
   <urn:groupAction>ADD-GROUPS</urn:groupAction>
   <urn:user>
      <urn:id>
         <urn:displayName>John Doe</urn:displayName>
         <urn:loginId>JDoe</urn:loginId>
      </urn:id>
   <urn:isDeleted>true</urn:isDeleted>