Security Controls REST API

Home 

Machine Groups

Machine groups are used to organize and track the machines that are included in a scan. You can add, edit and delete machine groups.

Base URL

        https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups

Supported Requests

Method URL Input Return

DELETE

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}

 

None

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/discoveryFilters

 

Success code

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/discoveryFilters/{filter Id}

 

Success code

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/virtualMachineDiscoveryFilters

 

Success code

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/virtualMachineDiscoveryFilters/{filter Id}

 

Success code

     

GET

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups

URL Parameters

MachineGroup[]

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}

 

Configuration information for the specified machine group

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/UsedBy

 

List of entities using the specified machine group.

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/discoveryFilters

 

 

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/virtualMachineDiscoveryFilters

 

 
     

POST

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups

Request Body

ErrorPolicy (optional)

Machine Group

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/discoveryFilters

 

 

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/virtualMachineDiscoveryFilters

 

 
     

PUT

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}

Request Body

Success code

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{Id}/credential

 

Success code (removes the credential)

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/credential/{admin credential}

 

Success code (sets the group credential)

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/discoveryFilters/{filter Id}

 

 

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/{group Id}/virtualMachineDiscoveryFilters/{filter Id}

 

 

Input Models

URL Parameters

Name Type Description

count

Integer

Provide the count of items to return. The maximum value is 50.

createdByMe

Boolean

Returns only those items created by the user.

name

String

Returns the items whose name matches the specified name.

start

Integer

Sets the starting point.

path

String

Returns the items containing the path.

Request Body

Name Required? Type Default Value Description

credentialId

No

Guid

None

The unique identifier of the credential associated with the machine group.

description

No

String

None

Provides a description of the machine group.

discoveryFilters

No

DiscoveryFilters[]

None

Specifies a list of machine group filters or sub-items defining the types of machines and container to operate on.

isBuiltIn

No

Boolean

false

Specifies if the machine group is a built-in (predefined) group such as My Machine or My Domain.

name

Yes

String

None

The unique, user-defined name of the machine group.

path

No

String

None

The path that describes the location of the machine group within the My Machine Groups list in the navigation pane.

Example: Lab\Servers

serverFilterTypes

No

ServerFilterTypes[]

All

The server filter types that will be included when scanning a machine group.

virtualMachineDiscoveryFilters

No

VirtualMachine
DiscoveryFilters

None

Virtual discovery filters. This corresponds with the machines contained in the bottom pane of the Hosted Virtual Machines tab or the Workstation Virtual Machines tab. This parameter contains two properties:

errorPolicy – required, enumeration type = ErrorPolicy (valid values are Throw, Omit)

HostedVirtualServer[] array. has the following properties:

adminCredentialId – Optional, Guid.

inventoryPath – required string, virtual inventory path.

note: optional, string human note or description.

serverName: hypervisor or management server name

DiscoveryFilter Request Body

Name Required? Type Default Value Description

adminCredentialId

No

Guid

None

The unique identifier of the credential associated with the admin credential.

category

No

String

None

 

inventoryPath

No

 

None

The path that describes the location.

Example: /Server/vm/QA/vm-qa-w81x64-1

isExcluded

No

Boolean

false

 

note

 

String

None

A user-specified note or description.

serverName

No

String

None

 

 

Example

Add a machine group named "Sample Group"

POST Request

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups

{

"Name": "Sample Group",

"Description":"A sample group created using the REST API"

}

Example Response

{

"creator": "SHAVLIK\\joe.coder",

"description": "A sample group created using the REST API",

"id": 7,

"isBuiltIn": false,

"isReadOnly": false,

"links": {

"self": {

"href": "https://device-name.fakedomain.com:3121/st/console/api/v1.0/machinegroups/7"

},

"discoveryfilters": {

"href": "https://device-name.fakedomain.com:3121/st/console/api/v1.0/machinegroups/7/discoveryfilters"

},

"virtualmachinediscoveryfilters": {

"href": "https://device-name.fakedomain.com:3121/st/console/api/v1.0/machinegroups/7/virtualmachinediscoveryfilters"

},

"usedby": {

"href": "https://device-name.fakedomain.com:3121/st/console/api/v1.0/machinegroups/7/usedby"

}

},

"name": "Sample Group",

"serverFilterTypes": "All"

}

Other Request Examples

Add a machine group containing one machine and an associated credential

POST Request

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups

{

"Name": "Example Machine Group",

"CredentialId": "01234567-89AB-CDEF-0123-456789ABCDEF",

"Description":"A machine group example",

"Path":"Path1",

"DiscoveryFilters":[ {

"AdminCredentialId": "01234567-89AB-CDEF-0123-456789ABCDEF",

"category": "MachineName",

"Name": "SO-W2K12R2.dev.domainname.com",

"IsExcluded": "False"

}]

}

Find machine group information for the first 10 machine groups

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/?count=10

Find machine group information for machine group with id 8

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/8

