Planning Status API

Context

With the Planning Status API you can fetch the status of the planning. The status indicates which steps the data you have sent to our platform went through.

Environment

For the Planning Status API we use the following URIs:

Production URL: https://planning-status-api.services.simacan.com/api/v4/attempts/{uuid}

Staging URL: https://planning-status-api-stg.services.simacan.com/api/v4/attempts/{uuid}

Schema

The planning-status-api is a read-only API and thus only supports GET requests.

The exact schema can be found on our OpenAPI specification.

Example

Getting the status

In a previous step, you delivered your data to our platform and if everything went fine, you should have obtained an UUID. In our previous example we got 01b44637-1395-4591-a0ec-14108022b707

Request it

Keep in mind that this request only works, if you have a bearer token. Include this in the header. In this example we request the staging environment.

Copy

Copied

curl -H "Authorization: Bearer eyXXX" -X GET -i https://planning-status-api-stg.services.simacan.com/api/v4/attempts/01b44637-1395-4591-a0ec-14108022b707

Response

If everything went fine, you should receive an HTTP status code 200 OK and a body which looks like this

Copy

Copied

{
  "importAttempt" : {
    "id" : "39e8d454-87b4-427d-a4f3-c50ed2677644",
    "name" : "peterson/2020-09-02T12:26:47.585271Z.json",
    "planningCreationTime" : "2020-09-02T12:26:47.705Z",
    "shipper" : "peterson",
    "triggerType" : "Automatic",
    "status" : "ShouldStart",
    "file" : {
      "fileName" : "peterson/2020-09-02T12:26:47.585271Z.json",
      "directory" : "simacan-planning-data"
    },
    "tags" : {
      "mimeType" : "application/json",
      "version" : 1,
      "schema" : "json",
      "source" : "planning-receive-api"
    }
  },
  "steps" : [ {
    "id" : "90e66fcb-4be0-4d33-9ee6-60fe999904e5",
    "endTime" : "2020-09-02T12:26:47.708852Z",
    "status" : "ShouldStart",
    "errors" : [ ],
    "name" : "Starting peterson/2020-09-02T12:26:47.585271Z.json",
    "processingStepType" : "Starting"
  } ],
  "items" : [ ]
}

When consuming this response, check for the status. The value for status can be ShouldStart, Running, Succeeded or Failed. In this case ShouldStart would mean that the specific file has been received by Simacan, but the processing of it, should still be starting. When requesting a bit later, you should see more steps, where you can analyze all steps taken on your planning file. Ultimately you are looking for the status Succeeded

Failed response

Of course not all files will be processed properly. To give you an idea on how a failed attempt will look like, we've sent a malformed JSON file to the Planning Receive API. What follows is a response, for when processing has failed.

Copy

Copied

{
  "importAttempt" : {
    "id" : "39e8d454-87b4-427d-a4f3-c50ed2677644",
    "name" : "peterson/2020-09-02T12:26:47.585271Z.json",
    "planningCreationTime" : "2020-09-02T12:26:47.705Z",
    "shipper" : "peterson",
    "triggerType" : "Automatic",
    "status" : "Failed",
    "file" : {
      "fileName" : "peterson/2020-09-02T12:26:47.585271Z.json",
      "directory" : "simacan-planning-data"
    },
    "tags" : {
      "mimeType" : "application/json",
      "version" : 1,
      "schema" : "json",
      "source" : "planning-receive-api"
    }
  },
  "steps" : [ {
    "id" : "9a00f442-2806-4e15-adec-de005ec7240f",
    "endTime" : "2020-09-02T12:40:05.553Z",
    "status" : "Failed",
    "errors" : [ {
      "id" : "15b245b0-6a47-44ae-8bf2-591f430cd368",
      "message" : "(/_id,List(JsonValidationError(List(error.path.missing),WrappedArray())))"
    }, {
      "id" : "0cf9c82d-aecd-428e-9c0d-51dbab47f47b",
      "message" : "(/id,List(JsonValidationError(List(error.path.missing),WrappedArray())))"
    }, {
      "id" : "9a2066e4-01b4-4553-9416-a5600b43f761",
      "message" : "(/timestamp,List(JsonValidationError(List(error.path.missing),WrappedArray())))"
    }, {
      "id" : "daedc47f-378d-4db0-910b-672ff0e4899d",
      "message" : "(/tripid,List(JsonValidationError(List(error.path.missing),WrappedArray())))"
    }, {
      "id" : "1e020fe8-399d-4311-a64b-1f64473624ea",
      "message" : "(/planning,List(JsonValidationError(List(error.path.missing),WrappedArray())))"
    }, {
      "id" : "db329e8a-e019-4964-833c-5e09ef2fc307",
      "message" : "(/clientname,List(JsonValidationError(List(error.path.missing),WrappedArray())))"
    } ],
    "name" : "Converting JSON to domain",
    "processingStepType" : "ConvertToDomain"
  }, {
    "id" : "a909d69d-a80b-4364-9bc1-33442803a541",
    "endTime" : "2020-09-02T12:40:05.541Z",
    "status" : "Running",
    "errors" : [ ],
    "name" : "Parsing data as JSON",
    "processingStepType" : "ConvertToDomain"
  }, {
    "id" : "d529051d-c3de-4b2d-9b3b-d8d81f77551c",
    "endTime" : "2020-09-02T12:40:05.537Z",
    "status" : "Running",
    "errors" : [ ],
    "name" : "Retrieve data from S3",
    "processingStepType" : "RetrieveData"
  }, {
    "id" : "9005140d-dfea-4554-8018-ef57c29edd33",
    "endTime" : "2020-09-02T12:39:55.475022Z",
    "status" : "ShouldStart",
    "errors" : [ ],
    "name" : "Starting peterson/2020-09-02T12:26:47.585271Z.json",
    "processingStepType" : "Starting"
  }, {
    "id" : "90e66fcb-4be0-4d33-9ee6-60fe999904e5",
    "endTime" : "2020-09-02T12:26:47.708852Z",
    "status" : "ShouldStart",
    "errors" : [ ],
    "name" : "Starting peterson/2020-09-02T12:26:47.585271Z.json",
    "processingStepType" : "Starting"
  } ],
  "items" : [ ]
}

Responses

Key	Description
200	Ok
401	Unauthorized Whenever you will get a 401 status, you have either provided the wrong credentials or none at all. Check if you bearer token has not expired
403	Forbidden You will receive this status, when you successfully supplied credentials, but your username does not have the necessary permissions for the resource
404	Not Found The requested planning was not found