Connecting to WiseTime

There are a few ways that you can connect your existing system to WiseTime. We have a range of pre-built integrations that you can plug into; you can use our API to create your own system integration; or we can create an integration for you.


Using an existing integration

Connecting to one of our existing integrations can take as little as 1-2 hours of set up work. Our current integrations include:

  • Inprotech, CPA Global

  • Patricia, Patrix IP Helpware

  • Jira Software

What do we need to know?

There are two simple questions we need answered in order to begin scoping an integration:

  1. How do we detect when you add a new case?

We need to know this information to automate the creation of tags for each new case in your docketing system, to enable WiseTime to seamlessly tag time entries that include one of your system’s case numbers.

For example, if your system is based on an on-premise SQL database, we will need to identify the database table and column(s) that new case numbers are added to.

Alternatively, if the database is hosted online or otherwise not accessible, what API should be called, to periodically obtain the latest case numbers from your hosted system?

  1. Where would you like the data from WiseTime sent?

When WiseTime data is “posted” to your firm’s team, we need to know where that information, about the duration, person, case number and description, should be sent to register in your time registration system.

Depending on what system you are using, this usually takes the form of a database table or stored procedure. We are available to assist you with further information in this regard, should it be useful.

What data can WiseTime offer?

The following data is, for example, available to be stored in your system as time is posted from the WiseTime system:

  • Total time sent

  • Group name of the time sent (if used)

  • Description of time sent (if used)

  • Detail of time entries sent (window titles)

  • The person that recorded the time

  • Any modifiers (such as, for example, ‘reduced rate’)

In customised integrations, in addition to the above information, WiseTime is able to determine additional output information. For example, a chargeable total amount - that can also be written to your case management system - based on further information obtained from your case management system, like hourly rate for the charging individual, discounts, etc.


Preparing to integrate

To prepare for WiseTime integration, please follow the steps below:

  1. Download our pre-configured .ova image for VMware ESXI 5.5+ environments (also available as .vmdk image). For Hyper-V environments, please download our pre-configured .vhdx image. For Xen Server, please download or pre-configured Xen-compatible image for importing into Xen. Download Links:

  2. After you set your network settings as required, please restart the network service: 'systemctl restart network.service'

  3. After that, reboot the host. Your network is now ready to use with the parameters you set.

  4. Make sure that /etc/timezone file exists and locale is set appropriately (eg. Europe/Berlin)

Once these steps are completed, our development team can use SSH to setup the integration.


Using our API

Supported API requests

Only 4 integration points are needed to fully integrate with WiseTime. These fall into two categories:

  1. Inform WiseTime about new tags

    1. Create tag

    2. Add tag keyword. Keywords are aliases that, when detected, will cause the tag to be applied to a time row

  2. Fetch new posted time rows from WiseTime

    1. Download posted time. Supports long polling (with a maximum wait time)

    2. Update posted time status. Used to inform WiseTime when posted time is received, processed successfully, or if there was an error processing the posted time

Protocol Support

The api specification supports multiple transport layers:

  1. HTTP / JSON

  2. HTTP2 / gRPC

The API is defined using the protobuf language specification, allowing clients to connect by their preferred programming language, including full support for Java, C#, Python, Go, C++, Scala and REST.

WiseTime API Files


Templating and Settings

Settings

Setting Name Setting Scope Setting Default

PUBLIC_ACTIVITY_TEXT_MAX_LENGTH

Core

0 (no limit)

INTERNAL_ACTIVITY_TEXT_MAX_LENGTH

Core

0 (no limit)

PUBLIC_ACTIVITY_TEXT_TEMPLATE_PATH

Core

absolute path of a default template file from resources in classpath

INTERNAL_ACTIVITY_TEXT_TEMPLATE_PATH

Core

absolute path of a default template file from resources in classpath

PUBLIC_ACTIVITY_TEXT_WINCLR

Core

false

INTERNAL_ACTIVITY_TEXT_WINCLR

Core

false

PATRICIA_JDBC_URL

Patricia

<< no defaul >>

Implementation Detail

  1. Use Apache Configuration 2 library

  2. Build tiered configuration model, where layered (last item in list having highest priority)

    1. Core Module

    2. Implementation Module (e.g. Patricia or Jira)

    3. User specified file location from fixed name property set in JAVA ENV or falling back to ENV VAR

      1. i.e. AGENT_CONFIGURATION_FILE_PATH

      2. File is loaded as a properties file in usual way

    4. Environment Vars (perhaps this is cleanest, i.e. added to docker compose spec)

    5. JVM System Properties

Templates

Structure for Extension/Configuration

There are 2 template files required: . PublicActivityTextTemplate (found at setting PUBLIC_ACTIVITY_TEXT_TEMPLATE_PATH) . InternalActivityTextTemplate (found at setting INTERNAL_ACTIVITY_TEXT_TEMPLATE_PATH)

We will define a core/base template for each of above. Then, an agent may override the default, by, for example, setting a different template for either or both of these. Lastly, at a customer site, we want to be able to, optionally, define a specific version of the template file(s) for that particular site. Freemarker is well maintained and used in Apache heavily, has features we need, is known by developers, so let’s use that.

Variables Available in Template Template Path

Variable Name (all inside userDayBundle) Variable Type Description

tagName

String

The case reference

actualDuration

Number

Sum of time in groupedTime bundle

userDefinedDuration

Number

By default, will by same as actualDuration. If user modified value in the console prior to posting group, it will differ from actualDuration.

modifierCode

String

Optional, if modifier is set.

excludeSegmentDetails

boolean

If posted via group, whether segment details were elected to be excluded

timeSegmentDate

LocalDate

narrative

String

Optional, if narrative provided (i.e. via group narrative can be provided)

userEmail

String

userExternalId

String

Optional, for example, a username in the system integrated with.

dayActivityItems

List

At least one item will be present. This is the list of the actual detailed time activity rows.

dayActivity.durationSecs

Number

If time was sent to multiple tags, this is the number of seconds AFTER time row split across those multiple tags.

dayActivity.activityType

String

Name of activity application but can include Reading etc. The @ pattern is removed in case of manual time items (and isManualTime will return true).

dayActivity.activityDescription

String

Name of activity window title but note will include user-typed description in case of manual time rows.

dayActivity.manualTime

boolean

Whether activity description is a manual time description.

dayActivity.firstTimeRecordal

DateTime

Set to start of time segment first appeared in given day, in 6min granularity (round backward).

dayActivity.lastTimeRecordal

DateTime

Set to start of time segment immediately after end of last segment, in 6min granularity (round forward).

Template Path

Path to template can be defined on several levels:

  • lowest level: there is default template in wt-agent-core that is used, when no alternative provided. It looks like:

<#if narrative has_content >${narrative}</#if>
<#if !excludeSegmentDetails>
  <#list dayActivityItems as activityItem>
${activityItem.firstTimeRecordal?date} - ${activityItem.activityType} - ${activityItem.activityDescription}
</#list>
</#if>
  • wt-agent specific template: every specific implementation of wt-agent can override default template. Typically specific template available on classpath of specific module and it overrides path. E.g. PUBLIC_ACTIVITY_TEXT_TEMPLATE_PATH=classpath:jira-template.ftl.

  • user-defined template: user can provide own template (typically it is saved in file system) and set it by setting environment variable or system property. Such config will have highest priority. E.g. PUBLIC_ACTIVITY_TEXT_TEMPLATE_PATH=/home/jenkins/template /public.ftl.

Duration Formatting

During formatting timelog it found to be useful to convert denormalized seconds duration to human readable string. E.g. 600 has to be 10m, and 3605 1h 5s. To achieve this wt-agent provides own custom duration formatter. It is available for every wt-agent implementation. Syntax: 

${durationSec?string.@duration}

Date and Time Formatting

Freemarker provides multiple way to format date. Variables available in template such as timeSegmentDate daySegment.firstTimeRecordal d , , aySegment.lastTimeRecordal can be converted to string in desired format. E.g.:

${activityItem.firstTimeRecordal string( "HH:mm")}
${activityItem.firstTimeRecordal date}

More options can be found in Freemarker docs: https://freemarker.apache.org/docs/ref_builtins_date.html

Process Steps

The generation of activity text from the template should follow this process:

  1. Creating Text

    1. convert UserDayBundle to java object/context for applying to freemarker context

    2. determine the correct internal activity or public activity template file

    3. use freemarker to use context + template file to create a text output

    4. trim activity text

    5. if "PUBLIC_ACTIVITY_TEXT_WINCLR" or "INTERNAL_ACTIVITY_TEXT_WINCLR" (as applicable), replace all linux line breaks with Windows CLR (see inprotech module for example)

    6. if "_MAX_LENGTH" is defined (for public or internal, as applicable), then if exceeding max, truncate to MAX_LENGTH - 3, and append '…​', leaving string size always no greater than MAX_LENGTH defined. By default, zero is no limit.

  2. Sending to time poster via interface

    1. add object containing String publicActivityText and String internalPublicActityText as parameter in postBundleToExternalSystem of TimeLogPostingService interface


API Case Study

JIRA Integration

WiseTime’s integration with JIRA, Atlassian’s issue & project tracking software, allows for agile & scrum project managers to automatically track project time & activity for each employee. This allows employees to continue to multitask throughout their day and properly identify the time associated on each project task by matching your JIRA issue keys (ticket numbers) and tagging them in your WiseTime Console. The teams time logs are then available for management to review on each ticket along with the total time logged. With the automactic time tracking from WiseTime integrated with JIRA you will see major improvements in forecasting and budgeting affecting the success of your projects.

Jira Integration Ticket Review