You can register a webhook using the WiseTime Connect API to be notified whenever a user posts time to your team. When that happens, WiseTime will send a POST request to your webhook, with a JSON payload containing information about the TimeGroup that was posted.
Once you have successfully processed the posted time group, respond with HTTP code 200. WiseTime will then let the user know that the time rows have successfully been posted.
Responding any 4xx HTTP code except 408 will tell WiseTime Connect that you are unable to accept this time group. The time group will be unposted in WiseTime, and the user will be shown an error indicator for the relevant time rows.
If you respond with any other HTTP code, WiseTime Connect will retry posting the time group to your webhook a number of times before eventually giving up. WiseTime will then unpost the time, and let the user know that the time rows couldn’t be posted. The user will be able to retry posting the time group again.
Here’s a sample TimeGroup JSON payload:
{
"callerKey": "80&1f1$b9fd1^",
"groupId": "5bf7dc15c815720001c55b82",
"description": "Prepare API service for deployment",
"totalDurationSecs": 468,
"groupName": "API Deloyment",
"narrativeType": "NARRATIVE_AND_TIME_ROW_ACTIVITY_DESCRIPTIONS",
"tags": [
{
"name": "3342",
"path": "/jira",
"description": "Deploy API to production"
}
],
"timeRows": [
{
"activity": "Code",
"description": "deployment.yaml - Visual Studio Code",
"activityHour": 2018112214,
"firstObservedInHour" : 9,
"durationSecs": 168,
"submittedDate": 20181123105324612,
"modifier": "",
"source": "WT_DESKTOP"
},
{
"activity": "jetbrains-idea",
"description": "api-server master - Main.java - IntelliJ IDEA",
"activityHour": 2018112214,
"firstObservedInHour" : 9,
"durationSecs": 120,
"submittedDate": 20181123105324612,
"modifier": "",
"source": "WT_DESKTOP"
},
{
"activity": "Code",
"description": "ingress.yaml - Visual Studio Code",
"activityHour": 2018112214,
"firstObservedInHour" : 10,
"durationSecs": 60,
"submittedDate": 20181123105324612,
"modifier": "",
"source": "WT_DESKTOP"
}
],
"user": {
"name": "Jane Dev",
"email": "jane.dev@email.io",
"externalId": "janed",
"businessRole": "Software Engineer",
"experienceWeightingPercent": 100
},
"originatingUser": {
"name": "John Dev",
"email": "john.dev@email.io",
"externalId": "johnd",
"businessRole": "Software Engineer",
"experienceWeightingPercent": 100
},
"durationSplitStrategy": "DIVIDE_BETWEEN_TAGS"
}
Type: String, optional
When you register a webhook, you can specify a caller key that you would like WiseTime to use when it calling the webhook. You can then use this field to authenticate that the request comes from WiseTime. This field will be blank if you didn’t specify a caller key when registering the webhook.
Type: String, required
A string that uniquely identifies the posted TimeGroup.
Type: String, optional
User description for this time group. This may be blank if the user did not provide a narrative when posting their time.
Type: Integer, required
By default this is the sum of the time log durations in seconds. It may have been edited by user before posting. To calculate the unmodified total duration, add the items from the timeRows array.
Type: String, optional
When a group name is created in the WiseTime console, it is assigned the name of the colour that is shown for the group in the user interface. For example, Blue Group. The user can rename the group to provide a more descriptive name. This field may be blank in the case that the user has selected a group of rows and posted that time without explicitly creating a group. It is therefore an optional field.
Type: String enum value, required
The possible values are:
NARRATIVE_AND_TIME_ROW_ACTIVITY_DESCRIPTIONSNARRATIVE_ONLYThe user may request that the time row activity information be ignored by the web hook receiver. In the usual case, the default narrative type is NARRATIVE_AND_TIME_ROW_ACTIVITY_DESCRIPTIONS.
Type: Array of Tags, required, possibly empty
An array of tags that were assigned to the time group. An empty array will be sent if there were no assigned tags.
Type: Array of TimeRows, required, non-empty
Activity time rows posted with the group. There will always be at least one time row posted.
Type: User object, required
Information about the user who posted the time group. If the posted time is associated to a User, then this field will be populated with information about the user who is the recipient of the associated time.
Type: User object, optional
Only relevant if the posted time was associated to a User, this field contains information about the user that posted the time.
Type: String enum value, optional
The possible values are:
DIVIDE_BETWEEN_TAGSWHOLE_DURATION_TO_EACH_TAGOnly relevant when the group has more than one tag. This instructs the endpoint whether time should be divided between tags (default behaviour), or if WHOLE_DURATION_TO_EACH_TAG is set, the webhook receiver is asked to post the full/undivided time to each of the tags listed in the tags array.
Type: String, required
The activity performed, e.g. “Meeting”, “Microsoft Word”.
Type: String, required
A description of the activity, e.g. the filename of a wordprocessor document being worked on.
Type: Integer, required
The date and hour, in UTC, during which the activity was performed, in the following format: yyyyMMddhh.
Type: Integer, required
The firstObservedInHour represents the minute in the activityHour when the activity was first observed. It will be an integer value between 0 and 59.
Type: Integer, required
The duration of the activity, in seconds.
Type: Long integer, required
The time at which the activity was submitted by the user, in UTC. The format for this field is yyyyMMddHHmmSSsss.
Type: String, optional
A modifier for the time row. Modifiers can be selected by the user when posting time, and can be any string value that makes sense to the connected system when posted. For example, a law firm might configure activity codes for the various activities that they have set up in their case management system, so that they can charge meetings and court appearances at different rates.
Type: String enum value, required
The possible values are:
WT_DESKTOPUSER_MANUAL_TIMEThis field describes the origin of the time row. Time logs can either come from the desktop client (WT_DESKTOP) or be created manually by the user (USER_MANUAL_TIME).
Type: String, required
The name of the tag.
Type: String, required
The folder path of the tag, e.g. /path/to/tag/.
Type: String, optional
The text that is displayed to the user next to the tag name in the user interface. For example, this could take the form of a matter description or a project name.
Type: String, required
The name of the user.
Type: String, required
The user’s email address.
Type: String, optional
The ID that the connector should use to refer to the user when talking to the system being integrated with WiseTime. This is set through the user’s team membership.
Type: String, optional
The user’s role, set through their team membership.
Type: Integer, required
Experience rating assigned to the user. This is a percentage value, between 0 and 100. You can use this value to apply a multiplier to the total posted time duration before sending it to the connected system. For example, you may want to send 20 minutes instead of 40 minutes for a junior employee whose experience rating is 50%.