2 Nov 2022

BIM360 Checklist API now supports section signature and final sign-offs

By Xiaodong Liang

In Field Management of BIM360,  the checklists from templates is for tracking quality, punch lists, safety, and commissioning progress etc, in order to keep a project on track. One checklist instance is composed of a few individual sections, each of which can contain various types of items for checking.  You can also require signatures for a complete checklist (final sign-offs) or individual sections of a checklist(section signature). The final sign-offs signature is also called checklist-level signature. 

Checklist has exposed API for reading template and instance (including section items). In the past, it only returns a few attributes to indicate the status:

  • signaturesStatus: The signatures status of the checklist.
    • Pending - all sections are complete but one or more signatures are required.
    • Required - not all sections are complete, and one or more signatures are required.
    • Signed - no more signatures are required.
    • None - signatures are not needed.
  • totalRequiredSignatures: The number of required checklist-level signatures.
  • totalUnsignedSignatures: The number of checklist-level signed signatures.
  • totalSignedSignatures: The number of unsigned checklist-level signatures in the checklist.

Now it supports to get the content of section signature and checklist-level signature!

Checklist-level Signature

1

A new query parameter (signatures) is introduced with GET: Instances/:id. When this parameter is true, it will return the checklist-level signature at data.attributes.signatures. Except the basic data such as signedName, signedCompany, it also returns content in the patten of svg. The svg data can be used to render an image directly. 

 "data": {
        "type": "instances",
        "id": "2606690",
        "attributes": {
            "urn": "urn:adsk.checklists.cs.instance:55b9a76f-ff85-4831-8bee-e2cedc10b967/2606690",
            "signatures": [
                {
                    "id": "b303a86a-f9fe-4a04-a333-96b2ced54c83",
                    "urn": "urn:adsk.checklists.cs.instance.signature:55b9a76f-ff85-4831-8bee-e2cedc10b967/b303a86a-f9fe-4a04-a333-96b2ced54c83",
                    "instanceId": 2606690,
                    "index": 0,
                    "requiredBy": "",
                    "isRequired": true,
                    "requiredName": "final",
                    "requiredCompany": "mytest",
                    "signedName": "final",
                    "signedCompany": "mytest",
                    "submittedBy": "200902260532621",
                    "signedAt": "2022-11-02T23:36:59.185Z",
                    "createdAt": "2022-11-02T14:57:22.987Z",
                    "updatedAt": "2022-11-02T15:37:35.352Z",
                    "deletedAt": null,
                    "isSigned": true,
                    "content": "<svg xmlns=\"http://www.w3.org/2000/svg\" version=\"1.2\" viewBox=\"0 0 566 150\" height=\"150\" width=\"566\"><g stroke-width=\"5\" stroke-linejoin=\"round\" stroke-linecap=\"round\" fill=\"none\" stroke=\"black\"><path d=\"M 181.5 21.3125 L 179.5 21.3125 L 175.5 23.3125 L 170.5 26.3125 L 164.5 31.3125 L 159.5 37.3125 L 154.5 43.3125 L 150.5 50.3125 L 147.5 58.3125 L 144.5 65.3125 L 141.5 73.3125 L 138.5 80.3125 L 134.5 86.3125 L 132.5 94.3125 L 129.5 99.3125 L 128.5 105.3125 L 126.5 110.3125 L 125.5 115.3125 L 122.5 120.3125 L 121.5 122.3125 L 119.5 127.3125 L 117.5 130.3125 L 116.5 133.3125 L 115.5 135.3125 L 113.5 137.3125 L 112.5 139.3125 L 110.5 140.3125 L 109.5 142.3125 L 107.5 143.3125 L 106.5 144.3125 L 104.5 145.3125 L 103.5 146.3125 L 102.5 147.3125 L 101.5 147.3125 L 100.5 148.3125 L 98.5 148.3125 L 96.5 149.3125 L 94.5 150.3125 L 92.5 150.3125\"></path></g><g stroke-width=\"5\" stroke-linejoin=\"round\" stroke-linecap=\"round\" fill=\"none\" stroke=\"black\"><path d=\"M 120.5 70.3125 L 120.5 69.3125 L 122.5 69.3125 L 128.5 67.3125 L 132.5 67.3125 L 137.5 66.3125 L 142.5 65.3125 L 146.5 65.3125 L 151.5 64.3125 L 155.5 64.3125 L 158.5 64.3125 L 161.5 64.3125 L 163.5 64.3125 L 165.5 64.3125 L 166.5 64.3125 L 167.5 63.3125 L 169.5 63.3125 L 172.5 63.3125 L 174.5 62.3125 L 178.5 60.3125 L 179.5 60.3125 L 181.5 59.3125\"></path></g><g stroke-width=\"5\" stroke-linejoin=\"round\" stroke-linecap=\"round\" fill=\"none\" stroke=\"black\"><path d=\"M 206.5 51.3125 L 205.5 54.3125 L 203.5 56.3125 L 202.5 59.3125 L 201.5 61.3125 L 200.5 63.3125 L 200.5 65.3125 L 200.5 67.3125 L 199.5 69.3125 L 199.5 70.3125 L 199.5 71.3125 L 199.5 72.3125 L 199.5 73.3125 L 200.5 74.3125 L 200.5 75.3125 L 201.5 75.3125 L 202.5 76.3125 L 203.5 76.3125 L 205.5 77.3125 L 206.5 77.3125 L 207.5 77.3125 L 208.5 77.3125 L 209.5 77.3125 L 210.5 77.3125 L 211.5 77.3125\"></path></g><g stroke-width=\"5\" stroke-linejoin=\"round\" stroke-linecap=\"round\" fill=\"none\" stroke=\"black\"><path d=\"M 211.5 34.3125\"></path></g><g stroke-width=\"5\" stroke-linejoin=\"round\" stroke-linecap=\"round\" fill=\"none\" stroke=\"black\"><path d=\"M 211.5 32.3125 L 211.5 33.3125 L 211.5 35.3125 L 211.5 36.3125 L 214.5 38.3125 L 214.5 39.3125\"></path></g><g stroke-width=\"5\" stroke-linejoin=\"round\" stroke-linecap=\"round\" fill=\"none\" stroke=\"black\"><path d=\"M 235.5 61.3125 L 234.5 65.3125 L 234.5 67.31\"></path></g><g stroke-width=\"5\" stroke-linejoin=\"round\" stroke-linecap=\"round\" fill=\"none\" stroke=\"black\"><path d=\"M 458.5 28.3125 L 458.5 31.3125 L 459.5 33.3125 L 460.5 36.3125 L 462.5 38.3125 L 465.5 42.3125 L 466.5 42.3125\"></path></g></svg>",
                    "type": "SVG"
                }
            ]
        }

 

Section Signature

2

The section signature is slightly different. Firstly, you need to specify query parameter (include= sections,sections.items) as usual. This will return the information of sections. In each section data, the attribute sectionSignatures is provided. The section signatures are managed as image file in BIM360 storage. Like other file in BIM360,it has an unique ossurn which contains 

  • urn:adsk.objects:os.object (the Object Storage Service)
  • checklists.prod.us (the bucket key)
  • 6a2bc2e8-db7b-41a2-9a6d-d05b4bd4f299 (the signature object key)
"sectionSignatures": [
                    {
                        "id": "5a67e7df-97d9-487e-9d54-8df5c9c60f96",
                        "urn": "urn:adsk.checklists.cs.item.signature:55b9a76f-ff85-4831-8bee-e2cedc10b967/5a67e7df-97d9-487e-9d54-8df5c9c60f96",
                        "ossUrn": "urn:adsk.objects:os.object:checklists.prod.us/5a67e7df-97d9-487e-9d54-8df5c9c60f96",
                        "instanceSectionId": 13609802,
                        "index": 3,
                        "requiredBy": "",
                        "isRequired": true,
                        "signedName": "API",
                        "signedCompany": "Test",
                        "submittedBy": "200902260532621",
                        "signedAt": "2022-11-02T23:34:56.981Z",
                        "createdAt": "2022-11-02T14:57:22.981Z",
                        "updatedAt": "2022-11-02T15:35:26.424Z",
                        "deletedAt": null,
                        "instructions": "",
                        "uploadStatus": "Completed",
                        "uuid": "158ea2d0-5300-4eff-8d9f-8bd6962d7203"
                    }
                ]

By bucket key and object key, you will need to call POST buckets/:bucketKey/objects/batchsigneds3download to get its signed url of S3. With the signed url, you can get the binary file of the signature image.  The tutorial describes in detail.

Tags:

Related Article