Managing Collectors

The Start Collector API
Using the Start Collector API, you can start a collector.
METHOD PUT
URI 
https://<historianservername>/historian-rest-api/v1/collector/start
SAMPLE URI Sample URI for the service mode:
https://<historianservername>/historian-rest-api/v1/collector/start

Payload

{
  "interfaceName":"<source server>_<type of the collector>_<destination server>",
  "mode":1                            
}
Sample URI for the command line mode:
https://<historianservername>/historian-rest-api/v1/collector/start

Payload

{
  "interfaceName":"<source server>_<type of the collector>_<destination server>",
  "mode":2,
  “winUserName”:””,
  “winPassword”:””                             
}
SAMPLE RESPONSE 
{
    "ErrorCode": 0,
    "ErrorMessage": ""
    "Data": "Collector Start Initiated"
}
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>\”,
\"mode\": 1}” -X PUT https://<historianservername>/historian-rest-api/v1/collector/start

Query parameters include the Payload parameter, which is a JSON file, which contains the following properties.

Table 1. Query Parameters
Parameter Description Required? Values
interfaceName The interface name of the collector. Yes String
mode The mode to use to manage the collector. Yes
  • 1: service mode
  • 2: command-line mode
winUserName The Windows username. Yes (only if you want to use the command-line mode) String
winPassword The Windows password Yes (only if you want to use the command-line mode) String
Table 2. 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.
Data String No Indicates if the task has been initiated.
The Stop Collector API
Using the Stop Collector API, you can stop a collector.
METHOD PUT
URI 
https://<historianservername>/historian-rest-api/v1/collector/stop
SAMPLE URI 
https://<historianservername>/historian-rest-api/v1/collector/stop

Payload

{
“interfaceName":"<source server>_<type of the collector>_<destination server>"
“winUserName”:”TestAdmin”,
“winPassword”:”TestAdminPassword”                    
}
SAMPLE RESPONSE 
{
    "ErrorCode": 0,
    "ErrorMessage": null,
    "Data": "Collector Stop Initiated"
}
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>\”}” 
-X PUT https://<historianservername>/historian-rest-api/v1/collector/stop

Query parameters include the Payload parameter, which is a JSON file, which contains the following properties.

Table 3. Query Parameters
Parameter Description Required? Values
interfaceName The interface name of the collector. Yes String
winUserName The Windows username. Yes (only if you want to use the command-line mode) String
winPassword The Windows password Yes (only if you want to use the command-line mode) String
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.
Data String No Indicates if the task has been initiated.
The Restart Collector API
Using the Restart Collector API, you can restart a collector.
METHOD PUT
URI 
https://<historianservername>/historian-rest-api/v1/collector/restart
SAMPLE URI 
https://<historianservername>/historian-rest-api/v1/collector/restart

Payload
{
  “interfaceName":"<source server>_<type of the collector>_<destination server>" 
   "winUserName":"",
   "winPassword":""                   
}
SAMPLE RESPONSE 
{
    "ErrorCode": 0,
    "ErrorMessage": null,
    "Data": "Collector Restart Initiated"
}
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>\”}” 
-X PUT https://<historianservername>/historian-rest-api/v1/collector/restart

Query parameters include the Payload parameter, which is a JSON file, which contains the following properties.

Table 5. Query Parameters
Parameter Description Required? Values
interfaceName The interface name of the collector. Yes String
winUserName The Windows username. Yes String
winPassword The Windows password Yes String
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.
Data String No Indicates if the task has been initiated.
The Pause Data Collection API
Using the Pause Data Collection API, you can pause the data collection of a collector.
METHOD PUT
URI 
https://<historianservername>/historian-rest-api/v1/collector/pausecollection/{interfaceName}
SAMPLE URI 
https://<historianservername>/historian-rest-api/v1/collector/pausecollection/RSSERVER2012-02_Simulation
SAMPLE RESPONSE 
{
    "ErrorCode": 0,
    "ErrorMessage": ""
}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" 
-H "Authorization: Bearer <TOKEN>” -X PUT https://<historianservername>/historian-rest-api/v1/collector/pausecollection/RSSERVER2012-02_Simulation
Table 7. 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.
Data String No Indicates if the task has been initiated.
The Resume Data Collection API
Using the Resume Data Collection API, you can resume the data collection of a collector.
METHOD PUT
URI 
https://<historianservername>/historian-rest-api/v1/collector/resumecollection/{interfaceName}
SAMPLE URI 
https://<historianservername>/historian-rest-api/v1/collector/resumecollection/RSSERVER2012-02_Simulation
SAMPLE RESPONSE 
{
    "ErrorCode": 0,
    "ErrorMessage": ""
}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" 
-H "Authorization: Bearer <TOKEN>” -X PUT https://<historianservername>/historian-rest-api/v1/collector/resumecollection/RSSERVER2012-02_Simulation
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.
Data String No Indicates if the task has been initiated.
The Add Tag Comment API
Using the Add Tag Comment API, you can add a comment to a tag.
METHOD POST
URI 
https://<historianservername>/historian-rest-api/v1/tags/addcomment
SAMPLE URI 
https://<historianservername>/historian-rest-api/v1/tags/addcomment

