Actions applied to a group are applied to all members in the group, and values assigned to a group are assigned to all members in the group.  Certain actions are reserved to administer the group itself, and are not relayed to the group members.  These actions start with "self", such as self.create, self.provision, etc.

You invoke actions on the members through the group’s do topic, and can make assignment to the group as if that assignment was made to each member.

This group example contains the following tasks:

Task 1:  Add Three Datapoints to a Group

This example adds three datapoints to a group with ID 1571.

Begin by using the following REST request:   PUT  /iap/grp/1571/assign/dp 
With the following body:

{
   "datapointQualifiers" : [
      "17q3bm7.2/device/0/nviDO1",
	  "17q3bm7.3/device/0/nviDO1",
	  "17q3bm7.4/device/0/nviDO1"
   ]
}

Response:

204 success.

CMS Action:

The CMS sends the following IAP/MQ message:   glp/0/17q3bm7/rq/grp/group-1571/do   
With the following payload:

{
  "action" : "self.create",
  "args" : {
    "desc" : "gr7",
    "members" : [
        "glp/0/17q3bm7/rq/dev/lon/17q3bm7.2/if/device/0/nviDO1",
        "glp/0/17q3bm7/rq/dev/lon/17q3bm7.3/if/device/0/nviDO1",
        "glp/0/17q3bm7/rq/dev/lon/17q3bm7.4/if/device/0/nviDO1"
    ],
    "provision" : true
  }
}

The group is created and contains the three datapoints.

In this example, the group did not already exist in IAP/MQ, so the first line of the payload is "action" : "self.create", otherwise it would be "action" : "self.add".

Once the group exists, then the IAP/MQ request would contain the self.add action along with the new members to be added to the group.

So now re-issuing the original IAP/REST request:   PUT  /iap/grp/1571/assign/dp       
With the following body:

{
   "datapointQualifiers" : [
	  "17q3bm7.2/device/0/nviDO2",
	  "17q3bm7.3/device/0/nviDO2",
	  "17q3bm7.4/device/0/nviDO2"
   ]
}

Response:

204 success.

CMS Action:

The CMS sends the following IAP/MQ message:   glp/0/17q3bm7/rq/grp/group-1571/do   
With the following payload:

{
  "action" : "self.add",
  "args" : {
   "members" : [
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.2/if/device/0/nviDO2",
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.3/if/device/0/nviDO2",
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.4/if/device/0/nviDO2"
	],
    "apply" : true,
    "provision" : true
  }
}

And now the group contains 6 datapoints.

Task 2:  Add all Datapoints to a Group

This example adds all datapoints available to the current user to a group with ID 1585, except for datapoints with the following qualifiers: "17q3bm7.2/device/0/nviDO1", "17q3bm7.3/device/0/nviDO1", "17q3bm7.4/device/0/nviDO1".

Begin by using the following REST request:   PUT  /iap/grp/1585/assign/dp 
With the following body:   

{
	"datapointQualifiersToExclude" : [
		"17q3bm7.2/device/0/nviDO1",
		"17q3bm7.3/device/0/nviDO1",
		"17q3bm7.4/device/0/nviDO1"
	],
	"processAllCurrentDatapoints" : true
}

Response:

204 success.

CMS Action:

CMS sends the following IAP/MQ message:  glp/0/17q3bm7/rq/grp/group-1585/do 
With the following payload: 

{
  "action" : "self.create",
  "args" : {
	"desc" : "gr1",
    "members" : [
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.3/if/device/0/nvoEPcpos",
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.4/if/device/0/nvoEPbpos",
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.3/if/device/0/nviGroup",
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.4/if/device/0/nvoEQrev",
		...
	],
    "provision" : true
  }
}

The group is created and contains the datapoints specified in the "members" list.  The “members” property contains qualifiers of all datapoints available available to the current user, except for the three that were listed in the REST request: "17q3bm7.2/device/0/nviDO1", "17q3bm7.3/device/0/nviDO1", "17q3bm7.4/device/0/nviDO1". 

Task 3:  Delete Datapoints from a Group

This example deletes all datapoints from a group with ID 1585, except datapoints with qualifier “17q3bm7.3/if/device/0/nvoEPcpos”.

Begin by using the following REST request:   PUT  /iap/grp/1585/unassign/dp    
With the following body:   

{
	"datapointQualifiersToExclude" : [
		"17q3bm7.3/device/0/nvoEPcpos"
	],
	"processAllCurrentDatapoints" : true
}

Response:

204 success.

CMS Action:

CMS sends the following IAP/MQ message:   glp/0/17q3bm7/rq/grp/group-1585/do     
With the following payload: 

{
  "action" : "self.remove",
  "args" : {
	"members" : [
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.4/if/device/0/nvoEPbpos",
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.3/if/device/0/nviGroup",
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.4/if/device/0/nvoEQrev",
		...
	],
    "apply" : true,
    "provision" : true
  }
}

The members property contains all datapoint members of the group except the datapoint specified in the REST request "17q3bm7.3/if/device/0/nvoEPcpos".

In this example, removing the datapoints did not leave an empty group, so the first line of the payload is "action" : “remove”, which does not remove the group, otherwise it would have been “self” : “delete” to simply delete the group.

Task 4:  Add all Devices to a Group 

This example adds all devices available to the current user to a group with ID 1585.

Begin by using the following REST request:   PUT  /iap/grp/1585/assign/devs    
With the following body:   

{
	"processAllCurrentDevices" : true
}

Response:

204 success.

CMS Action:

CMS sends the following IAP/MQ message:   glp/0/17q3bm7/rq/grp/group-1585/do     
With the following payload:    

{
  "action" : "self.add",
  "args" : {
	"members" : [
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.3", 
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.4",
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.2"
	],
    "apply" : true,
    "provision" : true
  }
}

Now the group with ID 1585 contains one datapoint with the qualifier "17q3bm7.3/if/device/0/nvoEPcpos" and the three edge devices listed in the payload.

Task 5:  Delete Devices from a Group

This example deletes all devices from the group with ID 1585, except for the device with DID “17q3bm7.2”.

Begin by using the following REST request:   PUT  /iap/grp/1585/unassign/devs    
With the following body:   

{
	"devicesDIDsToExclude" : ["17q3bm7.2"],
	"processAllCurrentDevices" : true
}

Response:

204 success.

CMS Action:

CMS sends the following IAP/MQ message:   glp/0/17q3bm7/rq/grp/group-1585/do     
With the following payload:    

{
  "action" : "self.remove",
  "args" : {
	"members" : [
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.3", 
		"glp/0/17q3bm7/rq/dev/lon/17q3bm7.4"
	],
    "apply" : true,
    "provision" : true
  }
}

Now the group with ID 1585 contains one datapoint and one edge device.