Managing Collector Instances

The Create Collector Instance API
Using the Create Collector Instance API, you can create a collector instance.
METHOD POST
URI 
https://<historianservername>/historian-rest-api/v1/collector/createnewinstance
SAMPLE URI 
https://<historianservername>/historian-rest-api/v1/collector/createnewinstance
Payload
{
"mode":1,
"CollectorSystemName":"xyz",
"InterfaceDescription":"xyz_Simulation_<IP address>_2",
"DataPathDirectory":"C:\\Proficy Historian Data",
"CollectorDestination":"Historian",
"winUserName":"","winPassword":"",
"InterfaceSubType":"",
"DestinationHistorianUserName":"abc",
"DestinationHistorianPassword":"password",
"DestinationHistorian":"<IP address>",
"General1":"",
"General2":"",
"General3":"123",
"General4":"",
"General5":"",
"Type":2,
"InterfaceName":"<source server>_<type of the collector>_<destination server>"
}
Note:
  • The DestinationHistorian parameter will not have a value for offline collector configuration.
  • To connect to MQTT destinations such as AWS IoT and Google Cloud Platform (GCP), you must provide an encrypted password.
SAMPLE RESPONSE 
{

    "ErrorCode": 0,

    "ErrorMessage": null

}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" 
-H "Authorization: Bearer <TOKEN>” -d “{ \"mode\":1,\"CollectorSystemName\":\"xyz\",
\"InterfaceDescription\":\"xyz_Simulation_<IP address>_2\",\"DataPathDirectory\":\"C:\\Proficy Historian Data\",
\"CollectorDestination\":\"Historian\",\"winUserName\":\"\",\"winPassword\":\"\",
\"InterfaceSubType\":\"\",\"DestinationHistorianUserName\":\"abc\",
\"DestinationHistorianPassword\":\"password\",
\"DestinationHistorian\":\"<IP address>\",\"General1\":\"\",
\"General2\":\"\",\"General3\":\"xyz\",\"General4\":\"\",\"General5\":\"\",
\"Type\":2,\"InterfaceName\":\"<source server>_<type of the collector>_<destination server>\"}” -X POST 
https://<historianservername>/historian-rest-api/v1/collector/createnewinstance
Table 1. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, ErrorCode = 0 implies the operation was successful.
ErrorMessage String Yes For example, NULL.
The Get Collector Instance Details API
Using the Get Collector Instance Details API, you can view the details of a collector instance.
METHOD GET
URI 
https://<historianservername>/historian-rest-api/v1/collector/instancedetails/<interface name>
SAMPLE QUERY PARAM GET URL 
https://<historianservername>/historian-rest-api/v1/collector/instancedetails/<interface name>
SAMPLE RESPONSE 
{
"ErrorCode":0,
"ErrorMessage":null,
"Data":
{
"CloudDestination":"",
"InterfaceSubType":"",
"CollectorSystemName":"xyz",
"Type":2,
"DefaultCompression":false,
"CloudInformationLogLevel":0,
"InterfaceDataDir":"C:\\Proficy Historian Data",
"SourceServer":"",
"Username":"",
"Password":"",
"DestinationType":"Historian",
"DestinationServer":"abc",
"DebugLogLevel":0,
"InterfaceInstallDrive":"C",
"ConnnectionString":"xyz"
}
}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” 
https://<historianservername>/historian-rest-api/v1/collector/instancedetails/xyz_Simulation_<IP address>_2
Table 2. Query Parameters
Parameter Description Required? Values
interface name The interface name of the collector whose details you want to view. Yes String
Table 3. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, ErrorCode = 0 implies the operation was successful.
ErrorMessage String Yes For example, NULL.
The Edit Collector Instance API
Using the Edit Collector Instance API, you can modify the cloud parameters of a collector instance. The collector instance will be restarted after you make changes.
METHOD PUT
URI 
https://<historianservername>/historian-rest-api/v1/collector/editinstance
SAMPLE URI 
https://<historianservername>/historian-rest-api/v1/collector/editinstance
Payload
{"interfaceName":"<source server>_<type of the collector>_<destination server>",
"messageCompression":0,
"azureLogLevel":1,
"debugMode":0,
"CollectorDestination":"Predix",
"DestinationHistorian":"abc",
"mode":1,
"CloudDestinationAddress":"wss://def.run.abc.ice.predix.io/v1/stream/messages",
"IdentityIssuer":"https://1234.predix-uaa.run.abc.ice.predix.io/oauth/token",
"ClientID":"xyz",
"ClientSecret":"123",
"ZoneID":"1234",
"Proxy":"http://1.2.3.4:80",
"ProxyUserName":"",
"ProxyPassword":"",
"DatapointAttribute1":"",
"DatapointAttribute2":"",
"DatapointAttribute3":"",
"DatapointAttribute4":""}
Note:
  • The DestinationHistorian parameter will not have a value for offline collector configuration.
  • To connect to MQTT destinations such as AWS IoT and Google Cloud Platform (GCP), you must provide an encrypted password.
