docs: def add_attribute_group_items(attributegroupitems, **kwargs):
  
      """
          Populate attribute groups with items.
          ** attributegroupitems : a list of items, of the form:
              ```{
                      'attr_id'    : X,
                      'group_id'   : Y,
                      'network_id' : Z,
                 }```
  
          Note that this approach supports the possibility of populating groups
          within multiple networks at the same time.
  
          When adding a group item, the function checks whether it can be added,
          based on the 'exclusivity' setup of the groups -- if a group is specified
          as being 'exclusive', then any attributes within that group cannot appear
          in any other group (within a network).
      """
  
      user_id=kwargs.get('user_id')
  
      if not isinstance(attributegroupitems, list):
          raise HydraError("Cannpt add attribute group items. Attributegroupitems must be a list")
  
      new_agis_i = []
  
      group_lookup = {}
  
      #for each network, keep track of what attributes are contained in which groups it's in
      #structure: {NETWORK_ID : {ATTR_ID: [GROUP_ID]}
      agi_lookup = {}
  
      network_lookup = {}
  
      #'agi' = shorthand for 'attribute group item'
      for agi in attributegroupitems:
  
  
          network_i = network_lookup.get(agi.network_id)
  
          if network_i is None:
              network_i = _get_network(agi.network_id)
              network_lookup[agi.network_id] = network_i
  
          network_i.check_write_permission(user_id)
  
  
          #Get the group so we can check for exclusivity constraints
          group_i = group_lookup.get(agi.group_id)
          if group_i is None:
              group_lookup[agi.group_id] = _get_attr_group(agi.group_id)
  
          network_agis = agi_lookup
  
          #Create a map of all agis currently in the network
          if agi_lookup.get(agi.network_id) is None:
              agi_lookup[agi.network_id] = {}
              network_agis = _get_attributegroupitems(agi.network_id)
              log.info(network_agis)
              for net_agi in network_agis:
  
                  if net_agi.group_id not in group_lookup:
                      group_lookup[net_agi.group_id] = _get_attr_group(net_agi.group_id)
  
                  if agi_lookup.get(net_agi.network_id) is None:
                      agi_lookup[net_agi.network_id][net_agi.attr_id] = [net_agi.group_id]
                  else:
                      if agi_lookup[net_agi.network_id].get(net_agi.attr_id) is None:
                          agi_lookup[net_agi.network_id][net_agi.attr_id] = [net_agi.group_id]
                      elif net_agi.group_id not in agi_lookup[net_agi.network_id][net_agi.attr_id]:
                          agi_lookup[net_agi.network_id][net_agi.attr_id].append(net_agi.group_id)
          #Does this agi exist anywhere else inside this network?
          #Go through all the groups that this attr is in and make sure it's not exclusive
          if agi_lookup[agi.network_id].get(agi.attr_id) is not None:
              for group_id in agi_lookup[agi.network_id][agi.attr_id]:
                  group = group_lookup[group_id]
                  #Another group has been found.
                  if group.exclusive == 'Y':
                      #The other group is exclusive, so this attr can't be added
                      raise HydraError("Attribute %s is already in Group %s for network %s. This group is exclusive, so attr %s cannot exist in another group."%(agi.attr_id, group.id, agi.network_id, agi.attr_id))
  
              #Now check that if this group is exclusive, then the attr isn't in
              #any other groups
              if group_lookup[agi.group_id].exclusive == 'Y':
                  if len(agi_lookup[agi.network_id][agi.attr_id]) > 0:
                      #The other group is exclusive, so this attr can't be added
                      raise HydraError("Cannot add attribute %s to group %s. This group is exclusive, but attr %s has been found in other groups (%s)" % (agi.attr_id, agi.group_id, agi.attr_id, agi_lookup[agi.network_id][agi.attr_id]))
  
  
          agi_i = AttrGroupItem()
          agi_i.network_id = agi.network_id
          agi_i.group_id   = agi.group_id
          agi_i.attr_id    = agi.attr_id
  
          #Update the lookup table in preparation for the next pass.
          if agi_lookup[agi.network_id].get(agi.attr_id) is None:
              agi_lookup[agi.network_id][agi.attr_id] = [agi.group_id]
          elif agi.group_id not in agi_lookup[agi.network_id][agi.attr_id]:
              agi_lookup[agi.network_id][agi.attr_id].append(agi.group_id)
  
  
          db.DBSession.add(agi_i)
  
          new_agis_i.append(agi_i)
      log.info(agi_lookup)
  
      db.DBSession.flush()
  
      return new_agis_i