API: createGroup

8 Minutes to read

Print
Share
Dark
Light

API: createGroup

8 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 createGroup method adds a group and assigns users, courses and subscription variants to it.

Who Has Access

The following users have access to the createGroup 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>createGroup</Method>
   <Parameters>
      <Group>
         <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><![CDATA[]]></Enabled>
            <Amount><![CDATA[]]></Amount>
         </UserLimit>

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

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

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

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

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

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

<Group>
   <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><![CDATA[]]></Enabled>
      <Amount><![CDATA[]]></Amount>
   </UserLimit>

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

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

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

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

</Group>

The Group tag may contain the following.

Name

The group's name. Group names are unique for your SmarterU account.

GroupID (optional)

The group's unique, user-specified identifier.

Status

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

Description

The group's description.

HomeGroupMessage

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

NotificationEmails

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 (optional)

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

DashboardSetID (optional)

The dashboard set's system-generated identifier. If no value is provided, the account's default dashboard set is assigned to the group.

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.

<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.

TagID

The tag's system-generated identifier. This tag is mutually exclusive with the TagName tag.

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.

TagValues

A comma-separated list of values for the tag. The allowed values are controlled by the tag's settings.

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

The Users tag group is required even if doesn't contain any tags.

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

If no tags are added to the Users tag, no users will be assigned to the group.

<Users></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. This tag is mutually exclusive with the Email tag. This is the EmployeeID returned by the getUser and listUsers methods.

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 container for the group's courses.

The LearningModules tag group is required even if doesn't contain any tags.

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

If no tags are added to the LearningModules tag, no courses will be assigned to the group.

<LearningModules></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.

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>
      <RequiresCredits><![CDATA[]]></AllowSelfEnroll>
   </SubscriptionVariant>
</SubscriptionVariants>

If no tags are added to the SubscriptionVariants tag, no variants will be assigned to the group.

<SubscriptionVariants></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.

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[Fina Partners]]></Group>
      <GroupID><![CDATA[G-432]]></GroupID>
   </Info>

   <Errors>
   </Errors>
</SmarterU>

Error Codes

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

Was this article helpful?

What's Next

API: createRole

Table of contents

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

API: createGroup

Description

Who Has Access

API Call XML Package

Group Tag Group

Name

GroupID (optional)

Status

Description

HomeGroupMessage

NotificationEmails

UserHelpOverrideDefault (optional)

UserHelpEnabled (optional)

UserHelpEmail (optional)

UserHelpText (optional)

Tags2 (optional)

UserLimit (optional)

Users

LearningModules

SubscriptionVariants (optional)

DashboardSetID (optional)

Tags2 Tag Group (optional)

TagID

TagName

TagValues

Users Tag Group

Email

EmployeeID

HomeGroup

Permissions

LearningModules Tag Group

ID

AllowSelfEnroll

AutoEnroll

SubscriptionVariants Tag Group (optional)

ID

RequiresCredits

API Response XML Package

Group

GroupID

Example API Response XML Package

Error Codes

Related articles

What's Next