API: updateGroup

9 Minutes to read

Print
Share
Dark
Light

API: updateGroup

9 Minutes to read

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

Starting June 1, 2022, SmarterU will require all API calls to POST to HTTPS. Any POST to HTTP will result in the SU:01 error (i.e., No POST data detected.).
If you are viewing the help in a language other than English, please change your language to English before copying and pasting any code. All API attributes and functions are in English.
Tags are required unless specified.

Description

The updateGroup method edits a group including the group's users, courses, and subscription variants.

Who Has Access

The following users have access to the updateGroup method:

Users with the Group Manager, Manage Group Courses, or Manage Group Users group permission.
Users with the Create New Group account permission.
Administrators and owners.

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>updateGroup</Method>
   <Parameters>
      <Group>
         <Identifier>
            <Name><![CDATA[]]></Name>
               - OR -
            <GroupID><![CDATA[]]></GroupID>
         </Identifier>

         <Name><![CDATA[]]></Name>
         <GroupID><![CDATA[]]></GroupID>
         <Status><![CDATA[]]></Status>
         <Description><![CDATA[]]></Description>
         <HomeGroupMessage><![CDATA[]]></HomeGroupMessage>

         <NotificationEmails>
            <NotificationEmail><![CDATA[]]></NotificationEmail>
         </NotificationEmails>
 
         <UserHelpOverrideDefault><![CDATA[]]></UserHelpOverrideDefault>
         <UserHelpEnabled><![CDATA[]]></UserHelpEnabled>
         <UserHelpEmail><![CDATA[]]></UserHelpEmail>
         <UserHelpText><![CDATA[]]></UserHelpText>

         <Tags2>
            <Tag2>
               <TagID><![CDATA[]]></TagID>
                  - OR -
               <TagName><![CDATA[]]></TagName>
               <TagValues><![CDATA[]]></TagValues>
            </Tag2>
         </Tags2>

         <UserLimit>
            <Enabled></Enabled>
            <Amount></Amount>
         </UserLimit>

         <Users>
            <User>
               <Email><![CDATA[]]></Email>
                  - OR -
               <EmployeeID><![CDATA[]]></EmployeeID>
               <UserAction><![CDATA[]]></UserAction>
               <HomeGroup><![CDATA[]]></HomeGroup>
               <Permissions>
                  <Permission>
                     <Code><![CDATA[]]></Code>
                  </Permission>
               </Permissions>
            </User>
         </Users>

         <LearningModules>
            <LearningModule>
               <ID><![CDATA[]]></ID>
               <LearningModuleAction><![CDATA[]]></LearningModuleAction>
               <AllowSelfEnroll><![CDATA[]]></AllowSelfEnroll>
               <AutoEnroll><![CDATA[]]></AutoEnroll>
            </LearningModule>
         </LearningModules>

         <SubscriptionVariants>
            <SubscriptionVariant>
               <ID><![CDATA[]]></ID>
               <SubscriptionVariantAction><![CDATA[]]></SubscriptionVariantAction>
               <RequiresCredits><![CDATA[]]></AllowSelfEnroll>
            </SubscriptionVariant>
         </SubscriptionVariants>

         <DashboardSetID><![CDATA[]]></DashboardSetID>

      </Group>
   </Parameters>
</SmarterU>

The Group tag group is a container for the group's details.

