Tag Archives: timecontrol documentation

API Dynamic Documentation

Writing documentation for any software product is a significant challenge.  There’s the obvious of course, how each function works targeted at end-users.  For TimeControl that’s quite straightforward.  Our User Guide is about 100 pages (a little longer for TimeControl Industrial as it has to cover the use of Crew Timesheets and Materials).  It’s under the covers that Documentation takes on more significance.

With a product like TimeControl, the level of flexibility and configuration that is possible with the product makes those elements of documentation much longer.  No client needs to know everything about how to configure every element of TimeControl as clients only need to focus on that functionality and those processes that are specific to their needs.  But there’s still a lot of it.  The TimeControl Industrial Reference Guide is over 600 pages long.  There’s also the TimeControl Report Designer Guide that is a little over 200 pages, the soon to be defunct legacy guide at 48 pages, the Installation Guide for on-premise clients at 90 pages and the TimeControl Project Guide at 44 pages so far.  It’s a lot.  There are variations on those guides to accommodate TimeControl on-premise vs. TimeControl Online and TimeControl vs. TimeControl Industrial.

There’s more of course.  The website has numerous white papers and other collateral like videos and webcasts to talk more about specific solutions and processes.  And, there is this blog where we try to add detail to things that need to be showcased or clarified for specific circumstance.

While all of that may seem like a lot, there is another category of documentation we haven’t talked about and that is the API Guide.   The TimeControl API is the Application Programming Interface that lets you write programming code directly to the TimeControl  Server service to allow it to integrate with actions from other applications.

The API Guide is not an indexed PDF like the other guides.  It is dynamic.  The API Guide includes static elements which HMS has created to show how to authenticate, how to initiate code to access the API and more.  Topics include Authentication, Security, Errors, how to scale, versioning, rate limiting, OData support along with Examples and a complete list of Endpoints.  For each EndPoint you can see all possible operations and for each operation, there is example code.  Any changes to the API cause automatic updates to the API Guide so it is impossible for it to be out of date.

Taking advantage of the API requires expertise in both programming and TimeControl operations and the API Guide itself has the potential to execute code directly on TimeControl.  This can and should be prevented for most users by not giving API security authentication to most User Profiles.

Creating API code and executing it should be done in a sandbox first to make sure it will deliver the functionality you expect.  It’s a powerful tool for integration with other systems to extend functionality but should be used with care and caution.

This is the most flexible type of documentation we’ve ever included in TimeControl and it’s worth a look.