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).

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

XXX

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:

When you edit a WLA, the following fields can't be changed any longer:

• Field Type
• 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. This relation defines under which circumstances the WLA appears on a "Log Work" screen.

• 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 types 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.
  
  

Assigments

Depending on the WLA Type, a WLA can be assigned to one or more projects or one or more activity types.

Assignments are done via the respective icon in the WLA list as a separate step after creation of the WLA:

XXX

The assignment screen looks like follows (depending on WLA Type):

Assign Activity Types

Assign Projects

Mark one or more activity types (or projects) to assign or unassign them, click the respective button and save.

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.

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)

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 UPDATE, CREATE or DELETE, you won't be able to save.

A few parameters available within a JIRA issue or from ictime can be used to parametrize your query:

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.

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"
/>

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

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).