GoPlant API: Get Responses Last Updated after a specified UTC date
  • Description / Endpoint Version: 1.0
    This endpoint will return a list of responses last updated after a specified UTC date. This endpoint was designed to return information that would be useful to most external services.
  • Change Log:
    • 1.0: Initial build.
    • API 2.0: For any of the endpoints that require a start and end date / time, 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.

  • Authentication Type:
    GoPlant
  • Accepts:
    URL: http://demo.goplant.mobi/api/svc/Historian/ResponsesAfterResponseLastUpdated
    Method: Post
    Authorization: Basic
    • Username: [Contact The GoPlant Administrator]
    • Password: [Contact The GoPlant Administrator]
    Headers:
    • Content-Type: application/json
    Body:
    • RowStart and RowCount are used for paging thru large record sets. The maximum number of rows that can be returned at any one time is 1000.
    • RowStart: This is a zero based row number of the row to start with.
    • RowCount: The number of rows to return starting from the RowStart.
    • ReturnType: How you would like to receive the response. JSON and XML are supported.
    • LastUpdatedUTC: Will return responses updated on or after this UTC date / time.
    • LastUpdatedSG: Will return responses updated on or after this Storage Group date / time.
    • Note: This endpoint includes any responses there were updated on or after the given date / time.
    • Note: For endpoints that allow a date parameter, you can now use "StartDatetimeSG" or "EndDatetimeSG" to pass storage group timestamps. See the home page for more details.
    Accept Body Example:
    {
    	"RowStart": 0,
    	"RowCount": 100,
    	"ReturnType": "json",
    	"LastUpdatedUTC": "2018-07-02T15:50:00",
    	"LastUpdatedSG": null,
    	"EndpointVersion": null (null = latest 1.x)
    }
    
  • Response:
    Status: 200
    Type: JSON
    Body:
    • Status Object: Holds status information about your request.
      • HTTPStatusCode: HTTP Status ID of the request.
      • HTTPStatus: HTTP Status string representation. EX. 'OK'
      • RowStart: The zero based first row that was returned.
      • RowsReturned: The actual number of rows returned in the Data object.
      • LastIdReturned: The Last Response ID Returned by this request. This is useful for the next call when you want new records.
      • RequestBegin: The UTC timestamp API received the request.
      • StopWatch: The elapsed time the API call.
      • APIversion: GoPlant internal API version.
      • EndpointVersionReturned: The endpoint version that was returned based on the request. ex. If no endpoint version was requested, this will show the latest 1.x version.
      • ExternalRequest: The request object that was passed. Includes the endpoint version that was requested and the actual endpoint version that was returned.
        • "EndpointVersion": null
        • "EndpointVersionReturned": 1.1
    • Data Object: Holds the actual data that you are requesting.
      • responseID: Unique Response ID
      • responseLabel: The label of the step associated with this response.
      • responseValue: The string value of the response.
      • responseDate: The UTC date / timestamp the questions step was answered.
      • responseColorcode: Color code of the response, if any.
      • responseType: The type of step the response is associated with.
      • operatorID: Internal ID of the user that created this response.
      • operatorFirstName: Users first name.
      • operatorLastName: Users second name.
      • stepID: Internal unique id of the step associated with this response.
      • stepRequired: Was the step required.
      • stepPage: Page number.
      • stepLabel: Step Name.
      • stepComments: Step Description.
      • stepWasVisible: Was the step visible at the time of the response.
      • formName: Form name.
      • formSGName: Storage Group path.
      • formStartDate: UTC date / timestamp when the form was started.
      • formEndDate: UTC date / timestamp when the form was completed.
      • elementLabel: Asset name / Form name.
      • assetTag: Asset name. May be null.
      • assetDescription: Asset description. May be null.
      • assetStatus: Status of the asset at the time of the response. May be null.
      • roundName: Name of the round.
      • roundDesc: Description of the round
      • roundStartDate: UTC date / timestamp when the round was started.
      • roundEndDate: UTC date / timestamp when the round was completed.
      • roundVariantName: Name of the variant.
      • taskName: Name of the task. May be null.
      • taskDescription: May be null.
      • taskEventStatus: Status of the task. OnTime, Late etc. May be null.
      • taskAssignmentStartline: UTC date / timestamp of the start date. May be null.
      • taskAssignmentDeadline: UTC date / timestamp of the end date. May be null.
      • taskAssignmentExpiration: UTC date / timestamp of the expiration. May be null.
      • taskAssignmentCompletedDate: UTC date / timestamp when completed. May be null.
      • taskAssignmentDeleted: Was the task deleted? May be null.
      • taskAssignmentStatus: Completed May be null.
      • timeZone: Timezone the response was completed in.
      • completedFormID: Use this id to group responses by a completed form.
      • completedRoundID: Use this id to group responses by a completed round.
      • completedRoundElementID: Use this id to group responses by a round / element combination
      • taskEventID: Use this id to group responses by a task event. Note: will be 'null' if response was not part of a task.
      • (v1.0) lastUpdated: Response Last Updated UTC date / timestamp.
      • (v1.0) roundStorageGroupID: Storage Group id of this records round.
      • (v1.1) roundStorageGroupName: Storage Group name of this records round.
    Response Example:
    {
        "status": {
            "HTTPStatusCode": 200,
            "HTTPStatus": "OK",
            "RowStart": 3,
            "RowsReturned": 3,
            "LastIdReturned": 270384,
            "RequestBegin": "2019-05-07T20:12:13.8743864Z",
            "StopWatch": {
                "IsRunning": true,
                "Elapsed": "00:00:00.0056833",
                "ElapsedMilliseconds": 6,
                "ElapsedTicks": 63232
            },
            "APIversion": "5.13.0.0",
            "EndpointVersionReturned": 1,
            "ExternalRequest": {
                "RowStart": 3,
                "RowCount": 3,
                "LastUpdatedUTC": "2019-10-02T20:50:00Z",
                "LastUpdatedSG": "2019-10-02T15:50:00",
                "TagSourceCodeName": "",
                "ReturnType": 1,
                "EndpointVersion": null,
                "EndpointVersionReturned": 1
            }
        },
        "data": [
            {
                "responseID": 270382,
                "responseLabel": "Step - 5 - List - Checkbox",
                "responseValue": " ",
                "responseDate": "2018-07-02T15:58:26",
                "responseColorcode": "       ",
                "responseType": "List",
                "operatorID": 299,
                "operatorFirstName": "Kevin",
                "operatorLastName": "Cornelison",
                "stepID": 32621,
                "stepRequired": false,
                "stepPage": 1,
                "stepLabel": "Step - 5 - List - Checkbox",
                "stepComments": "",
                "stepWasVisible": true,
                "formName": "form - All Steps",
                "formSGName": "KevinSubGroup Değeri",
                "formStartDate": "2018-07-02T15:58:04",
                "formEndDate": "2018-07-02T15:58:26",
                "elementLabel": "form - All Steps",
                "assetTag": null,
                "assetDescription": null,
                "assetStatus": null,
                "roundName": "Round All Steps",
                "roundDesc": "",
                "roundStartDate": "2018-07-02T15:58:02",
                "roundEndDate": "2018-07-02T15:58:46",
                "roundVariantName": "AllSteps",
                "taskName": "",
                "taskDescription": "",
                "taskEventStatus": "Void",
                "taskAssignmentStartline": null,
                "taskAssignmentDeadline": null,
                "taskAssignmentExpiration": null,
                "taskAssignmentCompletedDate": null,
                "taskAssignmentDeleted": false,
                "taskAssignmentStatus": "",
                "timeZone": "America/Chicago",
                "completedFormID": 30177,
                "completedRoundID": 8445,
                "completedRoundElementID": 50521,
                "taskEventID": null,
                "lastUpdated": "2018-07-02T15:58:26",
                "roundStorageGroupID": 425,
                "roundStorageGroupName:"TXRG1"
            },
            {
                "responseID": 270383,
                "responseLabel": "Step - 6 - List - Dropdown",
                "responseValue": " ",
                "responseDate": "2018-07-02T15:58:26",
                "responseColorcode": "       ",
                "responseType": "List",
                "operatorID": 299,
                "operatorFirstName": "Kevin",
                "operatorLastName": "Cornelison",
                "stepID": 32622,
                "stepRequired": false,
                "stepPage": 1,
                "stepLabel": "Step - 6 - List - Dropdown",
                "stepComments": "",
                "stepWasVisible": true,
                "formName": "form - All Steps",
                "formSGName": "KevinSubGroup Değeri",
                "formStartDate": "2018-07-02T15:58:04",
                "formEndDate": "2018-07-02T15:58:26",
                "elementLabel": "form - All Steps",
                "assetTag": null,
                "assetDescription": null,
                "assetStatus": null,
                "roundName": "Round All Steps",
                "roundDesc": "",
                "roundStartDate": "2018-07-02T15:58:02",
                "roundEndDate": "2018-07-02T15:58:46",
                "roundVariantName": "AllSteps",
                "taskName": "",
                "taskDescription": "",
                "taskEventStatus": "Void",
                "taskAssignmentStartline": null,
                "taskAssignmentDeadline": null,
                "taskAssignmentExpiration": null,
                "taskAssignmentCompletedDate": null,
                "taskAssignmentDeleted": false,
                "taskAssignmentStatus": "",
                "timeZone": "America/Chicago",
                "completedFormID": 30177,
                "completedRoundID": 8445,
                "completedRoundElementID": 50521,
                "taskEventID": null,
                "lastUpdated": "2018-07-02T15:58:26",
                "roundStorageGroupID": 425,
                "roundStorageGroupName:"TXRG1"
            },
            {
                "responseID": 270384,
                "responseLabel": "Step - 7 - Yes / No",
                "responseValue": " ",
                "responseDate": "2018-07-02T15:58:26",
                "responseColorcode": "       ",
                "responseType": "Yes/No",
                "operatorID": 299,
                "operatorFirstName": "Kevin",
                "operatorLastName": "Cornelison",
                "stepID": 32623,
                "stepRequired": false,
                "stepPage": 1,
                "stepLabel": "Step - 7 - Yes / No",
                "stepComments": "",
                "stepWasVisible": true,
                "formName": "form - All Steps",
                "formSGName": "KevinSubGroup Değeri",
                "formStartDate": "2018-07-02T15:58:04",
                "formEndDate": "2018-07-02T15:58:26",
                "elementLabel": "form - All Steps",
                "assetTag": null,
                "assetDescription": null,
                "assetStatus": null,
                "roundName": "Round All Steps",
                "roundDesc": "",
                "roundStartDate": "2018-07-02T15:58:02",
                "roundEndDate": "2018-07-02T15:58:46",
                "roundVariantName": "AllSteps",
                "taskName": "",
                "taskDescription": "",
                "taskEventStatus": "Void",
                "taskAssignmentStartline": null,
                "taskAssignmentDeadline": null,
                "taskAssignmentExpiration": null,
                "taskAssignmentCompletedDate": null,
                "taskAssignmentDeleted": false,
                "taskAssignmentStatus": "",
                "timeZone": "America/Chicago",
                "completedFormID": 30177,
                "completedRoundID": 8445,
                "completedRoundElementID": 50521,
                "taskEventID": null,
                "lastUpdated": "2018-07-02T15:58:26",
                "roundStorageGroupID": 425,
                "roundStorageGroupName:"TXRG1"
            }
        ]
    }
    
  • On Failure:
    • If you do not provide a basic authorization header you will get an empty body with a status of 401 Unauthorized.
    • If your basic authorization header Username or Password is incorrect, you will get this message with a status of 401 Unauthorized.
      {"message": "Unauthorized API access"}
    • If you do not supply a json object in your body, you will get this message with a status of 500 Internal Server Error.
      {"message": "Missing body in post."}
    • If you pass a RowStart less than zero, you will get this message with a status of 500 Internal Server Error.
      {"message": "RowStart cannot be less than 0."}
    • If you pass a RowCount less than zero, you will get this message with a status of 500 Internal Server Error.
      {"message": "RowCount cannot be less than 0."}
    • If TagSourceCodeName is required and you do not pass it, you will get this message with a status of 500 Internal Server Error.
      {"message": "You must pass a source code name."}
    • If a Start, End or last update date / time is required but not passed, you will get this message with a status of 500 Internal Server Error.
      {"message": "StartDatetimeUTC cannot be null"}
      OR
      {"message": "EndDatetimeUTC cannot be null"}
      OR
      {"message": "LastUpdateUTC cannot be null"}
    • If you pass an invalid version number, you will get this type of response.
      {"message": "ResponsesBetweenResponseDate Error: Invalid Version Requested [1.1].   at ...
  • curl Example:
                            
    curl -X POST \
      http://localhost:9080/api/svc/Historian/ResponsesAfterResponseLastUpdated \
      -H 'Authorization: Basic TXlUYWdTb3VyY2UxOjhFRTMxNTFCMUQwODQzOUZCMEQyQjhFQ0MzMzNBNkZF' \
      -H 'Cache-Control: no-cache' \
      -H 'Content-Type: application/json' \
      -d '{
    	"RowStart": 0,
    	"RowCount": 2,
    	"ReturnType": "json",
    	"LastUpdatedUTC": "2019-10-02T15:50:00"
    }'
                        
  • C# Example:
                            
    var client = new RestClient("http://localhost:9080/api/svc/Historian/ResponsesAfterResponseLastUpdated");
    var request = new RestRequest(Method.POST);
    request.AddHeader("Cache-Control", "no-cache");
    request.AddHeader("Authorization", "Basic TXlUYWdTb3VyY2UxOjhFRTMxNTFCMUQwODQzOUZCMEQyQjhFQ0MzMzNBNkZF");
    request.AddHeader("Content-Type", "application/json");
    request.AddParameter("undefined", "{\n\t\"RowStart\": 0,\n\t\"RowCount\": 2,\n\t\"ReturnType\": \"json\",\n\t\"LastUpdatedUTC\":\"2018-07-02T15:50:00\", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);
                        
  • Jquery Example:
                            
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "http://localhost:9080/api/svc/Historian/ResponsesAfterResponseLastUpdated",
      "method": "POST",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Basic R29QbGFudEFQSUFjY2VzczpERVZMLlRFU1RERVZFTE9QTUVOVEtFWQ==",
        "cache-control": "no-cache"
      },
      "processData": false,
      "data": "{\n\t\"RowStart\": 3,\n\t\"RowCount\": 3,\n\t\"ReturnType\": \"json\",\n\t\"LastUpdatedUTC\":\"2018-07-02T15:50:00\",\n\t\"EndpointVersion\": null\n}"
    }
    
    $.ajax(settings).done(function (response) {
      console.log(response);
    });