Floor plans

Floor plans are the specifications of a construction project. It is important that workers have access the most recent floor plan data. Hence keeping the floor plan versions up-to-date is an important part of managing the information sharing during the project.

The Congrid system stores the following information about floor plans:

  • The metadata of the floor plan
  • The actual image data of the floor plan

The meta data of the floor plan contains different attributes that help both the end-user and the system to better understand the actual floor plan image data. The image data on the other hand is only the raw image of the floor plan.

Floor plan types

Each floor plan has a type which is identified by the floorPlanTypeId property in the floor plan meta data. The available floor plan types can be retrieved from the global end-point.

https://api.congrid.com/v1/floorPlanTypes

For example:

curl -X GET \
  -H "Congrid-API-Token: YOUR-API-TOKEN" \
  -H "Content-Type: application/json" \
   "https://api.congrid.com/v1/floorPlanTypes"

Adding floor plans to the system

Adding new floor plans to the system consists of multiple steps. These steps are:

  • Add new floor plan meta data (POST)
  • Upload the floor plan raw image data (PUT)
  • Inform the system that the upload is completed (POST)
Add floor plan meta data

Lets start by adding the meta data. We will use the floorPlanTypeId 42b3c6feaa78c1 which indicates that the floor plan is used during construction. This is a good default value if you are unsure with what kind of floor plan you are dealing with.

