Skip to main content

1E 23.7 (SaaS)

ManagementGroups

Entity - ManagementGroups - handles management groups

Minimum API version 3.3

Note for API version 8.0

As of API version 8.0, access to management groups is restricted by the Management Group assignments of the user that makes the request. Other than the exceptions noted below, this means that these APIs will return an error if the user explicitly requests information about a Management Group that he or she is not allowed to use, and the APIs that return a list of Management Groups will exclude from the list any Management Groups that are not allowed for the caller.

Deprecation of Internal mode

As of API version 8.0, the "Internal" mode for creating, updating and deleting Management Groups has been deprecated. The Platform (SLA) APIs have been extended to allow similar functionality as was previously provided by the corresponding ManagementGroup Consumer APIs, so any future development that requires individual manipulation of Management Groups is expected to be done through SLA rather than by invoking the Consumer API.

The obsolete Consumer APIs are those marked below as "Requires Tachyon Management Group support mode to be set to 'Internal'." For backwards compatibility, these APIs can still be invoked in the v8.0 release , but they have been removed from the Swagger documentation and have been marked as Obsolete in the Consumer SDK. You should avoid using them for any new software development, as they will be permanently removed in future versions.

Verb

Request

Notes

Permissions required

POST

/Consumer/ManagementGroups/InitiateSlaSync

Initiate synchronization of Management Groups with SLA.

Requires Tachyon Management Group support mode to be set to 'External'.

Payload

{
   'Repository':'Default Inventory'
}

Change 'Default Inventory' into the name of the SLA repository against which you are synchronizing. It needs to match the repository that is configured in the Coordinator, otherwise you will get back an error.

Requires 'Synchronize' permission on Management Groups

GET

/Consumer/ManagementGroups

Returns all Management Groups.

By default, only non-system Management Groups are returned. In order to get system groups as well, use includeSystemGroups query string parameter and set it to true i.e. https://your.tachyon.server.address/Consumer/ManagementGroups?includeSystemGroups=true

Return payload

[
        {
            "Id": "1",
            "Name": "Management Group A",
            "Description": "",
            "Expression": "",
            "Count": "12",
            "UsableId": "0E9514B6-FD77-4077-9B54-A2AAA0C1953C",
        "HashOfMembers": "5c9f347457272d5edfeb5dd5c0f6fe4e38311b6126908f2612a1e58d8fb5b754"
        },{
            "Id": "2",
            "Name": "Management Group B",
            "Description": "",
            "Expression": "",
            "Count": "7",
            "UsableId": "AD9514B6-FD77-4077-9B54-A2AAA0C1953C",
        "HashOfMembers": "ddff347457272d5edfeb5dd5c0f6fe4e38311b6126908f2612a1e58d8fb5bbcc"
        }
]

New as of API version 8.0 : This API will return all the Management Group that the calling user can see regardless of context. Only useful for Device list; in all other instances callers should use ManagementGroups/SecurableType/{securableType}/Operation/{operation}

By default this endpoint will return a flat list of Management Groups like it did in previous versions. As of version 8.0 this endpoint will accept an optional query string parameter called view. If that parameter is set to tree, this endpoint will return the Management Groups as a tree structure.

Requires one of following:

  • Any permission on any of the Instruction Sets

  • 'Read' permission on Management Groups

GET

/Consumer/ManagementGroups/Id/{id}

Returns a single Management Group by its Id.

Return payload

{
    "Id": "1",
    "Name": "Management Group A",
    "Description": "",
    "Expression": "",
    "Count": "12",
    "UsableId": "0E9514B6-FD77-4077-9B54-A2AAA0C1953C",
    "HashOfMembers": "5c9f347457272d5edfeb5dd5c0f6fe4e38311b6126908f2612a1e58d8fb5b3ea"
}

Requires one of following:

  • Any permission on any of the Instruction Sets

  • 'Read' permission on Management Groups

GET

/Consumer/ManagementGroups/Name/{name}

Returns a single Management Group by its Name.

Name needs to be supplied as Base64Encoded string.

Return payload as above.

Requires one of following:

  • Any permission on any of the Instruction Sets

  • 'Read' permission on Management Groups

GET

/Consumer/ManagementGroups/UsableId/{usableId}