Payload
{
  "tagName":"rsserver2012-02.Simulation00003",
  "comment":"Retest",
  "timeStamp":"2020-04-22T00:00:00.000Z"
}
SAMPLE RESPONSE 
{
               "ErrorCode": 0,
               "ErrorMessage": null,
               "Data": ""
              }
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \”tagName\”:\” rsserver2012-02.Simulation00003\”,\"comment\":\"Test10\",\"timeStamp\": \”2020-04-22T00:00:00.000Z \”}” -X POST https://<historianservername>:8443/historian-rest-api/v1/tags/addcomment

Query parameters include the Payload parameter, which is a JSON file, which contains the following properties.

Table 9. Query Parameters
Parameter Description Required? Values
tagName The name of the tag. Yes String
timestamp The timestamp of the comment. Yes String
comment The comment. Yes String
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.
The Get Tag Comment API
Using the Get Tag Comment API, you can view the comments added to a tag.
METHOD GET
URI 
https://<historianservername>/historian-rest-api/v1/tags/
comments/{tagNames}/{start}/{end}
SAMPLE QUERY PARAM GET URI 
https://<historianservername>/historian-rest-api/
v1/tags/comments/?tagNames=rsserver2012-02.Simulation00003; 
rsserver2012-02.Simulation00004&start=2020-04-19T00:
00:00.000Z&end=2020-04-24T00:00:00.000Z
Note: The query parameter supports multiple tags.
SAMPLE RESPONSE 
{
    "ErrorCode": 0,
    "ErrorMessage": null,
    "Data": [
        {
            "TagName": "Motor Temperature",
            "ErrorCode": 0,
            "Comments": [
                {
                    "TimeStamp": "2020-04-22T00:00:00.000Z",
                    "Comment": "Heat run test: Starting temperature"
                },
                {
                    "TimeStamp": "2020-04-22T00:00:00.000Z",
                    "Comment": "Heat run test: Temperature of the stator"
                },
                {
                    "TimeStamp": "2020-04-22T00:00:00.000Z",
                    "Comment": "Heat run test: Temperature of the rotor"
                },
                {
                    "TimeStamp": "2020-04-22T00:00:00.000Z",
                    "Comment": "Heat run test: Temperature of the shaft"
                },
                {
                    "TimeStamp": "2020-04-22T00:00:00.000Z",
                    "Comment": "Heat run test: Temperature of the endshield"
                }
            ]
        }
    ]
}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -H 
"Authorization: Bearer <TOKEN>” http://<historianservername>
/historian-rest-api/v1/tags/comments/<tagNames>/<start>/<end>

Query parameters include the Payload parameter, which is a JSON file, which contains the following properties.

Table 11. Query Parameters
Parameter Description Required? Values
tagNames

The names of the tag as a semicolon-separated list. For example: HISTWIN20161.ctag1; HISTWIN20161.ctag2

 Yes String
start The start time of the query, in ISO data format (YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime
end The end time of the query, in ISO format (YYYY-MM-DDTHH:mm:ss.SSSZ). Yes DateTime
Table 12. 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 Set Debug Mode API
Using the Set Debug Mode API, you can set the debug mode of a collector.
METHOD PUT
URI 
https://<historianservername>/historian-rest-api/v1/collector/setdebugmode
SAMPLE URI 
https://<historianservername>/historian-rest-api/v1/collector/setdebugmode

Payload
{
  “interfaceName":"<source server>_<type of the collector>_<destination server>",
  “debugMode”:255                      
}
SAMPLE RESPONSE 
{
    "ErrorCode": 0,
    "ErrorMessage": ""
}
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>\”,
\”debugMode\”}” -X PUT https://<historianservername>/historian-rest-api/v1/collector/setdebugmode

Query parameters include the Payload parameter, which is a JSON file, which contains the following properties.

Table 13. Query Parameters
Parameter Description Required? Values
interfaceName The interface name of the collector. Yes String
debugMode The debug log level for the collector. Yes
  • 0: Normal log level
  • 255: Debug log level
Table 14. 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 Buffer File Control API
Using the Buffer File Control API, you can delete or move the buffer files. It is recommended to move the buffer files to a new folder within the same drive.
Note: Moving files to a network shared drive is not supported.
METHOD PUT
URI 
https://<historianservername>/historian-rest-api/v1/collector/buffercontrol
SAMPLE URI Sample URI for moving buffer files:
https://<historianservername>/historian-rest-api/v1/collector/buffercontrol

