Allow Connector to create new groups

Connector plugins can now create new groups, including the full range
of options on those groups (profile, public, category, etc.).

1 files changed, 23 insertions, 1 deletions

diff --git a/src/lib/Bcfg2/Server/Plugin/interfaces.py b/src/lib/Bcfg2/Server/Plugin/interfaces.py
index 376030792..33f6d338c 100644
--- a/src/lib/Bcfg2/Server/Plugin/interfaces.py
+++ b/src/lib/Bcfg2/Server/Plugin/interfaces.py
@@ -220,10 +220,32 @@ class Connector(object):
 
     def get_additional_groups(self, metadata):  # pylint: disable=W0613
         """ Return a list of additional groups for the given client.
+        Each group can be either the name of a group (a string), or a
+        :class:`Bcfg2.Server.Plugins.Metadata.MetadataGroup` object
+        that defines other data besides just the name.  Note that you
+        cannot return a
+        :class:`Bcfg2.Server.Plugins.Metadata.MetadataGroup` object
+        that clobbers a group defined by another plugin; the original
+        group will be used instead.  For instance, assume the
+        following in ``Metadata/groups.xml``:
+
+        .. code-block:: xml
+
+            <Groups>
+              ...
+              <Group name="foo" public="false"/>
+            </Groups>
+
+        You could not subsequently return a
+        :class:`Bcfg2.Server.Plugins.Metadata.MetadataGroup` object
+        with ``public=True``; a warning would be issued, and the
+        original (non-public) ``foo`` group would be used.
 
         :param metadata: The client metadata
         :type metadata: Bcfg2.Server.Plugins.Metadata.ClientMetadata
-        :return: list of strings
+        :return: list of strings or
+                 :class:`Bcfg2.Server.Plugins.Metadata.MetadataGroup`
+                 objects.
         """
         return list()