CreateUsers

Description

This services creates one or more new users.

Arguments

Response

NewUser is returned. The NewUser response contains one UserHolder element for each new user that is created. A temporary password is also returned for each new user account. For more specific information, see NewUser.

Usage

The CreateUsers call enables you create one or more new user accounts in SBM. Use the following arguments to control how the new user accounts are created:

• templateUser – Enables you to specify an existing user account in SBM to act as a template for each new user account that you create. If you specify a template user as well as additional user details in the user argument, the user parameters that you send will overwrite the values provided by the templateUser.
  Note: You can not use the templateUser argument in combination with an existing user in the user argument to update an existing user account (the system returns "Cannot create a duplicate user"). To update existing user accounts, see UpdateUsers.
  If you do not want to create new user accounts based on an existing account, do not specify a user in the templateUser argument. The templateUser argument is ignored if the updateIfExists argument is set to true.
• cloneGroups – Enables you to specify whether or not the group membership of the template user should be replicated for each new user account that you create. If you specify false, new users are created without group membership unless you specify one or more groups in the group element of the user argument. If you specify true, the group membership is cloned and the new user is also added to any additional groups that are specified in the user argument.
• updateIfExists – Enables you to specify whether existing user accounts are updated or not. When updateIfExists is true, each user with a login ID or display name that matches an existing user is updated based on the parameters sent in the user argument. For example, if Bill's login ID already exists in SBM, then Bill's e-mail address is replaced by the e-mail address you set in the user argument for Bill. If you send an empty e-mail address and updateIfExists is set to true, then Bill's existing e-mail address is not changed. To remove existing values, use the UpdateUsers call and set AllowEmptyValues to true. The templateUser argument is ignored if updateIfExists is set to true.
• user – To create new users, specify one or more unique user arguments. For each unique user argument that you send, an additional user is created in SBM. You must provide both the displayName and loginId for each new user account. If updateIfExists is set to true and the user IDs that you send match existing user accounts, the matching users are updated.

  If you specify a templateUser account instead, then any additional user information that you provide in the user argument overwrites the corresponding data supplied by the template account. For example, if you specify Joe as a template user, then Joe's product access, e-mail address, and phone number are copied into each new user account that you create unless you specifically overwrite these parameters in each 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.
• Create user requires a user login id.
• Create user requires a user display name.

XML

The following XML is a snippet of the payload this is sent with CreateUsers.

<urn:CreateUsers>
   <urn:auth>
      <urn:userId>admin</urn:userId>
      <urn:password></urn:password>
      <urn:hostname></urn:hostname>
      <urn:loginAsUserId></urn:loginAsUserId>
   </urn:auth>
   <urn:templateUser>
      <urn:displayName></urn:displayName>
      <urn:id></urn:id>
      <urn:uuid></urn:uuid>
      <urn:loginId></urn:loginId>
   </urn:templateUser>
   <urn:cloneGroups>false</urn:cloneGroups>
   <urn:updateIfExists></urn:updateIfExists>
   <urn:user>
      <urn:id>
         <urn:displayName>John Doe</urn:displayName>
         <urn:id></urn:id>
         <urn:uuid></urn:uuid>
         <urn:loginId>JDoe</urn:loginId>
      </urn:id>
      <urn:accessType>ACCESS-USER</urn:accessType>
      <urn:email>johndoe@companyName.com</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>111-111-1111</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:group>
      <urn:fieldsMask></urn:fieldsMask>
      <urn:notesMask></urn:notesMask>
      <urn:changeHistoryMask></urn:changeHistoryMask>
      <urn:browserMask></urn:browserMask>
      <urn:preferredSolution>
         <urn:displayName>Issue Defect Management</urn:displayName>
      </urn:preferredSolution>
      <urn:solutionData>
         <urn:solution>
            <urn:displayName>Issue Defect Management</urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:uniqueName></urn:uniqueName>
            <urn:tabName>IDM</urn:tabName>
         </urn:solution>
         <urn:homeReport>
            <urn:displayName>Built-In: All Items</urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
         </urn:homeReport>
         <urn:preferredProject>
            <urn:displayName>Animation Pro</urn:displayName>
            <urn:id></urn:id>
            <urn:uuid></urn:uuid>
            <urn:fullyQualifiedName></urn:fullyQualifiedName>
         </urn:preferredProject>
      </urn:solutionData>
   </urn:user>
   <urn:options>
      <urn:multiOption></urn:multiOption>
      <urn:sections>SECTIONS-ALL</urn:sections>
      <urn:specifiedSections></urn:specifiedSections>
   </urn:options>
</urn:CreateUsers>

In this example, a new user is created based on Joe's existing user account. Joe's group membership is replicated as well:

<urn:CreateUsers>
   <urn:auth>
      <urn:userId>admin</urn:userId>
      <urn:password></urn:password>
      <urn:hostname></urn:hostname>
      <urn:loginAsUserId></urn:loginAsUserId>
   </urn:auth>
   <urn:templateUser>
      <urn:displayName></urn:displayName>
      <urn:id></urn:id>
      <urn:uuid></urn:uuid>
      <urn:loginId>Joe</urn:loginId>
   </urn:templateUser>
   <urn:cloneGroups>true</urn:cloneGroups>
   <urn:updateIfExists></urn:updateIfExists>
   <urn:user>
      <urn:id>
         <urn:displayName>John Doe</urn:displayName>
         <urn:id></urn:id>
         <urn:uuid></urn:uuid>
         <urn:loginId>JDoe</urn:loginId>
      </urn:id>
   <urn:user>
</urn:CreateUsers>