Payload
{
  “interfaceName":"<source server>_<type of the collector>_<destination server>",
  “bufferMode”:2,
     "winUserName":"Administrator",
        "winPassword":"xxxxxxx",
  "bufferPath": "C:\\Users\\bufffiles"                      
}
Sample URI for deleting buffer files:

https://<historianservername>/historian-rest-api/v1/collector/buffercontrol

Payload
{
  “interfaceName":"<source server>_<type of the collector>_<destination server>",
  “bufferMode”:1   
 "winUserName":"Administrator",
        "winPassword":"xxxxxxx",                   
}
SAMPLE RESPONSE Sample response for moving buffer files:
{
    "ErrorCode": 0,
    "ErrorMessage": null,
    "Data": "BufferFiles Move Initiated. Collector is in the Stopped state."
}
Sample response for deleting buffer files:
{
    "ErrorCode": 0,
    "ErrorMessage": null,
    "Data": "BufferFiles Delete Initiated. Collector is in the Stopped state."
}
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>\”,
\”bufferMode \”:1,\”bufferPath \”:\” C:\\Users\\bufffiles\”}” -X PUT https://<historianservername>/historian-rest-api/v1/collector/buffercontrol

Query parameters include the Payload parameter, which is a JSON file, which contains the following properties.

Table 15. Query Parameters
Parameter Description Required? Values
interfaceName The interface name of the collector. Yes String
bufferMode Indicates whether you want to move or delete the files. Yes
  • 1: Indicates that the buffer files will be deleted.
  • 2: Indicates that the buffer files will be moved to the location specified in the bufferPath parameter.
bufferPath The directory to which you want to move the buffer files. For example: C:\\Data\\NewBufferFilesLocation or C:/Data/NewBufferPathLocation
Note: The double slash (\\) is required in the JSON format.
 Yes (only if you want to move the buffer files) String
winUserName The Windows username. Yes (only if you want to use the command-line mode) String
winPassword The Windows password Yes (only if you want to use the command-line mode) String
Table 16. 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.
Data String No Indicates if the task has been initiated (and if the collector is in the stopped state).
The Server Node Change API
Using the Server Node Change API, you can change the server node of a collector to a machine that has Historian 8.1 installed on it.
METHOD PUT
URI 
https://<historianservername>/historian-rest-api/v1/collector/historiannodechange
SAMPLE URI 
https://<historianservername>/historian-rest-api/v1/collector/historiannodechange

Payload
{
  “interfaceName":"<source server>_<type of the collector>_<destination server>",
  “mode”:2,
  "winUserName":"TestAdministrator",
  "winPassword":"TestPassword",
  "historianNode":"VMHISTWEBAUTO",
  "historianUserName":" TestAdministrator2 ",
  "historianpassword":" TestPassword2"                  
                 
}
SAMPLE RESPONSE 
{
    "ErrorCode": 0,
    "ErrorMessage": ""
}
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>\”,
\”userName  winUserName\”:\”tesrt\”,\”winpPassword \”:\”password\”,
\”historianNode \”:\”nodename\”,\” historianUserName \”:\”husername\”,
\” historianpassword \”:\”hpassword\”}” -X PUT 
https://<historianservername>/historian-rest-api/v1/collector/ historiannodechange

Query parameters include the Payload parameter, which is a JSON file, which contains the following properties.

Table 17. Query Parameters
Parameter Description Required? Values
interfaceName The interface name of the collector. Yes String
mode The mode to use to manage the collector. Yes
  • 1: service mode
  • 2: command-line mode
