Uploading Plans via API

Intro

Plan viewing is one of the core features of Fieldwire. Due to the nature of how plans are stored in Fieldwire, uploading new plans is be a multi step process that involves both a file upload and plan object creation. Uploading plans using the Fieldwire API is a 3 step process:

1. Generate an AWS POST token using https://developers.fieldwire.com/reference/add_aws_post_tokens
2. Use the response from that API call to upload the file directly to the Fieldwire S3 Bucket
3. Create a "sheet upload" using the url returned from the S3 bucket

This process can be used for both multi-page pdfs or single page pdfs, however multi-page pdfs will go through the normal plan name confirmation process. See https://help.fieldwire.com/hc/en-us/articles/360061902452 for more details

Note

Would you like diving into the code & learning from that? Wonderful! We have 2 sample applications that demonstrate this flow

• Ruby
• Java

Generating an AWS POST token

The first step in the upload process is to generate an AWS POST token. This will be used to upload your plan file directly to the Fieldwire S3 bucket.

Use the API call in https://developers.fieldwire.com/reference/add_aws_post_tokens with your Fieldwire API token to generate the information required to upload a file to s3. Please make sure to upload the file to the same Fieldwire region as where you want the plan to be created it

API response

After calling the /add_aws_post_tokens endpoint, you should receive a response with the following information:

• post_address
• post_parameters
  • key
  • x-amz-meta-original-filename
  • policy
  • x-amz-credential
  • x-amz-algorithm
  • x-amz-date
  • x-amz-signature

Note: This information will remain valid for up to an hour

Uploading a File to S3

Once you have generated the required information from the previous API call, you can now upload your file to s3.

Using the post_address and post_parameters generate a POST call to AWS with the following information gathered from the previous API response

url = {{post_address}}


body = {{json formatted value of post_parameters}}

file = {{local file}}

Notes:

• The order of the parameters is important and must be kept from the response of the API call made above
• Make sure to maintain the values ${filename} in your upload to S3
• You may receive an empty 204 response from AWS API call, this is normal

Uploading your plans to Fieldwire

After uploading the file to s3, you are now ready to upload the floorplan to Fieldwire.

1. Combine the post_address and the key to generate a file url
   1. Here you must replace the ${filename} value in the key with the exact name of the file you are uploading
   2. Do not attempt to url encode any values in this step
2. Perform a POST call to https://developers.fieldwire.com/reference/create_sheet_upload_in_project with the following information:

url = /api/v3/projects/{{project_id}}/sheet_uploads

body = {
  "user_id":{{user_id}},
  "name": {{floorplan name}},
  "file_url": "{{post_address}}/{{key}}"
}

Uploading a new version of a plan

Once a plan has been uploaded, additional sheet versions can be added onto the same plan. In this scenario, steps 1 and 2 above should be repeated, in order to upload the necessary files to the Fieldwire S3 bucket. However in order to add the sheet as a new version, you must make a PATCH call to the Floorplan endpoint as shown below.

Notes:

• You must have the Floorplan ID of the plan you'd like to add a sheet version to
• You'll need to generate the post_address and key as shown in previous steps if you haven't already
• ${filename} will need to be replaced in the key field here with the actual file name - similar to uploading plans for the first time

url = /api/v3/projects/{{project_id}}/floorplans/{{floorplan_id}}

body = {
  "sheets": [
    {
      "name": {{key}},
      "original_url": "{{post_address}}/{{key}}"
    }
  ]
}