<Group>
   <Identifier>
      <Name><![CDATA[]]></Name>
         - OR -
      <GroupID><![CDATA[]]></GroupID>
   </Identifier>

   <Name><![CDATA[]]></Name>
   <GroupID><![CDATA[]]></GroupID>
   <Status><![CDATA[]]></Status>
   <Description><![CDATA[]]></Description>
   <HomeGroupMessage><![CDATA[]]></HomeGroupMessage>

   <NotificationEmails>
      <NotificationEmail><![CDATA[]]></NotificationEmail>
   </NotificationEmails>
 
    <UserHelpOverrideDefault><![CDATA[]]></UserHelpOverrideDefault>
    <UserHelpEnabled><![CDATA[]]></UserHelpEnabled>
    <UserHelpEmail><![CDATA[]]></UserHelpEmail>
    <UserHelpText><![CDATA[]]></UserHelpText>

   <Tags2>
      <Tag2>
         <TagID><![CDATA[]]></TagID>
            - OR -
         <TagName><![CDATA[]]></TagName>
         <TagValues><![CDATA[]]></TagValues>
      </Tag2>
   </Tags2>

   <UserLimit>
      <Enabled></Enabled>
      <Amount></Amount>
   </UserLimit>

   <Users>
      <User>
         <Email><![CDATA[]]></Email>
            - OR -
         <EmployeeID><![CDATA[]]></EmployeeID>
         <UserAction><![CDATA[]]></UserAction>
         <HomeGroup><![CDATA[]]></HomeGroup>
         <Permissions>
            <Permission>
               <Code><![CDATA[]]></Code>
            </Permission>
         </Permissions>
      </User>
   </Users>

   <LearningModules>
      <LearningModule>
         <ID><![CDATA[]]></ID>
         <LearningModuleAction><![CDATA[]]></LearningModuleAction>
         <AllowSelfEnroll><![CDATA[]]></AllowSelfEnroll>
         <AutoEnroll><![CDATA[]]></AutoEnroll>
      </LearningModule>
   </LearningModules>

   <SubscriptionVariants>
      <SubscriptionVariant>
         <ID><![CDATA[]]></ID>
         <SubscriptionVariantAction><![CDATA[]]></SubscriptionVariantAction>
         <RequiresCredits><![CDATA[]]></AllowSelfEnroll>
      </SubscriptionVariant>
   </SubscriptionVariants>

   <DashboardSetID><![CDATA[]]></DashboardSetID>

</Group>

The Group tag may contain the following.

The Identifier tag contains the information for the group you want to update. The remaining tags in the Group tag group specify the updates to the group.

Identifier

The identifier of the group you want to update. This tag contains the following.

Tag	Description
Name	The group's name. This tag is mutually exclusive with the GroupID tag.
GroupID	The group's user-specified identifier. This tag is mutually exclusive with the Name tag. This is the GroupID returned by the listGroups method.

Name (optional)

The group's name.

GroupID (optional)

The group's user-specified identifier.

Status (optional)

The group's status. Acceptable values are Active or Inactive.

Description (optional)

The group's description.

HomeGroupMessage (optional)

The message displayed on the learner interface for learner who have the group set as their home group.

NotificationEmails (optional)

A container for the email addresses that the following emails will be sent to:

This tag contains the following.

Tag	Description
NotificationEmail	The user's email address. Each email address should be contained in its own NotificationEmail tag.

UserHelpOverrideDefault (optional)

Indicates whether the account's Enable User Help setting is overridden by the group. Acceptable values are:

1 - The account's Enable User Help setting is overridden by the group.
0 - The account's Enable User Help setting is not overridden by the group.

UserHelpEnabled (optional)

Indicates whether a link displays in the header of the learner interface that enables users who have the group as their home group to request help. Acceptable values are:

1 - A link to request help displays in the learner interface's header.
0 - A link to request help doesn't display in the learner interface's header.

UserHelpEmail (optional)

The email addresses to which help requests will be sent. To specify multiple email addresses, separate each with a comma. If no email address is specified, the help requests will be sent to all administrators.

If an administrator requests help, their request will be sent to our Success Desk.

UserHelpText (optional)

The help link text displayed in the learner interface's header.

Tags2 (optional)

A container for assigning tags to the group. Refer to Tags2 Tag Group.

UserLimit (optional)

Indicates whether there's a limit on how many users can be added to the group and what the maximum number is. The tag may contain the following.

