Troubleshooting

10 minute read

This page will help you find the best solution to the most common problems that you may encounter when submitting and updating checklist responses. It also details the current request validation rules. Additionally, several recommendations are provided to help prevent issues when the updated validation system is implemented.

Submitting Checklist Response

Use the POST /checklists/CheckListResponse method to submit a checklist response.

General

The request to submit a checklist response contains some common parameters regardless of the question type. These parameters are:

  • ChecklistQuestionId [Required]
  • EntityId [Required]
  • ProviderId [Required]
  • Attempt [Required]
  • TechnicianId
  • AuthUserId

In addition, an attachment can be added to respond to the checklist.

Important: Special attention should be given to the correct use of the Attempt parameter, as its misuse when submitting checklist responses is one of the most common issues.

ChecklistQuestionId

This parameter specifies the ID of the checklist question you are responding to. The field is required, and the following validation rules apply:

Current verification rules

  • The parameter should not be null.
  • The parameter should be greater than 0.
  • The parameter should contain the ID existing in the database.

Planned validation rule

  • The parameter should contain the question ID associated with the active current checklist for the specified work order.

EntityId

This parameter specifies the work order ID for which the checklist answers will be submitted. This parameter is mandatory, and the following validation rules apply:

Current verification rules

  • The parameter should contain the work order ID existing in the database.
  • The user should have authorized access and user permissions to manage the specified work order.

Planned validation rule

  • There should be an active current checklist available for the specified work order.

ProviderId

This parameter specifies the provider ID associated with the checklist response. This parameter is mandatory. The following validation rules apply:

Current verification rules

  • The parameter should not be null.
  • The parameter should be greater than 0.
  • The parameter should contain the provider ID existing in the database.

Attempt

The order of the technician’s onsite visit for which you are submitting a checklist response. Data with an empty value or a value less than 1 will be invalid for further processing. Currently, the most common cause of issues with displaying and processing checklist responses is misuse of this parameter.

Planned validation rules

  • The parameter should not be null.
  • The parameter should be greater than 0.

TechnicianId and AuthUserId

These parameters contain the Technician ID or associated User ID of the user on whose behalf you are sending the response. At least one of these parameters should be passed in the request. TechnicianId takes precedence if both are filled in.

Current verification rules

  • One of the parameters should be greater than 0.
  • Parameters should contain the ID linked to the existing technician.

Submit a response to Acknowledgement question

To submit a checklist response for this type of question, in addition to the parameters outlined in the General section, you should provide values for the following parameter:

  • Answer

Example

POST https://sb2api.servicechannel.com/v3/checklists/CheckListResponse  
accept: application/json  
authorization: bearer YOUR_BEARER_TOKEN  
Content-Type: multipart/form-data; boundary=WebAppBoundary  
  
--WebAppBoundary  
Content-Disposition: form-data; name="CheckListResponseRequest"  
  
{  
    CheckListQuestionID: 16525,
    ProviderID: 2000019527,
    TechnicianID: 173134,
    EntityID: 290554999,
    Attempt: 1,
    Answer: 'yes'
}  
--WebAppBoundary--

Answer

This parameter contains the answer to the question. Valid values for the Acknowledgement question type are on, 1, true, yes, off, 0, false, no. The checklist response is saved with an empty string if the value is not filled or is invalid. The following validation rules apply:

Current verification rules

  • If the question is marked as ‘answer required’, Answer should not be an empty string or null.
  • If the question is marked as URL view required, Answer should contain only the following values: on, 1, true, yes.

Submit a response to Selector question

To submit a checklist response for this type of question, in addition to the parameters outlined in the General section, you should provide values for the following parameters:

  • CheckListQuestionOptionID
  • FreeTextAnswer

Example

POST https://sb2api.servicechannel.com/v3/checklists/CheckListResponse  
accept: application/json  
authorization: bearer YOUR_BEARER_TOKEN  
Content-Type: multipart/form-data; boundary=WebAppBoundary  
  
--WebAppBoundary  
Content-Disposition: form-data; name="CheckListResponseRequest"  
  
{  
    CheckListQuestionID: 16527,
    ProviderID: 2000019527,
    TechnicianID: 173134,
    EntityID: 290554999,
    Attempt: 1,
    CheckListQuestionOptionID: 22321,
    FreeTextAnswer: 'user comment'
}  
--WebAppBoundary--

CheckListQuestionOptionID

This parameter contains the ID of the selected option used to answer the question. The checklist response is saved with an empty string in Answer if the value for CheckListQuestionOptionID is not populated. The following validation rules apply:

Current verification rules

  • If the question is marked as ‘answer required’, the parameter should be greater than 0.
  • The parameter should contain the ID of the checklist question option existing in the database.
  • The parameter should contain the ID of the answer option associated with the specified checklist question.

FreeTextAnswer

