toggl-vertec

toggl-vertec

toggl-vertec offers two functionalities:

1. It flattens and synchronizes your vertec projects into toggl projects to allow you to use them for your bookings in toggl.
2. Subsequently you can do all your bookings in toggl and toggl-vertec synchronizes them back to vertec.

toggl-vertec only does a one time synchronization of new toggl time entries. It will never update or delete existing time entries in vertec, however you can easily do this manually if required.

Installation & Configuration

In order to install toggl-vertec globally on you local machine, execute:

npm install -g toggl-vertec

Afterwards you can toggl-vertec from everywhere:

toggl-vertec

Alternatively to installing it globally you can also run toggl-vertec using npx:

npx toggl-vertec

Initially toggl-vertec will ask you to enter the vertec xml server url, the vertec auth url, your vertec user name and your toggl api token, which can be found in your toggl profile.

Initially toggl-vertec will also automatically sync your projects from vertec to toggl.

Usage

In order to synchronize vertec projects to toggl execute:

toggl-vertec -p

All your vertec projects will be added to your toggl projects list. You can safely delete projects which you do not want to book on right now, they will be recreated once you synchronize again. In order to omit recreation you can black list projects, phases and activities in the configuration.js file which can be found inside the toggl-vertec app data folder. Per default all projects are named 'xxx (PROJECTCODE/PHASECODE/ACTIVITYCODE)' in order to avoid synchronizing possibly sensitive information to toggl servers. You can safely rename the project's name (xxx) in front of the brackets, toggl-vertec only needs the codes in the brackets in order to synchronize back the time entries later on. To see how to synchronize phase descriptions also, see additional options.

Now you can start booking in toggl. Before you synchronize back to vertec, assure you correct all entries to be multiples of 30 minutes, as toggl-vertec ignores them otherwise. If you do not actually rely on the time tracking, the easiest way is to use toggl in manual mode.

In order to synchronize toggl time entries to vertec execute:

toggl-vertec

toggl-vertec reads all toggl entries of the last 35 days and synchronizes them to vertec. Once an entry is synchronized it adds the 'vertec' tag to the time entry in toggl in order to not synchronize it again later on. Time entries only get synchronized if a project can be found which has been synchronized before to toggl (see project cache). Time entries to be synchronized must be multiples of 30 minutes, otherwise they are ignored. Time entries having the 'vertec' tag are not being synchronized (again).

toggl-vertec will always ask you for your vertec password before accessing vertec. If you want to avoid that, you can add your password to the configuration.js file inside the toggl-vertec app data folder, however for security reasons this is not recommended.

Additional options

Set the vertec xml server url:

toggl-vertec -v https://newvertecxmlserver.com/xml

Set the vertec auth url:

toggl-vertec -a https://newvertecxmlserver.com/auth/xml

Set the vertec user name:

toggl-vertec -u newusername

Set the toggl api token:

toggl-vertec -t newtogglapitoken

Synchronize phase descriptions:

Per default all projects are named 'xxx ([projectCode]/[phaseCode]/[activityCode])' in order to avoid synchronizing possibly sensitive information to toggl servers. You can also execute toggl-vertec project synchronization with the -d switch, which synchronizes the phase descriptions. Use this switch when there is no sensitive information in your phase descriptions.

toggl-vertec -d

Synchronizing phase descriptions is persisted in the configuration. In order to switch back to not synchronize phase descriptions, execute the project synchronization with the -n switch:

toggl-vertec -n

Possible pifalls and additional details

Company network

toggl-vertec must be able to connect to the vertec xml server, so you most probably need to be connected to your company network, unless the database is publicly exposed.

### 30 mins validation

Time entries to be synchronized must be multiples of 30 minutes, otherwise they are ignored.

### Project format

The vertec project in toggl can have a random name, however it must end with normal brackets, containing the vertec project, phase and activity code separated by a slash.

Random project name (PROJECTCODE/PHASECODE/ACTIVITYCODE)

Project cache

Note that manual adding of projects is currently not supported, unless you add them also to the local project cache which is located in vertec-projects.json inside the toggl-vertec app data folder.

Vertec tag

Time entries only get synchronized if they do not already have the vertec tag set in toggl. When you add a new time entry in toggl, it proposes recently added entries having the same name. If you select the proposal and add such an entry again which has already being synchronized, toggl also automatically adds the vertec tag. In this case you must manually delete the tag so that toggl-vertec recognizes it as not being synchonized yet.

Be aware, that if you remove the vertec tag from already synchronized entries they will be synchronized again. You can also use that to your advantage and edit already synchronized entries. However in this case you manually need to remove the previous time entry in vertec.

Update of already synchronized time entries

toggl-vertec does not update previously synchronized time entries, it only adds new ones. In case you want to do that you can manually delete the entry in vertec and remove the vertec tag in toggl and the entry will be synchonized again.

Disclaimer

toggl-vertec adds time entries to vertec using the xml vertec server. The xml vertec server is provided by vertec and does the necessary validation. Furthermore toggl-vertec does a very basic validation and only adds entries to known vertec projects, and which are multiples of 30 minutes. There is no guarantee, that all toggl entries get synchronized. You are personally responsible for checking that all entries have been synchronized, nothing got lost on the way and all time entries are valid. Be aware that toggl-vertec if executed with the -d switch synchronizes your vertec phase descriptions to toggl servers, which may be against your corporate or client policies. In order to avoid that behavior, execute the project synchronization with the -n switch (see also additional options). Furthermore your vertec codes are synchonized to the toggl servers as this is technically required. If this is an issue, you must not use toggl-vertec.