winUserName The Windows username. Yes (only if you want to use the command-line mode) String
winPassword The Windows password. Yes (only if you want to use the command-line mode) String
historianNode The host name of the new Historian destination machine. The destination machine must have Historian 8.1. Yes String
historianUserName The Windows username of the new Historian destination machine. Yes (only if you want to use the command-line mode) String
historianPassword The Windows password of the new Historian destination machine. Yes (only if you want to use the command-line mode) String
Table 18. 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 Version API
Using the Get Collector Version API, you can view the version number of a collector.
METHOD GET
URI 
https://<historianservername>/historian-rest-api/v1/collector/version/{interfaceName}
SAMPLE QUERY PARAM GET URL 
https://<historianservername>/historian-rest-api/v1/collector/version/?interfaceName=<source server>_<type of the collector>_<destination server>
SAMPLE RESPONSE 
{
    "ErrorCode": 0,
    "ErrorMessage": null,
    "Data": {
        "Version": "8.1.2068.0"
    }
}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” http://<historianservername>/historian-rest-api/v1/collector/version/RSSERVER2012-02_Simulation
Table 19. Query Parameters
Parameter Description Required? Values
interfaceName The interface name of the collector. Yes String
Table 20. 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.
Data String Yes Returns the version of the collector.
The Get Collector Status API
Using the Get Collector Status API, you can view the status of a collector.
METHOD GET
URI 
https://<historianservername>/historian-rest-api/v1/collector/status/{interfaceName}
SAMPLE GET URI 
https://<historianservername>/historian-rest-api/v1/collector/status/RSSERVER2012-02_Simulation
SAMPLE RESPONSE 
{
    "ErrorCode": 0,
    "ErrorMessage": "null"
    "Data":{
        "Status":"Running"
    }
}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” 
https://<historianservername>/historian-rest-api/v1/collector/status/RSSERVER2012-02_Simulation
Table 21. 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.
Data String Yes Returns the status of the collector.
The Collector Manager List API
Using the Collector Manager List API, you can view the list of collector agents machines associated with the Historian server.
METHOD GET
URI 
https://<historianservername>/historian-rest-api/v1/collectormanagerlist
SAMPLE QUERY PARAM GET URL 
https://<historianservername>/historian-rest-api/v1/collectormanagerlist
SAMPLE RESPONSE 
{
    "ErrorCode": 0,
    "ErrorMessage": null,
    "Data": [
        {
            "Name": "CollectorManager::abc",
            "IPAddress": "[::ffff :<IP address>]",
            "Status": 1,
            "ComputerName": "abc "
        },
        {
            "Name": "CollectorManager::xyz",
            "IPAddress": "[::ffff:<IP address>]",
            "Status": 1,
            "ComputerName": "xyz"
        },
        {
            "Name": "CollectorManager::abc",
            "IPAddress": "[::ffff:<IP address>]",
            "Status": 1,
            "ComputerName": "abc"
        },
        {
            "Name": "CollectorManager::123",
            "IPAddress": "[::ffff:<IP address>]",
            "Status": 1,
            "ComputerName": "123"
        }
    ]
}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” 
https://<historianservername>/historian-rest-api/v1/collectormanagerlist
Table 22. 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 Collector Mode API
Using the Collector Mode API, you can view the running mode of a collector.
METHOD GET
URI 
https://<historianservername>/historian-rest-api/v1/collector/mode/<collector interface name>
SAMPLE QUERY PARAM GET URL 
https://<historianservername>/historian-rest-api/v1/collector/mode/<collector interface name>
SAMPLE RESPONSE 
{
    "ErrorCode": 0,
    "ErrorMessage": null,
    "Data": {
        "RunningMode": "Service Mode"
    }
}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” 
https://<historianservername>/historian-rest-api/v1/collector/mode/<host name>_Simulation_<IP address>_2
Table 23. 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 Collector Details API
Using the Collector Details API, you can view the details of a collector.
METHOD GET
URI 
https://<historianservername>/historian-rest-api/v1/collector/details
SAMPLE QUERY PARAM GET URL 
https://<historianservername>/historian-rest-api/v1/collector/details
SAMPLE RESPONSE 
{
"ErrorCode":0,
"ErrorMessage":null,
"Data":
[
{
"Name":"<value>",
"ComputerName":"<value>",
"Status":"Running",
"ReportRate":0,
"MaximumEventRate":0,
"MinimumEventRate":0,
"OutOfOrderEvents":0,
"Overruns":0,
"OverrunsPercent":0,
"TotalEventsCollected":0,
"TotalEventsReported":0,
"LastDataValue":"\\\"1970-01-01T00:00:00.000Z\\\"",
"Redundency":"",
"Comments":"<username>--test2--\\\"2020-12-15T07:19:42.000Z\\\";",
"Version":"9.0.4326.0",
"CollectorCompression":0,
"TagsCount":0
}
]
}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” 
https://<historianservername>/historian-rest-api/v1/collector/details
Table 24. 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 Offline Collectors API
Using the Offline Collectors API, you can view a list of offline collectors.
METHOD GET
URI 
https://<historianservername>/historian-rest-api/v1/offlinecollectors
SAMPLE QUERY PARAM GET URL 
https://<historianservername>/historian-rest-api/v1/offlinecollectors
SAMPLE RESPONSE 
{
"ErrorCode": 0,
"ErrorMessage": null,
"Data": [
{
"Name": "DISTMACHINE1_Simulation",
"ComputerName": "DISTMACHINE1",
"Status": "Stopped"
},
{
"Name": "NPI212611749M1_Simulation",
"ComputerName": "NPI212611749M1",
"Status": "Stopped"
},
{
"Name": "NPI212611749M1_Mqtt",
"ComputerName": "NPI212611749M1",
"Status": "Stopped"
}
]
}
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” 
https://<historianservername>/historian-rest-api/v1/offlinecollectors
Table 25. 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.