This parameter contains an additional comment about the answer. The parameter is available for input only when the IsConditionalFollowUp attribute option is specified. To add IsConditionalFollowUp to an option, the User Input Response checkbox should be activated when configuring a checklist in the Admin section of Service Automation. The maximum length is 200 characters.

Current verification rule

  • If the question is marked as ‘answer required’, the parameter should be greater than 0.

Submit a response to Text entry question

To submit a checklist response for this type of question, in addition to the parameters outlined in the General section, you should provide values for the following parameter:

  • Answer

Example

POST https://sb2api.servicechannel.com/v3/checklists/CheckListResponse  
accept: application/json  
authorization: bearer YOUR_BEARER_TOKEN  
Content-Type: multipart/form-data; boundary=WebAppBoundary  
  
--WebAppBoundary  
Content-Disposition: form-data; name="CheckListResponseRequest"  
  
{  
    CheckListQuestionID: 16528,
    ProviderID: 2000019527,
    TechnicianID: 173134,
    EntityID: 290554999,
    Attempt: 1,
    Answer: 'isolated coil 11a'
}  
--WebAppBoundary--

Answer

The maximum length of the Answer is 500 characters.

Current verification rule

  • If the question is marked as ‘answer required’, the parameter should not be blank.

Submit a response to Numeric question

To submit a checklist response for this type of question, in addition to the parameters outlined in the General section, you should provide values for the following parameter:

  • Answer

Example

POST https://sb2api.servicechannel.com/v3/checklists/CheckListResponse  
accept: application/json  
authorization: bearer YOUR_BEARER_TOKEN  
Content-Type: multipart/form-data; boundary=WebAppBoundary  
  
--WebAppBoundary
Content-Disposition: form-data; name="CheckListResponseRequest"  
  
{    
    CheckListQuestionID: 16529,  
    ProviderID: 2000019527,
    TechnicianID: 173134,
    EntityID: 290554999,
    Attempt: 1,
    Answer: 12.53
}    
--WebAppBoundary--

Answer

Planned validation rules

  • If the question is marked as ‘answer required’, the parameter should not be blank.
  • The parameter should contain a number.

Submit response with attachment

A file can be attached to any type of question. The requirement to attach a file to a response is configured when configuring a checklist in the Admin section of Service Automation. For each question, one of the following options can be specified:

  • Attachment is optional (PictureFlag = 0).
  • Attachment is not allowed (PictureFlag = 1).
  • Attachment is required (PictureFlag = 2).

If the PictureFlag is set to 1 for a question, any attached file will be ignored and not saved when submitting or updating a response.

The following validation rules apply:

Current verification rules

  • The file size should be less than 50MB.
  • If the PictureFlag attribute value for a question is 2, the attached should be uploaded.

Example of request to submit a response to number question with the attached file

POST https://sb2api.servicechannel.com/v3/checklists/CheckListResponse  
accept: application/json  
authorization: bearer YOUR_BEARER_TOKEN  
Content-Type: multipart/form-data; boundary=WebAppBoundary  
  
--WebAppBoundary
Content-Disposition: form-data; name="CheckListResponseRequest"  
  
{    
    CheckListQuestionID: 16529,  
    ProviderID: 2000019527,
    TechnicianID: 173134,
    EntityID: 290554999,
    Attempt: 3,
    Answer: 12.53
}    
--WebAppBoundary  
Content-Disposition: form-data; name="file"; filename="light_bulb#1.jpg"  
  
< C:/light_bulb#1.jpg  
--WebAppBoundary--

Best practices for submitting responses to the checklist

To comply with the planned validation rules and keep the data correct and up-to-date, follow these guidelines:

Success Strategies

  • Always populate the Attempt parameter.
  • Start with an attempt value of 1 and increment by 1 for each subsequent visit.
  • If a new checklist is associated with a work order, the Attempt value for new visits should reset to 1. For example, the Maintenance Checklist is initially associated with a work order, and the technician visits the site 3 times, completing the checklist on each visit. If the work order category changes and the checklist is updated to a Repair Checklist, the Attempt value should reset to 1 for the technician’s next visit. However, if the work order category is later switched back to the original and the Maintenance Checklist is reassociated with the work order, the Attempt value should pick up where it left off. In this case, the next attempt should be 4.
  • When submitting an answer to a numeric question, the Answer parameter should contain a number. The number may be enclosed in quotation marks, for example, “12.34”.

Avoidable Missteps

  • Do not start the attempt order from the beginning when sending responses to the checklist for new technicians. The Attempt value should increment by 1 for a new visit regardless of which technician fills out the checklist.
  • Do not submit responses to checklist questions that are not related to a work order. The ChecklistQuestionId parameter should contain the question ID of the currently active checklist.
  • When submitting a response to a Text question, do not leave the Answer parameter blank if the question requires an answer.
  • Avoid using the PUT /checklists/{checkListResponseId}/CheckListResponse method to create new checklist responses. This approach is incorrect, and this functionality will be disabled in the future. Use the POST /checklists/ChecklistResponse method instead.

