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 ones can 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:
- Generate an AWS POST token using https://developers.fieldwire.com/reference/add_aws_post_tokens
- Use the response from that API call to upload the file directly to the Fieldwire S3 Bucket
- 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
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
- acl
- 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}}
data = {{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
- Replace ${filename} from the previous response with the name of your file
- 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. Combine the post_address and the key to generate a file url, and run a POST request 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
url = /api/v3/projects/{{project_id}}/floorplans/{{floorplan_id}}
body = {
"sheets": [
{
"name": {{key}},
"original_url": "{{post_address}}/{{key}}"
}
]
}
Updated 10 months ago