Tag	Description
Enabled	Indicates whether there's a limit on how many users can be added to the group. Acceptable values are: 1 - There's a limit on how many users can be added to the group. 0 - There's no limit on how many users can be added to the group.
Amount	The maximum number of users that can be added to the group.

Tag

Description

Enabled

Indicates whether there's a limit on how many users can be added to the group. Acceptable values are:

1 - There's a limit on how many users can be added to the group.
0 - There's no limit on how many users can be added to the group.

Amount

The maximum number of users that can be added to the group.

Users

A container for assigning users to the group. Refer to Users Tag Group.

LearningModules

A container for assigning courses to the group. Refer to LearningModules Tag Group.

SubscriptionVariants

A container for assigning subscription variants to the group. Refer to SubscriptionVariants Tag Group.

DashboardSetID (optional)

The dashboard set's system-generated identifier.

To obtain a dashboard set's identifier:

Navigate to the Learner Dashboard Builder.
Hover over the dashboard set's name. The dashboard set's ID displays at the bottom of the browser window.

The Tags2 tag group is a container for the group's tags. The tags specified will replace any tags already assigned to the group.

<Tags2>
   <Tag2>
      <TagID><![CDATA[]]></TagID>
         - OR -
      <TagName><![CDATA[]]></TagName>
      <TagValues><![CDATA[]]></TagValues>
   </Tag2>
</Tags2>

Each tag is contained in a Tag2 tag and contains the following.

If no Tag2 tags are included, all existing tags and values assigned to the group will be removed.

TagID

The tag's system-generated identifier. This tag is mutually exclusive with the TagName tag. This is the TagID returned by the getGroup method.

To obtain a tag's ID:

Navigate to the Tag Management Dashboard.
Right click on a tag.
Click Inspect (or Inspect Element, in some browsers). This displays the Developer Tools in your browser. The tag's ID will be located within the code.

If you do not see the code, you may need to view a different tab within your Developer Tools.

TagName

The tag's name. This tag is mutually exclusive with the TagID tag. This is the TagName returned by the getGroup method.

TagValues

A comma-separated list of values for tag values associated with the group.

The Users tag group is a container for the group's users.

<Users>
   <User>
      <Email><![CDATA[]]></Email>
         - OR -
      <EmployeeID><![CDATA[]]></EmployeeID>

      <UserAction><![CDATA[]]></UserAction>
      <HomeGroup><![CDATA[]]></HomeGroup>

      <Permissions>
         <Permission>
            <Code><![CDATA[]]></Code>
         </Permission>
      </Permissions>
   </User>
</Users>

Each user is contained in a User tag and contains the following.

Email

The user's email address. This tag is mutually exclusive with the EmployeeID tag. This is the Email returned by the getUser and listUsers methods.

EmployeeID

The user's employee ID. The user must already exist within your SmarterU account. This tag is mutually exclusive with the Email tag. This is the EmployeeID returned by the getUser and listUsers methods.

UserAction

Indicates whether the user is to be added to or removed from the group. Acceptable values are:

Add - Adds the user to the group.
Remove - Removes the user from the group.

HomeGroup

Indicates if this is the user's home group. Acceptable values are:

1 - The group is the user's home group.
0 - The group isn't the user's home group.

Permissions

A container for the user's group permissions.

<Permissions>
   <Permission>
      <Code><![CDATA[]]></Code>
   </Permission>
</Permissions>

If no tags are added to the Permissions tag, no group permissions will be granted to the user, but they will be assigned to the group.

<Permissions></Permissions>

Each permission is contained in a Permission tag and contains the following.

Tag Description

Tag	Description
Code	The permission to grant the user. Acceptable values are: Manage_Group - Assigns the Group Manager group permission. Create_Course - Assigns the Create Course group permission. Manage_Group_Courses - Assigns the Manage Group Courses group permission. Manage_Users - Assigns the Manage Users group permission. Manage_Group_Users - Assigns the Manage Group Users group permission. View_Learner_Results - Assigns the View Learner Results group permission. Proctor - Assigns the Quiz Proctor group permission. Marker - Assigns the Long Answer Quiz Marker group permission. Instructor - Assigns the Instructor-Led Training Instructor group permission. For example, the following grants the user the Manage Users and Quiz Proctor permissions on the group. `<Permissions> <Permission> <Code>MANAGE_USERS</Code> </Permission> <Permission> <Code>PROCTOR</Code> </Permission> </Permissions>`