Returns a single Management Group by its UsableId.

Return payload as above.

Requires one of following:

  • Any permission on any of the Instruction Sets

  • 'Read' permission on Management Groups

GET

/Consumer/ManagementGroups/Search/{base64SearchString}

Returns a collection of Management Groups whose names are at least a partial match to the search string.

System Management Groups are not returned.

Search string must be Base64 encoded.

Return payload will be as in GET /Consumer/ManagementGroups.

New as of API version 8.0 : This API will search all the Management Groups that the calling user can see regardless of context. Only useful for Device list, in all other instances callers should use ManagementGroups/SecurableType/{securableType}/Operation/{operation}/Search/{base64SearchString}

Requires one of following:

  • Any permission on any of the Instruction Sets

  • 'Read' permission on Management Groups

POST

/Consumer/ManagementGroups/Search

Returns Management Groups that match search parameters passed in the request body:

  • filter - filter expression.To learn about how to define filter checkUsing scope and filter expressionspage.

  • sort - sort expression. To learn about how to define sort criteria checkSort Definitionpage.

  • start - starting index to support pagination. It begins from 1.

  • pagesize - number of results to fetch

Allowed filter columns:

  • Name

  • CreatedTime

  • ModifiedTime

  • Description

  • UsableId

Allowed sort columns:

  • Name

  • CreatedTime

  • ModifiedTime

Example

POST payload

{
        "Filter": {
                "Operator": "and",
                "Operands":[
                        {  
                           "Attribute":"Name",
                           "Operator":"like",
                           "Value":"Group%"
                 },
                 {  
                           "Attribute":"UsableId",
                           "Operator":"like",
                           "Value":"%2"
                 }
                 ]
                },
        "Start": 100,
        "PageSize": 100,
        "Sort": [{Column: "CreatedTime", Direction: "DESC"}]
}

New as of API version 8.0 : Will search all Management Groups that the calling user can see regardless of context. Only useful for Device list, in all other instances callers should use ManagementGroups/SecurableType/{securableType}/Operation/{operation}/Search

Requires one of following:

  • Any permission on any of the Instruction Sets

  • 'Read' permission on Management Groups

POST

/Consumer/ManagementGroups

Creates a new Management Group.

ManagementGroup object is required and it must have a Name, which must be unique.

UsableId is ignored as it will be generated internally.

Count and HashOfMembers are calculated internally and will be ignored if passed in the API call.

Devices collection is optional and if provided should contain device FQDNs.

Requires Tachyon Management Group support mode to be set to 'Internal'. See note above.

POST payload

{
        "ManagementGroup": {
        "Name": "Management Group A",
            "Description": "",
        "Expression": ""
        },
        "Devices": ["machinename01.somedomain.com", "machinename02.somedomain.com"]
}

Requires 'Write' permission on Management Groups

PUT

/Consumer/ManagementGroups

Updates an existing Management Group.

Id must be a valid Id.

You cannot change UsableId, Count or HashOfMembers

Requires Tachyon Management Group support mode to be set to 'Internal'.

PUT Payload

{
        "Id": 1,
    "Name": "Management Group A renamed",
    "Description": "",
    "Expression": ""
}

Requires 'Write' permission on Management Groups

DELETE

/Consumer/ManagementGroups/Id/{id}

Deletes a Management Group by its Id.

Requires Tachyon Management Group support mode to be set to 'Internal'.

New for version 8.0: An error will be returned if an attempt is made to delete a Management Group on which other entities have dependencies. This includes existence of other inherited Management Groups, Principal/Role assignments, assigned Policies, Surveys, Announcements and Event subscriptions.

Requires 'Write' permission on Management Groups

DELETE

/Consumer/ManagementGroups/Name/{name}

Deletes a Management Group by its Name.

Name needs to be supplied as Base64Encoded string.

Requires Tachyon Management Group support mode to be set to 'Internal'.

New for version 8.0: An error will be returned if an attempt is made to delete a Management Group on which other entities have dependencies. This includes existence of other inherited Management Groups, Principal/Role assignments, assigned Policies, Surveys, Announcements and Event subscriptions.

Requires 'Write' permission on Management Groups

DELETE

/Consumer/ManagementGroups/UsableId/{usableId}

Deletes a Management Group by its UsableId.

