Devices Operations
| Read Operations | Description |
|---|---|
|
Returns a list of matching device identifiers, given a service name (DDS or UIS) and a filter specifying a device category, a facility, or an associated communication device ID. The return XML will indicate success or failure. |
|
|
Returns a list of linked facilities and their attributes for the specified device, given a service name (DDS or UIS) and a device ID. The return XML will indicate success or failure. |
GetDeviceIds
Given a service name (DDS or UIS) and a filter specifying a device category, a linked facility or an associated communication device ID, this operation will return a list of matching device identifiers. The return XML will indicate success or failure.
Usage
The following table lists and describes all of the child elements of the request node (<GetDeviceIdsReq>).
| Element Name | Required | Description |
|---|---|---|
|
SvcName |
Yes |
The Site.Service to which to connect. This parameter must specify the name of a DDS or UIS Site.Service. If a UIS is specified, the service will resolve to its associated DDS. |
|
DeviceCategory |
No* |
If this element is used, the operation will only return IDs of devices within the specified category. |
|
LinkedFacility |
No* |
If this element is used, the operation will only return IDs of devices linked to the specified facility. |
|
AssocCommDeviceId |
No* |
If this element is used, the operation will only return IDs of devices with the specified associated Comm. Device. |
* Note: One (and only one) of DeviceCategory, LinkedFacility, or AssocCommDeviceId must be specified.
Target Services
The service name node (<SvcName>) must specify the name of a DDS or UIS Site.Service. If a UIS is specified, the service will resolve to its associated DDS.
Examples
Request
<?xml version="1.0"?>
<CygNetEnterpriseOperations xmlns="https://CygNetSCADA.com/Schemas/CygNetEnterpriseObjectsnnn">
<GetDeviceIdsReq>
<SvcName>CYGDEMO.UIS</SvcName>
<DeviceCategory>ED</DeviceCategory>
</GetDeviceIdsReq>
</CygNetEnterpriseOperations>Response
The following example represents a successful response.
<?xml version="1.0" encoding="utf-8"?>
<CygNetEnterpriseOperations xmlns="https://CygNetSCADA.com/Schemas/CygNetEnterpriseObjectsnnn">
<GetDeviceIdsResp>
<SvcName>CYGDEMO.UIS</SvcName>
<DeviceIds>
<DeviceId>TEST1</DeviceId>
<DeviceId>TEST2</DeviceId>
<DeviceId>TEST3</DeviceId>
</DeviceIds>
<OperationResults success="true" resp_timestamp="2023-01-08T00:54:53.392Z" exec_duration="PT0.021S" />
</GetDeviceIdsResp>
</CygNetEnterpriseOperations>The following example represents an unsuccessful response.
<?xml version="1.0" encoding="UTF-8"?>
<CygNetEnterpriseOperations xmlns="https://CygNetSCADA.com/Schemas/CygNetEnterpriseObjectsnnn">
<GetDeviceIdsResp>
<SvcName>CYGDEMO.UIS</SvcName>
<DeviceIds />
<OperationResults success="false" resp_timestamp="2023-11-04T03:15:15.447Z" exec_duration="PT0.002S">
<OperationResult type="ERROR" code="50003">Security check failed for ACS application ENTOPS and event ACCESS</OperationResult>
<OperationResult type="ERROR" code="50208">You are not permitted to execute this operation</OperationResult>
</OperationResults>
</GetDeviceIdsResp>
</CygNetEnterpriseOperations>
GetFacilityLinks
Given a service name (DDS or UIS) and a device ID, this operation will return the list of linked facilities and their attributes for the specified device. The return XML will indicate success or failure.
Usage
The following table lists and describes all of the child elements of the request node (<GetFacilityLinksReq>).
| Element Name | Required | Description |
|---|---|---|
|
SvcName |
Yes |
The Site.Service to which to connect. This parameter must specify the name of a DDS or UIS Site.Service. If a UIS is specified, the service will resolve to its associated DDS. |
|
DeviceId |
No |
The ID of the device for which to retrieve facility links. |
Target Services
The service name node (<SvcName>) must specify the name of a DDS or UIS Site.Service. If a UIS is specified, the service will resolve to its associated DDS.
Examples
Request
<?xml version="1.0"?>
<CygNetEnterpriseOperations xmlns="https://CygNetSCADA.com/Schemas/CygNetEnterpriseObjectsnnn">
<GetFacilityLinksReq>
<SvcName>CYGDEMO.UIS</SvcName>
<DeviceId>FLOWAUTOAP15</DeviceId>
</GetFacilityLinksReq>
</CygNetEnterpriseOperations>Response
The following example represents a successful response.
<?xml version="1.0" encoding="utf-8"?>
<CygNetEnterpriseOperations xmlns="https://CygNetSCADA.com/Schemas/CygNetEnterpriseObjectsnnn">
<GetFacilityLinksResp>
<SvcName>CYGDEMO.UIS</SvcName>
<DeviceId>FLOWAUTOAP15</DeviceId>
<FacilityLinks>
<FacilityLink>FLOWAUTOAP15</FacilityLink>
<FacilityLink>FLOWAUTOAP15_A</FacilityLink>
<FacilityLink>FLOWAUTOAP15_B</FacilityLink>
</FacilityLinks>
<OperationResults success="true" resp_timestamp="2023-01-12T17:44:06.334Z" exec_duration="PT0.071S" />
</GetFacilityLinksResp>
</CygNetEnterpriseOperations>The following example represents an unsuccessful response.
<?xml version="1.0" encoding="UTF-8"?>
<CygNetEnterpriseOperations xmlns="https://CygNetSCADA.com/Schemas/CygNetEnterpriseObjectsnnn">
<GetFacilityLinksResp>
<SvcName>CYGDEMO.UIS</SvcName>
<DeviceId>FLOWAUTOAP15</DeviceId>
<FacilityLinks />
<OperationResults success="false" resp_timestamp="2023-11-04T03:13:45.836Z" exec_duration="PT0.034S">
<OperationResult type="ERROR" code="50003">Security check failed for ACS application ENTOPS and event ACCESS</OperationResult>
<OperationResult type="ERROR" code="50208">You are not permitted to execute this operation</OperationResult>
</OperationResults>
</GetFacilityLinksResp>
</CygNetEnterpriseOperations>