Code

The permission to grant the user. Acceptable values are:

Manage_Group - Assigns the Group Manager group permission.
Create_Course - Assigns the Create Course group permission.
Manage_Group_Courses - Assigns the Manage Group Courses group permission.
Manage_Users - Assigns the Manage Users group permission.
Manage_Group_Users - Assigns the Manage Group Users group permission.
View_Learner_Results - Assigns the View Learner Results group permission.
Proctor - Assigns the Quiz Proctor group permission.
Marker - Assigns the Long Answer Quiz Marker group permission.
Instructor - Assigns the Instructor-Led Training Instructor group permission.

For example, the following grants the user the Manage Users and Quiz Proctor permissions on the group.

<Permissions>
   <Permission>
      <Code>MANAGE_USERS</Code>
   </Permission>
   <Permission>
      <Code>PROCTOR</Code>
   </Permission>
</Permissions>

The LearningModules tag group is a container for the group's courses.

<LearningModules>
   <LearningModule>
      <ID><![CDATA[]]></ID>
      <LearningModuleAction><![CDATA[]]></LearningModuleAction>
      <AllowSelfEnroll><![CDATA[]]></AllowSelfEnroll>
      <AutoEnroll><![CDATA[]]></AutoEnroll>
   </LearningModule>
</LearningModules>

Each course is contained in a LearningModule tag and contains the following.

ID

The course's system-generated identifier. This is the LearningModuleID returned by listLearningModules, and the ID returned by getLearnerReport.

LearningModuleAction

Indicates whether the course is to be assigned to or removed from the group. Acceptable values are:

Add- Adds the course to the group.
Remove - Removes the course from the group.

AllowSelfEnroll

Indicates whether the group's users can self-enroll in the course. Acceptable values are:

1 - Group users can self-enroll in the course.
0 - Group users cannot self-enroll in the course.

AutoEnroll

Indicates whether the group's user will be automatically re-enrolled in the course. Acceptable values are:

1 - Group users will be automatically re-enrolled in the course.
0 - Users will not be automatically re-enrolled in the course.

The SubscriptionVariants tag group is a container for the group's subscription variants.

<SubscriptionVariants>
   <SubscriptionVariant>
      <ID><![CDATA[]]></ID>
      <SubscriptionVariantAction><![CDATA[]]></SubscriptionVariantAction>
      <RequiresCredits><![CDATA[]]></AllowSelfEnroll>
   </SubscriptionVariant>
</SubscriptionVariants>

Each variant is contained in a SubscriptionVariant tag and contains the following.

ID

The subscription variant's system-generated identifier. This is the VariantID returned by the listVariants method.

SubscriptionVariantAction

Indicates whether the variant is to be to assigned to or removed from the group. Acceptable values are:

Add - Adds the variant to the group.
Remove - Removes the variant from the group.

RequiresCredits

Indicates whether enrollments in the subscription require credits. Acceptable values are:

1 - Subscription enrollments require credits.
0 - Subscription enrollments don't require credits.

API Response XML Package

The API response XML package will always include a Result, Info, and Errors tag.

<SmarterU>
   <Result></Result>
   <Info>
      <Group><![CDATA[]]></Group>
      <GroupID><![CDATA[]]></GroupID>
   </Info>

   <Errors>
      <Error>
         <ErrorID></ErrorID>
         <ErrorMessage></ErrorMessage>
      </Error>
   </Errors>
</SmarterU>

The response may also contain the following.

Group

The group's name.

GroupID

The group's user-specified identifier.