Requires Tachyon Management Group support mode to be set to 'Internal'.

New for version 8.0: An error will be returned if an attempt is made to delete a Management Group on which other entities have dependencies. This includes existence of other inherited Management Groups, Principal/Role assignments, assigned Policies, Surveys, Announcements and Event subscriptions.

Requires 'Write' permission on Management Groups

GET

/Consumer/ManagementGroups/Contents/Id/{id}

Returns all devices that belong to given Management Group using Management Group's Id.

Requires 'Read' permission on Management Groups

GET

/Consumer/ManagementGroups/Contents/Name/{Name}

Returns all devices that belong to given Management Group using Management Group's Name.

Name needs to be supplied as Base64Encoded string.

Requires 'Read' permission on Management Groups

GET

/Consumer/ManagementGroups/Contents/UsableId/{usableId}

Returns all devices that belong to given Management Group using Management Group's UsableId.

Requires 'Read' permission on Management Groups

POST

/Consumer/ManagementGroups/Contents

Adds device(s) to a Management Group.

Payload for this request is an object representing a one-to-many relationship using Ids of objects.

Owner has the Id of the Management Group, Elements is an array of Ids of Devices.

POST payload

{
        "ManagementGroupId": 12,
        "DeviceFqdns": ["machinename01.somedomain.com", "machinename02.somedomain.com", "machinename03.somedomain.com", "machinename04.somedomain.com"]
}

After devices have been added to the group Count and HashOfMembers for that group will be recalculated.

Return payload will contain the Management Group in question and all devices that belong to it

Sample Response payload Expand source

{
        "ManagementGroup": {
                "Id": "12",
            "Name": "Management Group A",
        "Description": "",
            "Expression": "",
            "Count": "12",
        "UsableId": "0E9514B6-FD77-4077-9B54-A2AAA0C1953C",
            "HashOfMembers": "5c9f347457272d5edfeb5dd5c0f6fe4e38311b6126908f2612a1e58d8fb5b3ea"
        },
        "Devices": [
                {
            "Id":1,
        "Name":"machinename01",
            "Fqdn":"machinename01.somedomain.com",
            "Status":1,
            "OsType":"Windows",
            "OsVerNum":2814750438195200,
            "OsVerTxt":"Microsoft Windows 10 Enterprise",
            "AgentVersion":281483566841860,
            "Manufacturer":"Dell Inc.",
            "ChassisType":7,
            "DeviceType":"Desktop",
            "CpuType":"Intel(R) Xeon(R) CPU E5-2630 0 @ 2.30GHz",
            "CpuArchitecture":"x64",
            "OsArchitecture":"x64",
            "RamMB":32693,
            "SMBiosGuid":"4c4c4544-0051-5a10-8058-b7c04f47354a",
            "OsGuid":"4c4c4544-0051-5a10-8058-b7c04f47354a",
            "TachyonGuid":"4c4c4544-0051-5a10-8058-b7c04f47354a",
            "BiosVersion":"n/a",
            "LastBootUTC":1454408472,
            "LastConnUtc":1454604670,
            "CreatedUtc":"2016-02-03T17:20:55.003",
            "VrPlatform":"",
            "TimeZone":0,
            "CertType":null,
            "CertExpiryUtc":null,
            "PushToken":null,
            "Model":"Precision T5600",
            "Domain":"somedomain"
                },
                { ... },
                { ... }
        ]
}

Requires Tachyon Management Group support mode to be set to 'Internal'.

Requires 'Write' permission on Management Groups

PUT

/Consumer/ManagementGroups/Contents

Replaces all the devices in a Management Group. All existing devices are deleted, and the devices supplied with this request are stored in their place.

After devices have been updated, the group Count and HashOfMembers for that group will be recalculated.

The incoming payload and the return payload are exactly the same as specified above for a POST request.

Requires 'Write' permission on Management Groups

DELETE

/Consumer/ManagementGroups/Contents

Removes device(s) from a Management Group.

Payload for this request is an object representing a one-to-many relationship using Ids of objects.

Owner has the Id of the Management Group, Elements is an array of Ids of Devices.

DELETE payload

{
        "ManagementGroupId": 12,
        "DeviceFqdns": ["machinename01.somedomain.com", "machinename02.somedomain.com"]
}

