The GoPlant API uses Basic Authentication. You will need to supply an 'Authorization' header to access all the endpoints in this API. Please contact your GoPlant administrator for a Username and Password to include in your 'Authorization' header.
Below are a list of available endpoints.
The 'API Test Get' and 'API Test Post' endpoints are for you to test your basic authentication header.

GoPlant uses standard versioning. Our current API version is 2.x. When calling the API, you will get the latest 2.x. This is because we consider any 2.x a 'non breaking' api change. For example, we may add a new field to the response object.

In the future, if we make a breaking change, we will increase the major version number to indicate this and you will need to include a version number in your API call.

To use an api other than the latest 2.x, you will need to include the version in the json body. Below is an example.

    {
      "RowStart": 0,
      "RowCount": 1000,
      "ReturnType": "json",
      "ResponseID": 500,
      "StartDatetimeUTC":"5/1/2018 15:00",
      "EndDatetimeUTC": "6/1/2018 15:00",
      "TagSourceCodeName": "DYNAMO",
      "TagDataValue": "",
      "EndpointVersion": 1.1
    }                    

If you want to use an older version of the API, just include the old version number in the body of your API call. ex. "EndpointVersion": 1.0
If you pass an invalid version number, you will get this type of response.

     {
      "message": "ResponsesBetweenResponseDate Error: Invalid Version Requested [2.9].   at ...
     }

Any endpoint that returns an array allows for pagination. This is done by setting the RowStart and RowCount parameters. Below is an example of how to pull all records after ResponseID 1234

• First Call: Set ResponseID = 1234, RowStart = 0, RowCount = 500
• Check if RowsReturned is greater than 0. If it is, increment the RowStart and call again.
• Second Call: Set ResponseID = 1234, RowStart = 500, RowCount = 500 - Note: Notice the ResponseID does not change.
• Check if RowsReturned is greater than 0. If it is, increment the RowStart and call again.
• Third Call: Set ResponseID = 1234, RowStart = 1000, RowCount = 500
• As soon as RowsReturned is equal to zero, you can stop.

When paging thru an endpoint that uses start and/or end date, do not change the start and/or end date. Only increment the RowStart by your RowCount. Note: The maximum number of records the API will return at any one time is 1000. Setting RowCount to a number above 1000 will only return a maximum of 1000 records.

ReturnType: XML

• You can now set the ReturnType = "XML"

    {
        "RowStart": 0,
        "RowCount": 10,
        "ReturnType": "xml",
        "ResponseID": 419312,
        "EndpointVersion": null,
        "StorageGroupIDs": "374",
        "IncludeStorageGroupDescendants": true
    }
                        

StorageGroupIDs

• A comma delimited list of storage Groups IDs. This will only return records that match the Round Storage Group ID.
• ex. "374", "374,320"
• Setting this property to null or empty string will return all records without filtering.
• Note: You can use the "/api/svc/Historian/GetStorageGroups" endpoint to get a list of Storage Group IDs.

IncludeStorageGroupDescendants

• Optional: When true, results will include all storage group descendants from "StorageGroupIDs".
• Default is false. Note: You do not need to include this property if you are not enabling it.

    {
      "RowStart": 0,
      "RowCount": 1000,
      "ReturnType": "json",
      "ResponseID": 401234,
      "EndpointVersion": null,
      "StorageGroupIDs": "374",
      "IncludeStorageGroupDescendants": true
    }
OR
    {
      "RowStart": 0,
      "RowCount": 1000,
      "ReturnType": "json",
      "ResponseID": 401234,
      "EndpointVersion": null,
      "StorageGroupIDs": "374,320",
      "IncludeStorageGroupDescendants": false
    }

For any of the endpoints that require a start and/or end date or, you can now pass a storage group date / time with "StartDatetimeSG" and "EndDatetimeSG" instead of "StartDatetimeUTC" and "EndDatetimeUTC". Include "StorageGroupID" to tell the system which storage group date / time you are sending. A LastUpdatedSG parameter is available for API v2.x.

Example:

    {
      "ReturnType": "json",
      "StartDatetimeSG":"5/1/1010 15:00",
      "EndDatetimeSG": "6/1/2018 15:00",
      "StorageGroupID": 80
    }

When you include "StorageGroupID", the "StartDatetimeSG" date / time will fill in the "StartDatetimeUTC" based on that storage group id's time zone. The same goes for the "EndDatetimeSG".

Partial example status response with StorageGroupID included:

 "status": {
        "HTTPStatusCode": 200,
        "HTTPStatus": "OK",
        "ExternalRequest": {
            "StartDatetimeUTC": "1010-05-01T10:00:00",
            "StartDatetimeSG": "1010-05-01T15:00:00",
            "EndDatetimeUTC": "2018-06-01T10:00:00",
            "EndDatetimeSG": "2018-06-01T15:00:00",
            "StorageGroupID": 80
        }
    }

Note: All endpoints still return dates as UTC.

If you do not include the "StorageGroupID", the "StartDatetimeSG" date / time will fill in the "StartDateTimeUTC" based on storage group 1's time zone. The same goes for the "EndDatetimeSG".

Partial example status response without a StorageGroupID included:

"status": {
        "HTTPStatusCode": 200,
        "HTTPStatus": "OK",
        "ExternalRequest": {
            "StartDatetimeUTC": "1010-05-01T10:00:00",
            "StartDatetimeSG": "1010-05-01T15:00:00",
            "EndDatetimeUTC": "2018-06-01T10:00:00",
            "EndDatetimeSG": "2018-06-01T15:00:00",
            "StorageGroupID": null
        }
    }

A single TagDataValue can now be selected for any External Tag Source Code API request.

There are two types of authentication, Tag Source and GoPlant. The 'Authentication Type' for each endpoint is outlined in this document.

Tag Source API Access

To access a Tag Source API, you must supply a basic authorization header for that Tag Source.
A basic authorization header is comprised of a Tag Source name, ex 'DYNAMO' and password.
You can get the password for each Tag Source from your GoPlant administrator.
The Tag Source login is tied to the Tag Source endpoints.
In order to pull Tag Source data for 'DYNAMO', you must use the 'DYNAMO' login and password in the basic authentication header.
For example, when calling an endpoint with the 'DYNAMO' credentials, you can only pass 'DYNAMO' as the 'TagSourceCodeName'.

If you try to pass anything other than 'DYNAMO' while logged in with the 'DYNAMO' credentials, you will get a message like this.

{"message": "UserName 'DYNAMO' cannot access TagSourceCodeName 'HACHWIMS' from endpoint 'HistorianBetweenDateTimes'"}

GoPlant API Access

To access a GoPlant API, you must supply a basic authorization header for GoPlant API Access.
GoPlant credentials can be used for any API that is has an 'Authentication Type' of 'GoPlant'.
You can get the password for GoPlant API access from your GoPlant administrator.
If you try to access a Tag Source endpoint with GoPlant credentials, you will get a message like this.

{"message": "UserName 'XXXXXX' cannot access TagSourceCodeName 'HACHWIMS' from endpoint 'HistorianBetweenDateTimes'   at ...}

Contact your GoPlant administrator for the login and passwords for the endpoints you want to call.