Example API Response XML Package

Below is an example of an API response XML package.

<SmarterU>
   <Result>Success</Result>
   <Info>
      <Group><![CDATA[Instructional Design]]></Group>
      <GroupID><![CDATA[G-432]]></GroupID>
   </Info>

   <Errors>
   </Errors>
</SmarterU>

Error Codes

Error Code	Message
UG:01	The name provided is not valid.
UG:02	The group ID provided is not valid.
UG:03	The status provided is not valid.
UG:04	The description provided is not valid.
UG:05	The home group message provided is not valid.
UG:06	The notification email provided is not valid.
UG:08	The email provided is not valid.
UG:09	The employee ID provided is not valid.
UG:10	The code provided is not valid.
UG:11	The user action provided is not valid.
UG:12	The value for home group must be 1 or 0.
UG:13	The value for a learning module/subscription variant ID is not valid.
UG:14	One or more tags do not exist in the provided account.
UG:15	Values must be from the pre-defined list specified for the tag.
UG:16	One or more values provided in the Tags2 nodes do not match.
UG:17	The subscription variant action provided is not valid.
UG:18	The value for requires credits must be 1 or 0.
UG:19	The required permissions are not met to call the updateGroup method.
UG:20	The requested group does not exist.
UG:21	The status provided is not valid. Only ACTIVE or INACTIVE are allowed values.
UG:22	User is not a part of the provided account.
UG:23	The user action provided is not valid. Only ADD or REMOVE are allowed values.
UG:24	Learning Module is not a part of the provided account.
UG:25	The learning module action provided is not valid. Only ADD or REMOVE are allowed values.
UG:26	Subscription Variant is not a part of the provided account.
UG:27	The subscription variant action provided is not valid. Only ADD or REMOVE are allowed values.
UG:28	Notification email is invalid.
UG:30	Group Identifier cannot be used.
UG:31	Group has too many notification records.
UG:32	Users could not be added to the group.
UG:33	Group permissions could not be granted to the users.
UG:34	Home group could not be set.
UG:35	Learning Modules could not be added to the group.
UG:36	Learning Modules settings could not be updated.
UG:37	Group name cannot be used.
UG:38	The required permissions are not met to call the updateGroup method.
UG:39	The required permissions are not met to modify the group's dashboard set.
UG:40	The dashboard set does not exist.
UG:41	The dashboard set's scope of availability is not set to home group.
UG:43	The user limit amount must be greater than 0 users.
UG:44	Group would exceed user limit.
UG:45	Number of users in this group would exceed the new limit.
UG:46	Missing required fields to set user help settings.
UG:47	User help email is invalid.
UG:48	User help text is invalid.

Was this article helpful?

What's Next

API: getGroupLearningModules

Table of contents

Description
Who Has Access
API Call XML Package
Group Tag Group
Tags2 Tag Group
Users Tag Group
LearningModules Tag Group
SubscriptionVariants Tag Group
API Response XML Package
Error Codes

API: updateGroup

Description

Who Has Access

API Call XML Package

Group Tag Group

Identifier

Name (optional)

GroupID (optional)

Status (optional)

Description (optional)

HomeGroupMessage (optional)

NotificationEmails (optional)

UserHelpOverrideDefault (optional)

UserHelpEnabled (optional)

UserHelpEmail (optional)

UserHelpText (optional)

Tags2 (optional)

UserLimit (optional)

Users

LearningModules

SubscriptionVariants

DashboardSetID (optional)

Tags2 Tag Group

TagID

TagName

TagValues

Users Tag Group

Email

EmployeeID

UserAction

HomeGroup

Permissions

LearningModules Tag Group

ID

LearningModuleAction

AllowSelfEnroll

AutoEnroll

SubscriptionVariants Tag Group

ID

SubscriptionVariantAction

RequiresCredits

API Response XML Package

Group

GroupID

Example API Response XML Package

Error Codes

Related articles

What's Next