After devices have been removed from the group Count and HashOfMembers for that group will be recalculated.

Return payload will contain the Management Group in question and all devices that belong to it.

Sample Response payload Expand source

{
        "ManagementGroup": {
                "Id": "1",
            "Name": "Management Group A",
        "Description": "",
            "Expression": "",
            "Count": "12",
        "UsableId": "0E9514B6-FD77-4077-9B54-A2AAA0C1953C",
            "HashOfMembers": "5c9f347457272d5edfeb5dd5c0f6fe4e38311b6126908f2612a1e58d8fb5b3ea"
        },
        "Devices": [
                {
            "Id":1,
        "Name":"machinename03",
            "Fqdn":"machinename03.somedomain.com",
            "Status":1,
            "OsType":"Windows",
            "OsVerNum":2814750438195200,
            "OsVerTxt":"Microsoft Windows 10 Enterprise",
            "AgentVersion":281483566841860,
            "Manufacturer":"Dell Inc.",
            "ChassisType":7,
            "DeviceType":"Desktop",
            "CpuType":"Intel(R) Xeon(R) CPU E5-2630 0 @ 2.30GHz",
            "CpuArchitecture":"x64",
            "OsArchitecture":"x64",
            "RamMB":32693,
            "SMBiosGuid":"4c4c4544-0051-5a10-8058-b7c04f47354a",
            "OsGuid":"4c4c4544-0051-5a10-8058-b7c04f47354a",
            "TachyonGuid":"4c4c4544-0051-5a10-8058-b7c04f47354a",
            "BiosVersion":"n/a",
            "LastBootUTC":1454408472,
            "LastConnUtc":1454604670,
            "CreatedUtc":"2016-02-03T17:20:55.003",
            "VrPlatform":"",
            "TimeZone":0,
            "CertType":null,
            "CertExpiryUtc":null,
            "PushToken":null,
            "Model":"Precision T5600",
            "Domain":"somedomain"
                },
                { ... },
                { ... }
        ]
}

Requires Tachyon Management Group support mode to be set to 'Internal'.

Requires 'Write' permission on Management Groups

POST

/Consumer/ManagementGroups/Clear/Id/{id}

Removes all Devices from a Management Group by the group's Id.

Requires Tachyon Management Group support mode to be set to 'Internal'.

Requires 'Write' permission on Management Groups

POST

/Consumer/ManagementGroups/Clear/Name/{name}

Removes all Devices from a Management Group by the group's Name.

Name needs to be supplied as Base64Encoded string.

Requires Tachyon Management Group support mode to be set to 'Internal'.

Requires 'Write' permission on Management Groups

POST

/Consumer/ManagementGroups/Clear/UsableId/{usableId}

Removes all Devices from a Management Group by the group's UsableId.

Requires Tachyon Management Group support mode to be set to 'Internal'.

Requires 'Write' permission on Management Groups

GET

/Consumer/ManagementGroups/SecurableType/ {securableType}/Operation/{operation}

Minimum API version 8.0

Replaces /Consumer/ManagementGroups, allowing a filter by securable type and operation.

By default this endpoint will return a flat list of Management Groups. An optional query string parameter called view can be used. If that parameter is set to tree this endpoint will return Management Groups as a tree structure.

NOTE:

If you make a request for "Security" securable type with either "Read" or "Write" operation API behaves differently.

All Management Groups will be returned, not only those caller has Permission on, and every MG returned will have two extra fields are returned. A flag called "CallerHasPermissionToAccess", which indicates whether the caller has requested Permission on a given group and a property called "NumberOfAssignments", which has the number of RBAC assignments that use given Management Group.

Using "Security" context is aimed at RBAC management, so creating assignments between Principals, Roles and Management Groups.

The following is an example of what the tree looks like; for a plain list example, see /Consumer/ManagementGroups above:

Returned tree JSON Expand source

