Managing Devices and Groups

Note: We recommend you use the REST API Add/Edit a device.

The following methods create and retrieve data for devices and device groups.

Creating a Device

The create_device method creates a device.

Request Type: CreateDeviceRequest

Element

Type

Description
SessionIDMandatory

String

SessionID obtained from connect method.
DeviceDetailsMandatory NewDevice

Details of device. See New Device Type (see NewDevice type).

Response Type: CreateDeviceResponse

Element

Type

Description
Result

AfaNonEmptyString

Result of method.

Request example: 

<CreateDeviceRequest>
    <SessionID>d89d0cc1f0f9737133a0c53a31598c20</SessionID>
    <DeviceDetails>
        <Brand>ios</Brand>
        <HostName>Foo</HostName>
        <UserName>Bob</UserName>
        <Password>408KWl%8</Password>
        <ConnectionType>regular</ConnectionType>
    </DeviceDetails>
</:CreateDeviceRequest>

Response example: 

<CreateDeviceResponse>
    <Result>1</Result>
</CreateDeviceResponse>

Creating a Device Group

The create_device_group method creates a device group in AFA from a list of devices.

Note: The group display name cannot contain non-alphanumeric characters or spaces. The tree name will be the same as the group display name.

Request Type: CreateDeviceGroupRequest

Element

Type

Description
SessionIDMandatory

String

SessionID obtained from Connect method.
GroupNameMandatory

AfaNonEmptyString

The group display name. The group's display name will also be the group ID (tree name) for the device group. The group ID is created automatically.
DeviceIDMandatory

List of AfaNonEmptyString

List of device IDs included in the device group. Each deviceID must be unique.

Response Type: CreateDeviceGroupResponse

Element

Type

Description
CreateDeviceGroupResponse

AfaNonEmptyString

On success, returns the device group ID.

On failure, throws a SOAP fault.

Request example: 

<CreateDeviceGroupRequest>
    <SessionID>d67d8cc0f8f7525022a8c52a20486c18</SessionID>
    <GroupName>Foo</GroupName>
    <!--1 or more repetitions:-->
    <DeviceID>10_132_16_1</DeviceID>
</CreateDeviceGroupRequest>

Response example: 

<CreateDeviceGroupResponse>Bar4</CreateDeviceGroupResponse>

Adding a Device to a Group

The add_device_to_group method adds a new device to an existing device group.

Request Type: AddDeviceToGroupRequest

Element

Type

Description
SessionIDMandatory

String

SessionID obtained from Connect method.
GroupIDMandatory

AfaNonEmptyString

Device group ID (tree name) to which the new device is added.
DeviceIDMandatory

AfaNonEmptyString

Tree name (entity ID) of the device.

Response Type: AddDeviceToGroupResponse

Element

Type

Description
AddeviceToGroupResponse

AfaNonEmptyBoolean

On success, returns the device group ID.

On failure, throws a SOAP fault.

Request example: 

<AddDeviceToGroupRequest>
    <SessionID>d67d8cc0f8f7525022a8c52a20486c18</SessionID>
    <GroupID>Foo</GroupID>
    <DeviceID>m_10_132_31_1</DeviceID>
</AddDeviceToGroupRequest>

Response example: 

<AddDeviceToGroupResponse>1</AddDeviceToGroupResponse>

Retrieving a List of all Devices

Note: We recommend that, instead of using this method, you use the newer REST API to retrieve a list of all devices: See Get a list of devices.

The get_devices_list method retrieves the list of all devices defined in AFA. For non-administrators, only the devices which the user has permission to view are returned.

Request Type: GetDevicesListRequest

Element

Type

Description
SessionIDMandatory

String

SessionID obtained from Connect method.

Response Type: GetDevicesListResponse

Element

Type

Description
Device

List of DeviceDataResult objects

On success, returns a list of devices. See DeviceDataResult Type (see DeviceDataResult type ).

On failure, throws a SOAP fault.

Request example: 

<GetDevicesListRequest>
    <SessionID>d67d8cc0f8f7525022a8c52a20486c18</SessionID>
</GetDevicesListRequest>

Response example:

Copy 
<GetDevicesListResponse>
<Device>
    <Brand>Cisco Router</Brand>
    <Name>Alon Cluster</Name>
    <ID>m_10_44_32_1</ID>
    <IP>10_32_44_20</IP>
</Device>
<Device>
    <Brand>Fortinet Fortigate</Brand>
    <Name>10.132.16.1</Name>
    <ID>15-m-222</ID>
    <IP>10.131.16.1</IP>
