CreateGroups

Description

This service creates one or more new groups.

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.
templateGroup	GroupIdentifier	Specifies an existing group that should be used as a template for creating new group. New groups are created based on the group account that you provide in the GroupIdentifier.
updateIfExists	boolean	Specify true to update any existing groups that are found with the same displayName.
group (required)	GroupInfo	Describes information about a group. Specify one or more group arguments to create one or more new groups.
options	MultipleOptions	Holds name value pairing for future elements and enumeration to determine if the service should stop on failure and send an error message, or continue processing.

Response

GroupHolder is returned. The GroupHolder response contains the GroupIdentifier and additional information about the group. For more specific information, see GroupHolder.

Usage

The CreateGroups call provides a method to create one or more new user groups, given the proper privileges. Use the following arguments to control how the new user groups are created:

templateGroup – Enables you to specify an existing group in SBM to act as a template for each new group that you create. If you specify a template group as well as additional details in the group argument, the group parameters that you send will overwrite the values provided by the templateGroup.
Note: You can not use the templateGroup argument in combination with an existing group in the group argument to update an existing group (the system returns "Cannot create a duplicate group"). To update existing groups, see UpdateGroups.
If you do not want to create new groups based on an existing group, do not specify a group in the templateGroup argument. The templateGroup argument is ignored if the updateIfExists argument is set to true.
updateIfExists – Enables you to specify whether existing groups are updated or not. When updateIfExists is true, each group with a display name that matches an existing group is updated based on the parameters sent in the group argument. For example, if the Engineering group already exists in SBM, then the group's current product access is replaced by the accessType value you set in the group argument for the Engineers groups. If you send an empty value and updateIfExists is set to true, then the group's existing value is not changed. To remove existing values, use the UpdateGroups call and set AllowEmptyValues to true. The templateGroup argument is ignored if updateIfExists is set to true.
group – To create new groups, specify one or more unique group arguments. For each unique group argument that you send, an additional group is created in SBM. You must provide the displayName for each new group account. If updateIfExists is set to true and the group names that you send match existing group accounts, then matching groups are updated. If you specify a templateGroup instead, then any additional group information that you provide in the group argument overwrites the corresponding data supplied by the template account. For example, if you specify Engineering as a template group, then the Engineering group's product access and memo value are copied into each new group that you create unless you specifically overwrite these parameters in each group argument.

Faults

Invalid database pointer.
The user lacks sufficient permission to create a group.

XML

The following XML is a snippet of the payload that is sent with CreateGroups. In this example, two new groups are created without a template group.

<urn:CreateGroups>
   <urn:auth>
      <urn:userId>admin</urn:userId>
      <urn:password></urn:password>
      <urn:hostname></urn:hostname>
      <urn:loginAsUserId></urn:loginAsUserId>
   </urn:auth>
   <urn:templateGroup>
      <urn:displayName></urn:displayName>
      <urn:id></urn:id>
      <urn:uuid></urn:uuid>
   </urn:templateGroup>
   <urn:updateIfExists></urn:updateIfExists>
   <urn:group>
      <urn:id>
         <urn:displayName>New Group 1</urn:displayName>
         <urn:id></urn:id>
         <urn:uuid></urn:uuid>
      </urn:id>
      <urn:accessType>ACCESS-USER</urn:accessType>
      <urn:memo>This group contains regular users.</urn:memo>
      <urn:isDeleted></urn:isDeleted>
   </urn:group>
   <urn:group>
      <urn:id>
         <urn:displayName>New Group 2</urn:displayName>
         <urn:id></urn:id>
         <urn:uuid></urn:uuid>
      </urn:id>
      <urn:accessType>ACCESS-EXTERNAL</urn:accessType>
      <urn:memo>This group contains external users.</urn:memo>
      <urn:isDeleted></urn:isDeleted>
   </urn:group>
   <urn:options>
      <urn:multiOption>CONTINUE-ON-FAILURE</urn:multiOption>
   </urn:options>
</urn:CreateGroups>

In this example, the CR Submitters group is used as a template to create the new group:

<urn:CreateGroups>
   <urn:auth>
      <urn:userId>admin</urn:userId>
      <urn:password></urn:password>
      <urn:hostname></urn:hostname>
      <urn:loginAsUserId></urn:loginAsUserId>
   </urn:auth>
   <urn:templateGroup>
      <urn:displayName>CR Submitters</urn:displayName>
      <urn:id></urn:id>
      <urn:uuid></urn:uuid>
   </urn:templateGroup>
   <urn:updateIfExists></urn:updateIfExists>
   <urn:group>
      <urn:id>
         <urn:displayName>New Group</urn:displayName>
         <urn:id></urn:id>
         <urn:uuid></urn:uuid>
      </urn:id>
      <urn:accessType></urn:accessType>
      <urn:memo>This is a copy of the CR Submitters group.</urn:memo>
      <urn:isDeleted></urn:isDeleted>
   </urn:group>
   <urn:options>
      <urn:multiOption>CONTINUE-ON-FAILURE</urn:multiOption>
   </urn:options>
</urn:CreateGroups>