curl
JavaScript
curl -X POST -H "Content-Type: application/json" \
  -H "Congrid-API-Token: YOUR-API-TOKEN" -d '{
   "name": "Floorplan 1",
   "floorPlanTypeId": "42b3c6feaa78c1",
   "description": "This is the base floorplan"
}' "https://api.congrid.com/v1/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorPlans"
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.congrid.com/v1/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorPlans',
  headers: 
   { 'congrid-api-token': 'YOUR-API-TOKEN',
     'content-type': 'application/json' },
  body: 
   { name: 'Floorplan 1',
     floorPlanTypeId: '42b3c6feaa78c1',
     description: 'This is the base floorplan' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The response:

{
  "description": "This is the base floorplan",
  "floorPlanTypeId": "42b3c6feaa78c1",
  "name": "Floorplan 1",
  "slug": "caa3ee71318e4214a73f72292fbe1db6",
  "id": "FhA5NLWneNuzgjhJfMcxVDGJzVLaulhH",
  "projectId": "PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ",
  "uploadUrl": "https://s3-eu-west-1.amazonaws.com/congrid/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorplans/ssoUmAHPhOAluMdLGYQmmYn1wpswYytr.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=172800&X-Amz-Credential=X&X-Amz-SignedHeaders=host&X-Amz-Date=1&X-Amz-Signature=b"
}

Note these three properties from the response: id, slug, uploadUrl.

The id property is used when you want to modify or remove this version of the floor plan. It is also used when mapping floor plans with targets.

The slug property ties different versions of a floor plan together. It is useful when you want to update the raw image data of a floor plan.

The uploadUrl property specifies the URL to which we should upload our raw image data of the floor plan.

Upload raw image data

Lets upload the raw image data of the floor plan to Congrid. The upload is a multipart/form-data upload with the HTTP method PUT. The form data file field should be set with the path to the actual data file.

Request:

curl
JavaScript
curl -X PUT \ 
  -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" \ 
  -F "file=@/tmp/1.krs.pdf" \
  "https://s3-eu-west-1.amazonaws.com/congrid/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorplans/ssoUmAHPhOAluMdLGYQmmYn1wpswYytr.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=172800&X-Amz-Credential=X&X-Amz-SignedHeaders=host&X-Amz-Date=1&X-Amz-Signature=b"
var fs = require("fs");
var request = require("request");

var options = { method: 'PUT',
  url: 'https://s3-eu-west-1.amazonaws.com/congrid/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorplans/FhA5NLWneNuzgjhJfMcxVDGJzVLaulhH.pdf',
  qs: 
   { 'X-Amz-Algorithm': 'AWS4-HMAC-SHA256',
     'X-Amz-Expires': '172800',
     'X-Amz-Credential': 'XXXXX',
     'X-Amz-SignedHeaders': 'host',
     'X-Amz-Date': '20170123T191654Z',
     'X-Amz-Signature': 'abc123abc123' },
  headers: 
   { 'cache-control': 'no-cache',
     'content-type': 'multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' },
  formData: 
   { file: 
      { value: 'fs.createReadStream("/tmp/1.krs.pdf")',
        options: 
         { filename: '/tmp/1.krs.pdf',
           contentType: null } } } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response:

The response is an empty response with HTTP Status Code 200
Inform that a floor plan has been uploaded

After the raw image data of the floor plan has been uploaded to the system the last step is to inform that the upload was successful. This is performed with a simple empty POST to the following URL where the {{projectId}} is the project id of our project and the {{floorPlanId}} is the id property returned with the floor plan meta data POST.

https://api.congrid.com/v1/projects/{{projectId}}/floorPlans/{{floorPlanId}}/uploaded

Request:

curl
JavaScript
curl -X POST \ 
  -H "Content-Type: application/json" \ 
  -H "Congrid-API-Token: YOUR-API-KEY" \ 
  -d '' "https://api.congrid.com/v1/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorPlans/FhA5NLWneNuzgjhJfMcxVDGJzVLaulhH/uploaded"
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.congrid.com/v1/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorPlans/FhA5NLWneNuzgjhJfMcxVDGJzVLaulhH/uploaded',
  headers: 
   { 'cache-control': 'no-cache',
     'congrid-api-token': '1191c0331d5d9fe0aa02a0507046f08ed1469b71',
     'content-type': 'application/json' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response:

The response is an empty response with HTTP Status Code 200

No the floor plan is completely uploaded to the system and is ready for use.

Updating floor plan version (image data)

To update the version of a floor plan we will use the slug property from the previous step and POST a new floor plan with that same slug. This is an indicator for the backend system that we actually want to update the version of an existing floor plan and not create a completely new floor plan instance.

Essentially we are going to perform the same three steps as above but to keep it short we will only show the first step which is the one that actually differs. The three steps to perform were:

  • Add new floor plan meta data (POST)
  • Upload the floor plan raw image data (PUT)
  • Inform the system that the upload is completed (POST)
Add floor plan meta data

Now in the previous example we did not POST the slug property as part of the object. However as we want to update the version of an existing floor plan we will now need to fill in the slug property as well.

curl
JavaScript
curl -X POST -H "Content-Type: application/json" -H "Congrid-API-Token: YOUR-API-TOKEN" \
  -d '{
   "name": "Floorplan 1 - version 2",
   "floorPlanTypeId": "42b3c6feaa78c1",
   "description": "This is the base floorplan version 2",
   "slug": "caa3ee71318e4214a73f72292fbe1db6"   
  }' "https://api.congrid.com/v1/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorPlans"
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.congrid.com/v1/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorPlans',
  headers: 
   { 'congrid-api-token': 'YOUR-API-TOKEN',
     'content-type': 'application/json' },
  body: 
   { name: 'Floorplan 1 - version 2',
     floorPlanTypeId: '42b3c6feaa78c1',
     description: 'This is the base floorplan version 2',
     slug: 'caa3ee71318e4214a73f72292fbe1db6' },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The response:

{
  "description": "This is the base floorplan version 2",
  "floorPlanTypeId": "42b3c6feaa78c1",
  "name": "Floorplan 1 - version 2",
  "slug": "caa3ee71318e4214a73f72292fbe1db6",
  "id": "cdGe1mPC8r2lYLYp1KVyQg1GECnP2uvj",
  "projectId": "PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ",
  "uploadUrl": "https://s3-eu-west-1.amazonaws.com/congrid/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorplans/cdGe1mPC8r2lYLYp1KVyQg1GECnP2uvj.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=172800&X-Amz-Credential=XXX&X-Amz-SignedHeaders=host&X-Amz-Date=20170123T192923Z&X-Amz-Signature=abc123abc123"
  }  

After this one would follow the to next steps of uploading the floor plan data to the uploadUrl returned by the POST and then informing the system once the upload is complete.

Fetching existing floor plans

Now we have added two floor plans for the project.

Request:

curl
JavaScript
curl -X GET -H "Congrid-API-Token: YOUR-API-TOKEN" -H "Content-Type: application/json" \ 
"https://api.congrid.com/v1/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorPlans"
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.congrid.com/v1/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorPlans',
  headers: 
   { 'content-type': 'application/json',
     'congrid-api-token': 'YOUR-API-TOKEN' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response:

{
  "count": 2,
  "pageSize": 100,
  "results": [
    {
      "description": "This is the base floorplan",
      "floorPlanTypeId": "42b3c6feaa78c1",
      "name": "Floorplan 1",
      "slug": "caa3ee71318e4214a73f72292fbe1db6",
      "id": "FhA5NLWneNuzgjhJfMcxVDGJzVLaulhH",
      "nextVersionId": "cdGe1mPC8r2lYLYp1KVyQg1GECnP2uvj",
      "projectId": "PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ"
    },
    {
      "description": "This is the base floorplan version 2",
      "floorPlanTypeId": "42b3c6feaa78c1",
      "name": "Floorplan 1 - version 2",
      "slug": "caa3ee71318e4214a73f72292fbe1db6",
      "id": "cdGe1mPC8r2lYLYp1KVyQg1GECnP2uvj",
      "projectId": "PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ"
    }
  ]
}

In the response you can see both of the floor plans we have added to the system. Note that the first floor plan we added now has the nextVersionId property set and it points to the id of the floor plan we added next. This is because the floor plans share the same slug and are actually two different versions of the floor plan.


NOTE

If a floor plan does not have a nextVersionId property it means that the floor plan instance is the latest version of the floor plans identified by the slug


To get only active floor plans or in other words floor plans which are at their latest version you can use the ?active=true query parameter. So the same query as before but with this query parameter set.

Request:

curl
JavaScript
curl -X GET \ 
  -H "Congrid-API-Token: YOUR-API-TOKEN" \
  -H "Content-Type: application/json" \ 
  "https://api.congrid.com/v1/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorPlans?active=true"
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.congrid.com/v1/projects/PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ/floorPlans',
  qs: { active: 'true' },
  headers: 
   { 'content-type': 'application/json',
     'congrid-api-token': 'YOUR-API-TOKEN' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response:

{
  "count": 1,
  "pageSize": 100,
  "results": [
    {
      "description": "This is the base floorplan version 2",
      "floorPlanTypeId": "42b3c6feaa78c1",
      "name": "Floorplan 1 - version 2",
      "slug": "caa3ee71318e4214a73f72292fbe1db6",
      "id": "cdGe1mPC8r2lYLYp1KVyQg1GECnP2uvj",
      "projectId": "PilvPWN3hZoNq4UOXVg6FFklXBJRTVzQ"
    }
  ]
}

The response only contains the active versions of the floor plans.

results matching ""

    No results matching ""