</Device>
<Device>
    <Brand>Juniper SRX</Brand>
    <Name>Dev_gw-R71</Name>
    <ID>Dev_gw-R71</ID>
    <IP>10.132.37.1</IP>
</Device>
</GetDevicesListResponse>

Retrieving a List of all Groups

The get_groups_list method retrieves a list of all groups defined in AFA. For non-administrators, only the groups which the user has permission to view are returned.

Request Type: GetGroupsListRequest

Element

Type

Description
SessionIDMandatory

String

SessionID obtained from Connect method.

Response Type: GetGroupsListResponse

Element

Type

Description
GroupsMandatory Groups

List containing GroupsID. See Groups Type (see Groups type ).

Request example: 

<afa:GetGroupsListRequest>
    <SessionID>74180e54d6023281d9bfcffd4e65f268</SessionID>
</afa:GetGroupsListRequest>

Response example: 

<GetGroupsListResponse>
    <Groups>
        <GroupsID>Bar</GroupsID>
        <GroupsID>Bar3</GroupsID>
        <GroupsID>Foo</GroupsID>
    </Groups>
</GetGroupsListResponse>

Retrieving a List of Devices Contained in a Group

The get_group_content method retrieves a list of devices contained in a group.

Request Type: GetGroupContentRequest

Element

Type

Description
SessionIDMandatory

String

SessionID obtained from Connect method.
GroupIDMandatory

String

Device group ID (tree name) of the group.

Response Type: GetGroupContentResponse

Element

Type

Description
DeviceMandatory

List of DeviceDataResult objects

List of device data results. See DeviceDataResult Type (see DeviceDataResult type ).

Request example: 

<GetGroupContentRequest>
    <SessionID>74180e54d6023281d9bfcffd4e65f268</SessionID>
    <GroupID>Foo</GroupID>
</GetGroupContentRequest>

Response example: 

<GetGroupContentResponse>
    <Device>
        <Brand>Cisco ASA</Brand>
        <DeviceName>10.132.16.1</DeviceName>
        <DeviceID>10_132_16_1</DeviceID>
    </Device>
    <Device>
        <Brand>Check Point</Brand>
        <DeviceName>Alon_Cluster</DeviceName>
        <DeviceID>Alon_Cluster</DeviceID>
    </Device>
    <Device>
        <Brand>Check Point</Brand>
        <DeviceName>fw3</DeviceName>
        <DeviceID>fw3</DeviceID>
    </Device>
    <Device>
        <Brand>Check Point</Brand>
        <DeviceName>Log_server_external</DeviceName>
        <DeviceID>Log_server_external</DeviceID>
    </Device>
</GetGroupContentResponse>

Device Changes Over Time

This enables you to generate a report for monitored changes in devices/groups over time, without logging into the AFA UI. This is mainly for 3rd party applications to store reports, send reports to other users, etc.

Request Type: device_changes_over_time_report

The web service input is:

Element

Type

Description
SessionIDMandatory

String

The Session ID.
EntityIDMandatory

String

Device or Group name.
StartDate, EndDate

String

Date ranges, using the format (yyyy-mm-dd).
Mandatory

 

 
IsLinkReturnTypeMandatory

String

Whether the output is linked to a pdf file (1) or pdf content encoded as a 64-based string (0).

Response Type:

The output is the PDF export of the report generated by AFA (as if the report was generated from the UI and exported) or the file is encoded in 64-bit format.

Request example:

<afa:ChangeOverTimeReportRequest>
          <SessionID>?</SessionID>
          <StartDate>?</StartDate>
          <EndDate>?</EndDate>
          <EntityID>?</EntityID>
          <IsLinkReturnType>?</IsLinkReturnType>
       </afa:ChangeOverTimeReportRequest>

Response example:

<ns1:ChangeOverTimeReportResponse>
          <Output>Link url </Output>
      </ns1:ChangeOverTimeReportResponse>

Deleting a device

The delete_device method deletes a device.

Request Type: DeleteDeviceRequest

Element

Type

Description
SessionIDMandatory

String

SessionID obtained from connect method.
DeviceIDMandatory String

Device ID.

Response Type: DeleteDeviceResponse

Element

Type

Description
Result

AfaNonEmptyString

Result of method.

Request example: 

<DeleteDeviceRequest>
    <SessionID>d89d0cc1f0f9737133a0c53a31598c20</SessionID>
    <DeviceID>10_132_16_1</DeviceID>
</:DeleteDeviceRequest>

Response example: 

<DeleteDeviceResponse>
    <Result>1</Result>
</DeleteDeviceResponse>