Web Services Developer Guide - Introduction

Overview

We offer a series of SOAP-based web services that allow customers to extend the usage of 3rd-party software by synchronizing and sharing data with Field Force Manager. 

You can download the developer guide in PDF format or review it in our help center:

• Introduction (covered in this article)
• Company Admin Service
• User Status Service
• Location Service
• Message Service
• Alert Service
• Job Service
• GPS Service
• Mileage Service
• Parts Management Service

Information

This article contains the following sections:

• Authentication
• Polling & Usage Restrictions
• System Integration & Troubleshooting
• Security & Roles
• Date & Time Formats

The list of services and APIs are exposed through WSDL. There are multiple versions (v0.0.1, v0.0.2, etc.) and types (wrapped and RPC) of WSDLs. The difference between wrapped and RPC: the response in wrapped service will not have the encoding info (ex. integer/String/float) and the size will be smaller compared to the RPC response. The SOAP-based services are strictly typed - adding a new version is the only way to add new properties without breaking the existing integration. The latest version will have additional data - so always use the latest version. 

Authentication

Access to the Field Force Manager web services is provided via a username/password/company id combination of authentication information. This combination of information must be passed on each web service request. The capabilities and access of the requesting user are determined by the security role of the web services user (its permissions).

The authentication parameters are passed in the HTTP header, this is commonly confused with the SOAP header. The parameters need to be passed with each request.

Web Service URL

To view WSDL or connect to web services go to the following URL:

https://webservices.fieldforcemanager.com

Polling & Usage Restrictions

The Field Force Manager web services system is designed to allow the user to keep their system synchronized with other back-office systems. Here are a couple of restrictions to keep in mind when querying the system for data.

• The Field Force Manager system limits web service responses to returning up to 500 items. If your request may return more than 500 items, try limiting the date range or other filters (workers, groups).
• The Field Force Manager system limits querying for data from a specific web service method to once every five minutes. Web service requests that happen more often are subject to being rejected by the system. The service will return an error if hourly usage is exceeded.
• The Field Force Manager system is monitored for excessive usage and reserves the right to turn off web service accounts for excessive usage.

Throttling

The Throttling filter protects a Web Service or Service Oriented Architecture (SOA) from message flooding. The throttle is in place to protect the system performance from customers who may be sending an overwhelming number of requests. If the number of calls exceeds the specified limit, the filter rejects the calls. Calls will start working automatically after the specified time period has passed. There are a very few specific scenarios which might necessitate raising the throttles slightly, if you believe your business requires this, please contact our support department for guidance and review of your integration to determine if your throttle limit can be modified. The types of throttling are described below.

Time-based limits:

1. Per minute throttling – 25 calls per service
2. Per hour throttling – 250 calls per service

Per hour throttling

This rule limits the total number of API calls per service per hour. The default limit is 250 request/service/hour. This means if your integration is using UserStatusService and JobService, you are allowed to make 250 call for UserStatusService and 250 calls for JobService within an hour. If you constantly get throttling exception, then please check the call pattern. For example, a company having 200 mobile workers and 4 divisions which requires to create 400 jobs in a day can use the following call pattern:

Call createJobs API with 25-50 jobs instead of calling createJob 400 times.

Make one getJobs call or four getJobsByDivision calls (1 call per division), instead of calling getJobsByWorker 200 times (1 call for each worker).

Make 1 getWorkers or 4 getWorkersByDivision call instead of calling getWorkerByName 200 times.

Per minute throttling

This rule limits the total number of API calls per service per minute. The default limit is 25 requests per minute. This throttle makes sure you aren’t overwhelming the system with a ton of near-simultaneous requests. If your application makes relatively few requests (under your hourly limit described above), you may need to ensure your integration does not try to make too many requests at a time. For example, if you need to call getJobByReferenceNumber on 100 different jobs every hour, plan on taking over 4 minutes to complete (25/minute) by giving 3-5 seconds delay between consecutive calls. If you have to create 1000 jobs for the whole day, then use createJobs API with 20-50 jobs in each call and make 1 to 2 calls per minute. This pattern would create all the jobs within an hour.

Volume based limits:

The maximum image size in get calls is 500 MB.

This rule limits the total size of all images in a single “get” call. If a call includes more than 500 MB of images, then the service will throw an exception. If the client gets this exception, then reduce the date range or number of groups.

System Integration and Troubleshooting

The client system can be integrated with web services using various technologies or 3rd-party software systems. When choosing systems and technologies to build integration, we recommend to choose a system with the functionality to schedule calls and that have a back-end storage system (like MSACCESS, Oracle, MySQL).

Before starting the integration, identify the APIs that best suits your business/requirement. Make regular requests for small and fixed duration and store the data. This will make your integration robust. We have exposed large number of APIs for your convenience. Select the APIs based on the number of Mobile workers, Number of divisions, Number of Jobs per day, etc. You can contact our support department for more assistance.

Example 1:

Requirement: Need to create jobs 1 at a time without having a fixed number of jobs per day.

Solution: You can use createJob or createJobs API to create Job. To get the job information, you can use getJobs API or getJobsByDivision (if the data is required per group ). You can send get calls in the following way:

• 1 call per hour to retrieve information for the previous hour
• 2 calls per hour to retrieve information for the previous 30 minutes
• 1 call every 2 hours  to retrieve information for the previous 2 hours

Example 2:

Requirement: Need to create 1000 Jobs before 5:00 AM.

Solution: Use createJobs API with 50-100 jobs in a call. Make sure that client will wait sufficient time (2-5 minutes) before resubmitting same data in case of no response. It is better to configure 1-3 minutes of delay between the calls. The client should not try to push all the jobs at a time with multiple threads.

Best practices

• Make calls at regular intervals.
• Use multi-threads but make sure that the client doesn't make all the calls at a time. Give sufficient time gaps between the calls.
• Make different API calls in different executions - so that if one API fails, it will not block the whole client.

Troubleshooting

General

Check the time-out value of the client, other network devices like router, proxy etc., and make sure that it is 1 minute or longer. It is preferable to set the client timeout to 5-10 mins (e.g., when there is a large response size and/or when the calls take a long time to complete).

.Net

• Make sure that client is using the most recent version of the .NET Framework.
• Disable the keep-alive feature. In the .NET Framework, set the HttpWebRequest.KeepAlive property to FALSE, which allows to close and reopen connections for each request.
• The ServicePointManager.MaxServicePointIdleTime value should be smaller than the timeout value of the server keep-alive connection.

Security & Roles

Access to Field Force Manager web services is controlled by the role of the user making the request. Each web service request must contain a valid username and password for the requesting user. The default web service role is configured with all web service permissions for the company. The permissions available to roles are controlled by the package or features available to the company or account (depending on the packages that are used). 

Methods available by Service:

Date & Time Formats

The Field Force Manager web services allow the users to retrieve data for a specified date range. The Field Force Manager web services use GMT/UTC for the date ranges in all queries. When making a web service request to the Field Force Manager system, the web service will query items that have been created or updated during the specified date range. However, some information (e.g., GPS, Timecard actions) that was stored on a mobile device and uploaded to the server later will have the entry time before the last update time.

You can retrieve data using continuous date ranges: when you making calls, you can use the endDate returned is the Field Force Manager system time as the startDate for your next call; the data for the startDate is included, but the data for the endDate is excluded.

The format of the date/time is as follows: YYYY-MM-DD HH:MM:SS.MMM

For example, February 13, 2006 12:45 PM would be 2006-02-13 12:45:00.000