[
    {
        "Children": [
            {
                "Children": [],
                "Id": 4,
                "Name": "UKDesktops",
                "Description": "All desktops in UK",
                "Expression": null,
                "Type": 1,
                "Count": 10,
                "UsableId": "DesktopsUK",
                "HashOfMembers": "AFCFAD58-49C5-45AE-A4F0-5C4EABA0F055",
                "CreatedTimestampUtc": "2021-05-18T16:20:11.47Z",
                "ModifiedTimestampUtc": "2021-05-18T16:20:11.47Z",
                "ParentUsableId": "UK"
            },
            {
                "Children": [],
                "Id": 3,
                "Name": "UKServers",
                "Description": "All servers in UK",
                "Expression": null,
                "Type": 1,
                "Count": 10,
                "UsableId": "ServersUK",
                "HashOfMembers": "C74ACBD3-4BC2-4B97-9B79-568612D234F8",
                "CreatedTimestampUtc": "2021-05-18T16:20:11.47Z",
                "ModifiedTimestampUtc": "2021-05-18T16:20:11.47Z",
                "ParentUsableId": "UK"
            }
        ],
        "Id": 2,
        "Name": "UK",
        "Description": "All computers in UK",
        "Expression": null,
        "Type": 1,
        "Count": 10,
        "UsableId": "UK",
        "HashOfMembers": "ADCA363B-C79F-4AA1-95EC-9357CE1FE88A",
        "CreatedTimestampUtc": "2021-05-18T16:20:11.47Z",
        "ModifiedTimestampUtc": "2021-05-18T16:20:11.47Z",
        "ParentUsableId": "global"
    },
    {
        "Children": [
            {
                "Children": [
                    {
                        "Children": [],
                        "Id": 9,
                        "Name": "USEastDesktops",
                        "Description": "All desktops in East US",
                        "Expression": null,
                        "Type": 1,
                        "Count": 10,
                        "UsableId": "DesktopsEastUS",
                        "HashOfMembers": "3B4D97DF-20B6-41F7-A333-7C1F400FD3F1",
                        "CreatedTimestampUtc": "2021-05-18T16:20:11.47Z",
                        "ModifiedTimestampUtc": "2021-05-18T16:20:11.47Z",
                        "ParentUsableId": "EastUS"
                    },
                    {
                        "Children": [],
                        "Id": 8,
                        "Name": "USEastServers",
                        "Description": "All servers in East US",
                        "Expression": null,
                        "Type": 1,
                        "Count": 10,
                        "UsableId": "ServersEastUS",
                        "HashOfMembers": "2697A98E-6808-4B39-BDDC-0C01C0551483",
                        "CreatedTimestampUtc": "2021-05-18T16:20:11.47Z",
                        "ModifiedTimestampUtc": "2021-05-18T16:20:11.47Z",
                        "ParentUsableId": "EastUS"
                    }
                ],
                "Id": 6,
                "Name": "USEast",
                "Description": "All computers in US East",
                "Expression": null,
                "Type": 1,
                "Count": 10,
                "UsableId": "EastUS",
                "HashOfMembers": "7ECE8794-7852-446F-B97D-EDE731CA4619",
                "CreatedTimestampUtc": "2021-05-18T16:20:11.47Z",
                "ModifiedTimestampUtc": "2021-05-18T16:20:11.47Z",
                "ParentUsableId": "US"
            },
            {
                "Children": [
                    {
                        "Children": [],
                        "Id": 11,
                        "Name": "USWestDesktops",
                        "Description": "All desktops in West US",
                        "Expression": null,
                        "Type": 1,
                        "Count": 10,
                        "UsableId": "DesktopsWestUS",
                        "HashOfMembers": "7E513BD0-DFDE-48A1-9A28-993D1E31CDE8",
                        "CreatedTimestampUtc": "2021-05-18T16:20:11.47Z",
                        "ModifiedTimestampUtc": "2021-05-18T16:20:11.47Z",
                        "ParentUsableId": "WestUS"
                    },
                    {
                        "Children": [],
                        "Id": 10,
                        "Name": "USWestServers",
                        "Description": "All servers in West US",
                        "Expression": null,
                        "Type": 1,
                        "Count": 10,
                        "UsableId": "ServersWestUS",
                        "HashOfMembers": "1D5E80F5-8D2F-403A-8384-83AA8A5682EA",
                        "CreatedTimestampUtc": "2021-05-18T16:20:11.47Z",
                        "ModifiedTimestampUtc": "2021-05-18T16:20:11.47Z",
                        "ParentUsableId": "WestUS"
                    }
                ],
                "Id": 7,
                "Name": "USWest",
                "Description": "All computers in US West",
                "Expression": null,
                "Type": 1,
                "Count": 10,
                "UsableId": "WestUS",
                "HashOfMembers": "9C2CAB68-2E91-4B1C-99AB-E5FEC8C26CE7",
                "CreatedTimestampUtc": "2021-05-18T16:20:11.47Z",
                "ModifiedTimestampUtc": "2021-05-18T16:20:11.47Z",
                "ParentUsableId": "US"
            }
        ],
        "Id": 5,
        "Name": "US",
        "Description": "All computers in US",
        "Expression": null,
        "Type": 1,
        "Count": 10,
        "UsableId": "US",
        "HashOfMembers": "29211754-F6E1-4286-BEA8-9BC1628C74BA",
        "CreatedTimestampUtc": "2021-05-18T16:20:11.47Z",
        "ModifiedTimestampUtc": "2021-05-18T16:20:11.47Z",
        "ParentUsableId": "global"
    }
]

Requires one of following:

  • Any permission on any of the Instruction Sets

  • 'Read' permission on Management Groups

GET

/Consumer/ManagementGroups/SecurableType/ {securableType}/Operation/{operation}/Id/{id}

Minimum API version 8.0

Replaces /Consumer/ManagementGroups/Id/{id} while providing additional filter options.

GET

/Consumer/ManagementGroups/SecurableType/ {securableType}/Operation/{operation}/Name/{name}

Minimum API version 8.0

Replaces Replaces /Consumer/ManagementGroups/Name/{name} while providing additional filter options.

GET

/Consumer/ManagementGroups/SecurableType/ {securableType}/Operation/{operation}/UsableId/{usableId}

Minimum API version 8.0

Replaces Replaces /Consumer/ManagementGroups/UsableId/{usableId} while providing additional filter options.

GET

/Consumer/ManagementGroups/SecurableType/ {securableType}/Operation/ {operation}/Search/{base64SearchString}

Minimum API version 8.0

Replaces Replaces /Consumer/ManagementGroups/Search/{base64SearchString} while providing additional filter options.

POST

/Consumer/ManagementGroups/SecurableType/ {securableType}/Operation/{operation}/Search

Minimum API version 8.0

Replaces Replaces /Consumer/ManagementGroups/Search while providing additional filter options.

GET

/Consumer/ManagementGroups/SecurableType/ {securableType}/Operation/{operation}/Contents/Id/{id}

Minimum API version 8.0

Replaces Replaces /Consumer/ManagementGroups/Contents/Id/{id} while providing additional filter options.

GET

/Consumer/ManagementGroups/SecurableType/ {securableType}/Operation/{operation}/Contents/Name/{name}

Minimum API version 8.0

Replaces Replaces /Consumer/ManagementGroups/Contents/Name/{name} while providing additional filter options.

GET

/Consumer/ManagementGroups/SecurableType/ {securableType}/Operation/ {operation}/Contents/UsableId/{usableId}

Minimum API version 8.0

Replaces Replaces /Consumer/ManagementGroups/Contents/UsableId/{usableId} while providing additional filter options.

GET

/Consumer/ManagementGroups/AllDevices

Minimum API version 8.0

Returns the 'All Devices' Management Group, which is identified in the database by the value "global" for the UsableId.

Requires one of following:

  • Any permission on any of the Instruction Sets

  • 'Read' permission on Management Groups

GET

/Consumer/ManagementGroups/AffectedEntities/ UsableId/{usableId}

Minimum API version 8.0

Returns a list of all entities that are linked to the Management Group.

The use case is to present to the user a warning about the "links" to the MG that would prevent it from being deleted when the user requests deletion of the MG.

Sample output

[
    {
        "EntityName": "ManagementGroup",
        "EntityId": 4,
        "Name": "Servers in East US",
        "Reason": "Management Group 'Servers in East US' inherits from 'Computers in East US'"
    },
    {
        "EntityName": "PrincipalRoleManagementGroup",
        "EntityId": null,
        "Name": "Principal 'John Smith', Role 'Global Approvers'",
        "Reason": "There is an assignment for Principal 'John Smith', Role 'Global Approvers' to Management Group 'Computers in East US'"
    }
]
In this section: