Checklist Document Item_Type

General
1

Has anyone figured out what the “Document” item_type is for Checklists? This is not mentioned anywhere in the support documents, and I’m intrigued, but nothing in terms of starting point to understand what it does let alone how to leverage it.

2

Hi Miciah,

In the Job Checklist API, item_type supports ‘Todo’, ‘Asset’, ‘Photo’, ‘Form’, and ‘Document’ (and defaults to ‘Todo’). The API schema description for item_type is that it determines the functionality and appearance of the checklist item.

If you’re seeing item_type='Document' on existing checklist items, retrieving that record via GET /jobchecklist/{uuid}.json will also show the regarding_object / regarding_object_uuid fields and the fulfilled_by_object_name / fulfilled_by_object_uuid fields, which is the best clue as to what it’s linking to and what completed it.

If the goal is to capture paperwork against a job, the iOS app’s Document Scanner job action can scan paper documents and attach it as a PDF file in the Job Diary as a Document. If the goal is to have structured paperwork appear as a checklist requirement, adding a Form’s badge to a job means the form will appear on the mobile app as a job checklist item.

If you’re generating documents via API, the Document Templates API can produce PDF, DOCX or JPG output, and storeToDiary=true will automatically attach to the job diary.

Reply here with a redacted JSON example of one of the Document checklist items (especially the regarding_* and fulfilled_by_* fields) and we can confirm what it’s linking to.

Thanks,
Cody

3

So the “Document” Checklist Type only gives the user to option to select an attachment which exists on the Job already? No option to upload (on mobile)? And once provided and completed, there is no way to open the related item? Seems like a missed opportunity…

4

Hi Miciah,

In the API, “Document” is simply one of the valid item_type values for a Job Checklist item, and the only behaviour description in the schema is that item_type determines the functionality and appearance of the checklist item.

The most reliable way to see what a specific Document checklist item is meant to reference (and what actually completed it) is to retrieve the checklist record via GET /jobchecklist/{uuid}.json and check the regarding_object / regarding_object_uuid and fulfilled_by_object_name / fulfilled_by_object_uuid fields.

If your goal is “upload/attach the document while on-site”, the iOS app supports getting documents onto the job in a couple of ways, then they’ll live in the Job Diary as attachments:

  • Document Scanner scans paper documents and saves them to the Job Diary as a PDF Document.
  • If you already have a PDF/file on the device, you can use the iOS share sheet to share it into ServiceM8 and attach it to a job card.

And for opening/viewing the document after it’s attached, PDFs are designed to be opened from the job’s Diary in the app.

If what you’re really chasing is a checklist item that launches a piece of structured paperwork to complete (rather than selecting an existing attachment), adding a Form’s Badge to the job is the documented workflow, because the form will appear on the mobile app as a job checklist item.

If you can paste a redacted example of the JSON from GET /jobchecklist/{uuid}.json for one of your item_type='Document' items (especially the regarding_* and fulfilled_by_* fields), we can confirm exactly what object it’s linking to in your case.

Thanks,
Cody

5

Thanks Cody,

I completely get all of that.

My OP was based on the fact that there was no documentation around what the “Document” item_type does.

Once that was sorted, my comments were not about how to use it, but rather the lack of functionality with this type of Checklist item.

To put it another way: If the Checklist is requesting a document (ie: Upload Receipt), the user can not do so from the Checklist action (like we can with Photo types), they must first upload it to the Job through one of the other means you mentioned, then it can be selected. Once the Checklist item is complete, and the attachment is related to the Checklist item, there is no native option to simply open the related attachment from the Checklist item (like you can with a completed Form item_type).

Just like a Photo item_type initiates the camera to capture the photo, or a Form item_type starts the process to complete the indicated Form, it feels like a missed opportunity to not include the option to upload or scan a document when marking this type complete.

In the same train of thought, bringing uniformity to the UX by having completed Photo & Document Checklist items open their related objects like we can with Forms only makes sense.