SAMPLE RESPONSE 
{

    "ErrorCode": 0,

    "ErrorMessage": null

}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" 
-H "Authorization: Bearer <TOKEN>” -d “{\"interfaceName\":\"<source server>_<type of the collector>_<destination server>\",
\"InterfaceName\":\"<source server>_<type of the collector>_<destination server>\",\"messageCompression\":0,\"azureLogLevel\":1,
\"debugMode\":0,\"CollectorDestination\":\"Predix\",\"DestinationHistorian\":\"abc\",\"mode\":1,
\"CloudDestinationAddress\":\"wss://wss://def.run.abc.ice.predix.io/v1/stream/messages\",
\"IdentityIssuer\":\"https://1234.predix-uaa.run.abc.ice.predix.io/oauth/token/",
\"ClientID\":\"HistQA\",\"ClientSecret\":\"Gei321itc\",\"ZoneID\":\"1234\",
\"Proxy\":\"http://1.2.3.4:80\",\"ProxyUserName\":\"\",\"ProxyPassword\":\"\",
\"DatapointAttribute1\":\"\",\"DatapointAttribute2\":\"\",\"DatapointAttribute3\":\"\",
\"DatapointAttribute4\":\"\"}” -X PUT 
https://<historianservername>/historian-rest-api/v1/collector/editinstance
Table 4. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, ErrorCode = 0 implies the operation was successful.
ErrorMessage String Yes For example, NULL.
The Azure Log Level API
Using the Azure Log Level API, you can set the debug information log level for destination - Azure IoT Hub. You can set a value ranging from 0 to 4.
METHOD PUT
URI 
https://<historianservername>/historian-rest-api/v1/collector/azureloglevel
SAMPLE URI 
https://<historianservername>/historian-rest-api/v1/collector/azureloglevel
Payload
{"interfaceName":""InterfaceName":"<source server>_<type of the collector>_<destination server>"", 
"azureLogLevel":1,}
SAMPLE RESPONSE 
{

    "ErrorCode": 0,

    "ErrorMessage": null

}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -i -H 
"Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d 
“{\"interfaceName\":\"<source server>_<type of the collector>_<destination server>\",\"azureLogLevel\":1}” -X PUT 
https://<historianservername>/historian-rest-api/v1/collector/azureloglevel
Table 5. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, ErrorCode = 0 implies the operation was successful.
ErrorMessage String Yes For example, NULL.
The Install Component Details API
Using the Install Component Details API, you can view the install component details from the collector machine.
METHOD GET
URI 
https://<historianservername>/historian-rest-api/v1/
installcomponentdetails/collectorType/collectorSubType/machine
SAMPLE URI 
https://<historianservername>/historian-rest-api/v1/installcomponentdetails/2/-/abc
SAMPLE RESPONSE 
{
"ErrorCode":0,
"ErrorMessage":null,
"Data":
{
"InterfaceInstallDrive":"C",
"InterfaceDataDir":"C:\\Proficy Historian Data",
"CertPathDir":"NONE"
}
}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” 
https://<historianservername>/historian-rest-api/v1/installcomponentdetails/2/-/abc
Table 6. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, ErrorCode = 0 implies the operation was successful.
ErrorMessage String Yes For example, NULL.
The Message Compression API
Using the Message Compression API, you can enable or disable message compression.
METHOD PUT
URI 
https://<historianservername>/historian-rest-api/v1/collector/messagecompression
SAMPLE REQUEST 
{
"interfaceName":"<source server>_<type of the collector>_<destination server>",
"messageCompression":1
}
SAMPLE RESPONSE 
{
"ErrorCode":0,
"ErrorMessage":null,
}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" 
-H "Authorization: Bearer <TOKEN>” -d 
“{\"interfaceName\":\"<source server>_<type of the collector>_<destination server>\",
\"messageCompression\":1}” -X PUT 
https://<historianservername>/historian-rest-api/v1/collector/messagecompression
Table 7. Query Parameters
Parameter Description Required? Values
interface name The interface name of the collector whose message compression you want to enable or disable. Yes String 
messagecompression
 Identifies whether you want to enable or disable message compression. The valid values are 0 and 1. Yes
Table 8. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, ErrorCode = 0 implies the operation was successful.
ErrorMessage String Yes For example, NULL.
The Delete Instance API
Using the Delete Instance API, you can delete a collector instance.
METHOD PUT
URI 
https://<historianservername>/historian-rest-api/v1/collector/deleteinstance
SAMPLE REQUEST 
https://<historianservername>/historian-rest-api/v1/collector/deleteinstance
Payload
{
"interfaceName":"<source server>_<type of the collector>_<destination server>",
"deleteTags":true
}
SAMPLE RESPONSE 
{
"ErrorCode":0,
"ErrorMessage":null,
}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" 
-H "Authorization: Bearer <TOKEN>” -d “{\"interfaceName\":\"<source server>_<type of the collector>_<destination server>\",\"deleteTags\":true}” -X PUT 
https://<historianservername>/historian-rest-api/v1/collector/deleteinstance
Table 9. Query Parameters
Parameter Description Required? Values
interface name The interface name of the collector whose details you want to delete. Yes String
deleteTags Identifies whether you want to delete the tags. The valid values are true and false. Yes Boolean
Table 10. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, ErrorCode = 0 implies the operation was successful.
ErrorMessage String Yes For example, NULL.