Before You Start
Before you start reporting travel or work activities, it’s better to first get down to some process specifics, check whether the check-in/out permission is enabled, and obtain some required data.
Things to Consider
There are some very important things that you need to learn before the check-in/out magic starts happening.
Permissions
For the travel, provider, and GPS check-in/out types, special permissions should be enabled. The custom type, however, requires no permissions.
Note: Custom types don’t exist by default. Subscribers should ask ServiceChannel to create custom types for them.
Check-In/Out Pair
For proper reporting, each check-in should be followed by a check-out. Also, the same UserId should be used for one pair of connected check-in/out records. Note that connected check-in/out records share the same MechanicId — the action ID that you obtain after checking in and out via our API.
Work Order Status
You cannot check in/out when the work order status is COMPLETED or COMPLETED + all extended statuses. One exception is the COMPLETED / PENDING CONFIRMATION status that allows you to check in/out.
Also, you cannot report any activities for the work order that has been invoiced or voided.
Technician’s Current Position
For some types of check-in/out, you need to pass the GPS coordinates of the technician’s current position. The technician’s position should be in the range of the work order location. Otherwise, you are not able to record some types of activities.
In ServiceChannel, the allowed check-in/out range is described as GPS radius. For example, if the GPS radius is 0.5 miles, the distance between the WO location and the technician’s position should be up to 0.5 miles.
Each subscriber may choose any GPS radius, so request the exact value in advance.
Check-In/Out Date
Usually, check-in/out activities are reported in real time. In this case, you don’t even have to pass the check-in and check-out dates as the current date and time is used. Sometimes, however, it is required to record check-in/out activities either after the real event has already occurred or before the real event will take place.
To do that, you don’t need a time machine. Just use our API and pass the check-in and check-out dates in your API requests. There are numerous exceptions, though, that are described below. Also, to pass those dates, the XML check-in/out permission should be enabled between the provider and subscriber.
The check-in/out date should not be less than the work order call date. Also, this date should not be more than the current location date + 24 hours.
For example, if the WO call date is 2018-07-15 08:00:00 and the current location date is 2018-07-15 11:00:00, you can check in/out between 2018-07-15 08:00 and 2018-07-16 11:00:00.
However, when the difference between the WO call date and the current location date is more than 168 hours (7 days), you can check in/out only between the location date − 168 hours and the location date + 24 hours.
Check-In/Out Date for Maintenance WOs
The rules described above also apply to the check-in/out date for maintenance work orders. There is one exception, though. When the WO expiration date is less the current location date, you should check in/out between the WO call date and the WO expiration date.
Check-In/Out Permissions
There should be a special permission for most types of check-in/out.
For the GPS type, the GPS check-in/out permission should be enabled for the subscriber. The provider type requires the XML check-in/out permission enabled between the subscriber and provider. Also, you can report travel activities when either the GPS or XML permission is enabled, while the custom check-in/out requires no permission.
XML Check-In/Out Permission
We enable this permission between a subscriber and a specific provider.
To obtain the XML permission, providers should ask their subscribers to sign the Contractor Request Form for Web Service Integration and email it to contractorsupport@servicechannel.com.
GPS Check-In/Out Permission
We enable this permission between a subscriber and all subscriber’s providers. Subscribers should contact their ServiceChannel representative and ask them to turn on the GPS permission and set the GPS radius.
Required Parameters
Before you can check in and out, you need to get some initial information.
workorderId
workorderId is the unique ID, or tracking number, of the work order for which you want to report a check-in/out.
You can retrieve the WOs you have using the following methods. The field you are looking for is Id.
You can also create a new WO following one of the WO guides. After you generate a WO, you get workorderId in the response body.
UserId
UserId is the ID of the technician that is checking in or out. It is also known as IVR PIN that technicians use to identify themselves in the SC Provider mobile app or when calling into the Interactive voice response system.
By default, the current user's ID is passed when checking in/out via our API, so you do not have to retrieve UserId. However, to check in/out with other user ID, use the following methods to get other technicians' IDs. The field you are looking for is `Id`.