Add a virtual machine discovery filter to an existing machine group with ID 38

POST Request

https://<consoleFQDN:port>/st/console/api/v1.0/machinegroups/38/virtualmachinediscoveryfilters

[{

"hostedVirtualMachines": [

{

"serverName": "vCenter.shavlik.com",

"AdminCredentialId": "fffbe3f5-42e1-40a7-b3d4-6d2dd9bcb1fd",

"inventoryPath": "/ELENDIL/vm/QA/VMH-QA-W81X64-2",

"note": "b note"

}

]

}]

 

Output Models

MachineGroup

Name Type Description

creator

 

String

The name of the user who created the machine group.

Example: MyDomain\\John.Doe

credentialId

Guid

The unique identifier of the credential associated with the machine group.

description

String

Provides a description of the machine group.

discoveryFilters

DiscoveryFilters[]

Specifies a list of machine group filters or sub-items defining the types of machines and container to operate on.

id

Integer

The unique identifier of the machine group.

isBuiltIn

Boolean

Specifies if the machine group is a built-in (predefined) group such as My Machine or My Domain.

isReadOnly

Boolean

Specifies if the machine group is editable. All user-defined machine groups are editable, as well as the My Test Machines group.

links

Links

Shows the related URLs for each machine group, the discoveryfilters, the virtualmachinediscoveryfilters and the usedby list.

name

String

The unique, user-defined name of the machine group.

path

String

The path that describes the location of the machine group within the My Machine Groups list in the navigation pane.

Example: Lab\Servers

serverFilterTypes

ServerFilterTypes[]

The server filter types that will be included when scanning a machine group.

virtualMachineDiscoveryFilters

VirtualMachine
DiscoveryFilters

Virtual discovery filters. This corresponds with the machines contained in the bottom pane of the Hosted Virtual Machines tab or the Workstation Virtual Machines tab. This parameter contains two properties:

errorPolicy – required, enumeration type = ErrorPolicy (valid values are Throw, Omit)

HostedVirtualServer[] array. has the following properties:

adminCredentialId – Optional, Guid.

inventoryPath – required string, virtual inventory path.

note: optional, string human note or description.

serverName: hypervisor or management server name

Discovery Filters

Name Type Description

adminCredentialID

Guid

The ID of the associated administrative credential ID (if any).

category

DiscoveryFilterType

The type of filter or machine group item.

containerCredentialId

Guid

The ID of the associated browse or container credential ID (if any).

id

Integer

The unique identifier of the item.

includeChildOU

Boolean

Include child OUs.

isExcluded

Boolean

Is the item included or excluded during the operation?

links

Links

Shows the related URL for the discovery filter.

name

String

The filter or endpoint name.

nestedGroupId

Integer

The nested group ID.

note

String

A user-specified note or description.

DiscoveryFilterType

An enumerated type that defines what category an item belongs to. These values must be explicitely defined with specific number values because they map to integer type information contained in the database and in previous versions of the product.

Name Description

InvalidType

Represents an invalid type for a discover filter.

MachineName

Represents that a discovery filter was added as a machine name.

Domain

Represents that a discovery filter was added as a domain.

IPAddress

Represents that a discovery filter was added as a single IP address.

IPRange

Represents that a discovery filter was added as a range of IP addresses.

Server

Represents that a discovery filter was added as a server.

PredefinedGroup

Represents that a discovery filter was added as a predefined group.

MachineFile

Represents that a discovery filter was added from a list of machine names.

DomainFile

Represents that a discovery filter was added from a list of domains.

IPRangeFile

Represents that a discovery filter was added from a list of IP ranges.

IPAddressFile

Represents that a discovery filter was added as a list of IP addresses.

OrganizationalUnit

Represents that a discovery filter was added as an organizational unit. When searching via OU, the OU name should be properly escaped for any LDAP special characters.

EntireNetwork

Represents that a discovery filter was added as an entire group.

OfflineDirectory

Represents that a discovery filter was added as a folder that contains offline virtual images.

OfflineDirectoryFile

Represents that a discovery filter was added as a folder that contains offline virtual images (linked).

OfflineImage

Represents that a discovery filter was added as an offline virtual image path.

OfflineImageFile

Represents that a discovery filter was added as an offline virtual machine file (linked).

EsxHostedOfflineSystem

Represents that a discovery filter was added an an ESX Server.

VirtualCenterHostedOfflineSystem

Represents that a discovery filter was added as a hosted VirtualCenter Server.

NestedGroup

Represents that a discovery filter was added as a nested group.

VirtualServerWildcard

Represents that a discovery filter was added as a virtual server wildcard.

ServerFilterTypes

Name Description

Workstation

 

Server

 

SqlServer

 

DomainController

 

PrintServer

 

IisServer

 

UsedBy

Name Type Description

name

String

The name of the item using the machine group.

usageType

 

The type of component using the machine group.


Was this article useful?    

The topic was:

Inaccurate

Incomplete

Not what I expected

Other