This feature has been introduced with ictime version 4.2.
Work Log Attributes (WLA) are en easy and powerful way to enhance your work logs with any kind of additional data you require. You can place one or more WLA on your "Log Work" mask, and can have a different set of WLA (or no WLA at all) depending on project and/or the Activity Type selected by the user.
What Is a Work Log Attribute
A Work Log Attribute (WLA) is a kind of "custom field" for work logs that can be placed on the ictime "Log Work" mask to collect any kind of data that is not part of the ictime default "Log Work" mask. At this moment, we support input text fields and dropdowns as field types, and for dropdowns, data (key-value-pairs) can be managed as static data or can be retrieved from a database with a dynamic query. A WLA can either be related to an Activity Type and/or a JIRA project, so it only appears for certain projects and/or after a user has selected an activity type. Data collected with a WLA is available via the export functionality of ictime Reporting (or via a separate add-on that exposes a REST-API for ictime, see API).
At this moment, Work Log Attributes are neither searchable nor displayed in the details of a report, their values can only be exported (or used via an API; see API).
Some typical use cases for a WLA are:
- If you do not (or do not only) need information about time spent to charge your work, but have other quantity-based criteria, like pages written, hard disks erased, images converted, disks burnt, ..., you can use a WLA. This way, ictime does not work as a mere time tracking solution any longer, but becomes a kind of general service recording tool.
- If you need aditional criteria like travel expenses, km travelled or fixed cost for a certain job, you can use a WLA.
- If Activity Types are not detailed enough for your purposes and you would need another hierachy level below, you can do that with a WLA.
- If you need accounting information that needs to be tracked on the level of single work logs (so that you can't use a custom field on issue level), you can use a WLA.
Create & Configure Work Log Attributes
WLA List
For description of all fields, please see below.
Once you have created a WLA and it appears in the list, the following operations are possible:
Operation | Description | Remarks |
---|---|---|
Assignments | Depending on the type of WLA ("ACTIVITY TYPE" or "PROJECT"), here you can create/edit the assignments (relations) of a WLA to either activity types or projects. For details, see below. | |
Edit | Edit the WLA. For details, see below. | |
Delete | You can delete a WLA if is is not used (has no assignments and no work logs with this WLA exist). If it is no longer possible to delete a WLA, you can still deactivate it (see below). |
Create & Edit WLA
To create a new WLA, click the respective button on top of the screen:
The following screen will be displayed:
Depending on your choice of WLA Type, you get more/different options:
For the Field Type DROPDOWN, there are also additional and different options, depending on your choice for the data source:
Field | Description | Remarks |
---|---|---|
Name (Internal) | An internal name for your purposes. | |
Label (Screen) | Name like it will appear on the "Log Work" screen. | |
Mapping ID | If you are connecting to an extrenal system to retrieve data for your WLA, you can use the external ID as mapping ID for the WLA (otherwise, the external system would need to use the ID of the WLA). | |
Field Type | Input text or dropdown. | Dropdowns have two different ways to get populated with data (see "Data Source"). |
RegEx (Field Check) | A regular expression that enforces a defined format for the user's input. | Not applicable to dropdowns. |
JNDI | If you want to manage dropdown values dynamically via a database query, you need to define your JNDI here. See http://en.wikipedia.org/wiki/Java_Naming_and_Directory_Interface and below. Here, you just enter the name of your JNDI. | Only applicable to dropdowns where dropdown values should be dynamically retrieved from a database. |
SQL Query | The query used to dynamically retrieve dropdown data from an (external) database. | Only applicable to dropdowns. |
WLA Type | There are two different types of WLA that distinguish as follows:
It is not possible to create a WLA that has relations to activity types and projects at the same time. However, for certain use cases, it is possible to create a WLA with type "PROJECT" and to create a real dependency from activity types. This requires the "Depend on Activity Type" checkbox being checked. For more information, see below. | For details, see below. Can't be changed later on. |
Assignments | The activity types or projects (depending on WLA Type) this WLA is assigned to. Assignments define if (under which conditions) the WLA appears on the "Log Work" mask. For more information, see below. | |
Order | If you define multiple WLA and multiple WLA might appear on the "Log Work" dialogue, you can define a sorting order for all WLA here. Sorting applies across all WLA, regardless of their type. All WLA will always display below the "Activity Type" dropdown and above the "Description" textarea. The order applies within different WLA on the same screen. | Numerical, like 10, 20, 30 |
Active | If the WLA is currently active. | It is not possible to delete a WLA that is in use. You can only deactivate it. If you deactivate a WLA, all data is kept, but the WLA is no longer available for new work logs (when editing a work log, you can either not save or need to clear/delete the data of this WLA). |
Mandatory | If the WLA is a mandatoy field in the "Log Work" mask. | |
Global | If the WLA is globally assigned to all activity types or all projects (depending on WLA Type). A global assignment automatically includes future projects or activity types that do not exist at this moment. See below. | |
Depend on Activity Type | By default, a WLA Type "PROJECT" is directly displayed in the "Log Work" mask for all projects this WLA has been assigned to. "Depend on Activity Type" changes this behaviour and the WLA will only be displayed (in the "Log Work" mask for all projects this WLA has been assigned to) after the user has selected (any) activity type. Usually, this setting only changes the field's display behaviour. However, if you combine this setting with field type "Dropdown" and use a dynamic database query to populate the dropdown, you could create a real dependency of this WLA from project/s and activity type/s at the same time. See below. | Only applicable for WLA Type "PROJECT". |
When you edit a WLA, the following fields can't be changed any longer:
- WLA Type.
WLA Types
The WLA Type defines a relation of a WLA, either to one or more projects or one or more activity types.
- ACTIVITY_TYPE: This type is related to one or more activity types. It only appears if in the "Log Work" mask, if one of the activity type assigned is selected by the user.
- PROJECT: This type is related to one or more projects. It only appears in the "Log Work" mask for these projects.
It is not possible to create a WLA that has relations to activity types and projects at the same time. However, for certain use cases, it is possible to create a WLA with type "PROJECT" and to create a real dependency from activity types. This requires the "Depend on Activity Type" checkbox being checked. For more information, see below.
Assigments
Depending on the WLA Type, a WLA can be assigned to one or more projects or one or more activity types.
Depend on Activity Type
See example query below.
Configuring Dropdowns
Static Data
If you have static data, i.e. a limited set of data that will be the same wherever the dropdown appears (and usually remains stable over a longer period of time), you should manage the key-value-pairs for the dropdown manually.
If you have selected the respective option, you can enter the static data:
The following formats are supported:
key1=value1;key2=value2;key3=value3;
key1;key2;key3
If you do not define a value, the key will be displayed as value. Data is trimmed if there are empty spaces at the beginning or the end.
Dynamic Data (SQL Query)
If you want to work with a query/dynamic data, you first need to define your JNDI, see below.
Using dynamic data means that
- you can use any kind of data source (database) accessible from your JIRA installation to populate your dropdown, e.g. with larger amounts of data or data that changes more frequently,
- you can filter data of your dropdown retrieved by an external data source by a few additional JIRA parameters (like projekt key),
- you can create a dependency of a WLA Type "Project" from an activity type (for specific use cases; see below).
You can define any kind of valid SELECT statement; if you try to use other common statements (UPDATE, CREATE and DELETE), you won't be able to save.
You can also work with a stored procedure. Keep in mind that in this case, ictime does not have any control over the kind queries that are executed, so it is up to you to ensure that you are not changing or deleting data.
A few parameters available within a JIRA issue or from ictime can be used to parametrize your query:
Field | Description | Remarks |
---|---|---|
projectKey | Current JIRA project key (retrieved via the JIRA issue). | |
projectId | Current JIRA project ID (retrieved via the JIRA issue). | |
userKey | Current JIRA user. | |
activityTypeId | Activity type currently selected. | Available after the user has selected an activity type. |
activityTypeExtMapId | External Mapping Id of the activity type currently selected. | Available after the user has selected an activity type. |
Example 1: Filter by Current Project
A simple example is using the JIRA project key to retrieve project-specific data (of course this would require that the JIRA project key is available in the database you are using to get the data):
SELECT contract_id AS `optKey`, description as `optValue` FROM mydb WHERE :projectKey = :projectKey
This example query would fill the dropdown with those contracts that are assigned to the project the current issue belongs to.
Example 2: Filter by Current Project and Activity Type
The following example shows howy ou could create a dependency between a WLA of type "Project" an an activity type (this example strictly requires that the WLA is of type "Project" and that the checkbox "Depend on Activity Type" is ticked - otherwise the WLA would load/display before the activity type has been selected by the user so that the query can't work):
SELECT contract_id AS `optKey`, description as `optValue` FROM mydb WHERE :projectKey = :projectKey AND :activityTypeExtMapId=:activityTypeExtMapId
This query does basically the same like the first example, but only after an activity type has been selected. Provided that your database shows a relation between contracts and projects and activity types (= contracts are assigned to projects, and only for certain activity types, it is desired/required to select a contract), you will only get the contract selectbox if you are working on an issue of a project with contracts, and the selctbox will only show the contracts of the current project, and only those applicable for the activity type selected by the user.
JNDI
To define the database you want to use to retrieve data for the case of Dynamic Data (see above), you first need to define your JNDI and when you configure the WLA where you want to use this data source, enter the name of the respective JNDI. You can define multiple JNDI with different names for multiple purposes.
Usually, JIRA comes packaged with a Tomcat, an open source software implementation of the Java Servlet and JavaServer Pages technologies. You might want to have a look at the following documentation of the JNDI topic for Apache Tomcat 7.x: http://tomcat.apache.org/tomcat-7.0-doc/jndi-resources-howto.html#JDBC_Data_Sources
To cerate a new JNDI, go to
[JIRA_HOME]/conf/server.xml
and add the following code (adapted to your specific configuration) to the file:
<Resource name="jdbc/TestName" auth="Container" type="javax.sql.DataSource" username="dbUsername" password="dbPassword" driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://hostname:3306/databaseName" />
Field | Description | Remarks |
---|---|---|
Resource name | individual name ("jdbc/" part is mandatory and must go first) | This value needs to be entered in the WLA mask in the "JNDI" field. |
username | user name for this database | |
password | password for this database | |
diverClassName | class name for the driver of your database (example shows MySQL) | |
url | URL to your database |
There might be more parameters available (refer to the specification of your servlet container), you might set them according to your needs.
Implications of Changing or Deleting Dropdown Data
This chapter is basically referring to
- changing keys of key-value-pairs (you should never do that). If only values are changed, this will also have an effect (on users and on data provided/saved), but does not require specific handling.
- taking away (deleting) keys (key-value pairs).
Adding new keys (key-value-pairs) is a non-problematic change.
Changing keys or deleting keys has an impact on existing work logs (that have been using the respective WLA) when they are edited. If you don't edit such work logs, nothing will happen. Data already stored is not touched and would be exported (or provided via API) as is.
If you delete or change a key and later on try to edit a work log that had been saved using this key (having selected the entry with this key), you will get the following behaviour:
The (!) indicates that this is an entry that no longer exists. However, you will be able to save this work log with this entry. Once you have made a change (selected another entry) and saved, the entry with the (!) will be gone. If you did not delete the respective key, but change it without changing the value (you should not do that), in addition you will now see another entry with the same value:
Log Work with Work Log Attributes
Create Work Logs
A maximum of 10 WLA are supported for a work log. You can create as many WLA as you want, but it is not possible that the "Log Work" screen displays and handles more than 10.
Edit Work Logs
You can now make a different choice and save, or you decide to leave all data untouched and cancel. However, you will never be able to save a work log (i.e. you won't be able to make other changes and save).
Moving Issues in JIRA: Work Logs with Warnings
If you move issues in JIRA between different projects that have a different WLA configuration, and these issues have work logs with WLA data, these work logs are no longer consistent, because they contain WLA data from the original project that does not match with the WLA configuration of the target project. As a result, reports might generate incorrect data for accounting purposes. We already know a similar problem when moving issues in JIRA between different projects that do not match as regards configuration for Activity Types, Rounding Rules and Teams/Price Lists. This problem is addressed with a specific tool to fix such work logs, see Fix Work Logs (Warnings).
Limitations & Known Issues
At this moment, the main limitation is that WLA are not searchable in Reporting and that values for WLA fields are not displayed in reports, but can only be exported or used via an API. These topics will be addressed in the future, but there are technical limits as regards performance and display (imagine the report details screen for a report that contains multiple projects and these projects have multiple different WLAs, the grid would get a dozen or more additional columns).
Another limitation is that a WLA does not know anything about it's own content, so it is e.g. not possible that ictime aggregates/summarizes values that are numbers. This is also on our roadmap. For the moment, you can do everything with the data based on exported .xls files or you use an API to work with the data in a different system (like your ERP system).