Updating Checklist Response

Use the PUT /checklists/{checkListResponseId}/CheckListResponse method to update an existing checklist response.

General

The request to update a checklist response contains some common parameters regardless of the question type. These parameters are:

  • ChecklistQuestionId [Required]
  • EntityId [Required]
  • ProviderId [Required]
  • Attempt [Required]
  • TechnicianId
  • AuthUserId
  • CheckListResponsePictureId

The identifier of the checklist response to update should be passed through the URL (/checklists/{checkListResponseId}/CheckListResponse).

Important: Special attention should be given to the correct use of the Attempt parameter, as its misuse when updating checklist responses is one of the most common issues.

The validation rules and recommendations described above in the Submitting Checklist Response section apply to all parameters.

Example of request to update the answer to Acknowledgement question

PUT https://sb2api.servicechannel.com/v3/checklists/26259255/CheckListResponse  
accept: application/json  
authorization: bearer YOUR_BEARER_TOKEN  
Content-Type: multipart/form-data; boundary=WebAppBoundary  
  
--WebAppBoundary  
Content-Disposition: form-data; name="CheckListResponseRequest"  
  
{  
    CheckListQuestionID: 16525,
    ProviderID: 2000019527,
    TechnicianID: 173134,
    EntityID: 290554999,
    Attempt: 1,
    Answer: 'no'
}  
--WebAppBoundary--

This API endpoint also allows to add a new attachment or replace an existing one.

Example of request to update the answer to Acknowledgement question with a new file attached

PUT https://sb2api.servicechannel.com/v3/checklists/26259255/CheckListResponse  
accept: application/json  
authorization: bearer YOUR_BEARER_TOKEN  
Content-Type: multipart/form-data; boundary=WebAppBoundary  
  
--WebAppBoundary  
Content-Disposition: form-data; name="CheckListResponseRequest"  
  
{  
    CheckListQuestionID: 16525,
    ProviderID: 2000019527,
    TechnicianID: 173134,
    EntityID: 290554999,
    Attempt: 1,
    Answer: 'no'
}  
--WebAppBoundary  
Content-Disposition: form-data; name="file"; filename="light_bulb#1.jpg"  
  
< C:/light_bulb#1.jpg  
--WebAppBoundary--

Example of request to update the answer to Acknowledgement question and update the attached file

PUT https://sb2api.servicechannel.com/v3/checklists/26259255/CheckListResponse  
accept: application/json  
authorization: bearer YOUR_BEARER_TOKEN  
Content-Type: multipart/form-data; boundary=WebAppBoundary  
  
--WebAppBoundary  
Content-Disposition: form-data; name="CheckListResponseRequest"  
  
{  
    CheckListQuestionID: 16525,
    ProviderID: 2000019527,
    TechnicianID: 173134,
    EntityID: 290554999,
    Attempt: 1,
    Answer: 'no'
}  
--WebAppBoundary  
Content-Disposition: form-data; name="CheckListResponsePictureId"  

1281130  
--WebAppBoundary  
Content-Disposition: form-data; name="file"; filename="light_bulb#2.jpg"
  
< C:/light_bulb#1.jpg  
--WebAppBoundary--

ChecklistQuestionId

In addition to the described above, the following validation rule applies when updating an existing checklist response:

Planned validation rule

  • The parameter should contain the same question ID as the existing checklist response.

EntityId

In addition to the described above, the following validation rule applies when updating an existing checklist response:

Planned validation rule

  • The parameter should contain the same work order ID as the existing checklist response.

Attempt

Currently, the most common cause of issues with displaying and processing checklist responses is misuse of this parameter. In addition to the described above, the following validation rule applies when updating an existing checklist response:

Planned validation rule

  • The parameter should contain the same Attempt value as the existing checklist response.

ChecklistResponseId

Planned validation rule

  • The parameter should contain the ID of the existing checklist response.

CheckListResponsePictureId

This parameter specifies the identifier of the existing attachment to be updated. The uploaded file will be added as a new attachment to an existing checklist response if the parameter is not filled in. The following validation rule applies:

Current verification rule

  • When populated, the parameter should contain the ID of the existing attachment record for the updated checklist response.

Best Practices for Updating Checklist Responses

To ensure compliance with the validation rules and maintain accurate, up-to-date data, follow these guidelines:

Success strategies

  • When updating an existing checklist response, always use the same ChecklistQuestionId, Attempt, and EntityId values as when the response was originally created.
  • Avoid using the checklist response update method to save new responses by passing invalid values, for example, -1, in the ChecklistResponseId parameter.

Updated: