Purpose

To simplify the work involved in establishing federation between systems.

API Definitions

timeld

This is currently captured in here in the timeld docs, but will be reproduced and expanded here to provide relevant additional examples as needed.

Ponder Source PreJournal

There is an instance of Prejournal at https://time.pondersource.com that tracks timesheet data for Ponder Source team members, and for other teams (m-ld, Muze, EvoluData, etc.), if those data have been transmitted to PreJournal.

Members of the Ponder Source team (@ishifoev, @michielbdejong) can administer the server using the scripts from this private repo which contains password settings etc. For generic instructions on how to administer a Prejournal server, see the main website of the Prejournal software project.

If you want to share your personal timesheets through time.pondersource.com, ping @michielbdejong or @ishifoev in the Federated Timesheets Gitter channel to get an account, and then access its API as described in the Prejournal docs section about time-pondersource-com usage.

Note that Prejournal (or at least this current configuration of it) uses a Source-as-Truth architecture, and its database contents will be reset from the original source documents periodically. This means write operations that you push to its API don't stick! You can push data to time-pondersource-com but it will only exist until the next time the server is reset. It will then reload its data from your system using API "pull", and (if all pushes were correct) reach the same state as before the server reset.

Ponder Source will be loading real live data into this instance once it's got appropriate access control in place.

User identities will also be created for the other two Tier-2 systems in the network (timeld and WikiSuite).

WikiSuite

https://gitter.im/federatedbookkeeping/timesheets?at=626a7fead30b6b44ebc2a8ab

Demo site you can use to review: https://timesheet.dev3.evoludata.com/ - register, login and follow instructions on the home page. By default, we have an empty Tiki installation with timesheets (https://profiles.tiki.org/Timesheets) profile applied. This creates a sample tracker app to track user's time, 2 tabular formats to import/export (from Time.json format and full/complete format to be used for WikiSuite - this latter one is going to evolve to cover the data model we come up with). Tabulars can be used to import/export to/from csv/json format. URIs are automatically generated and used for deduplication. APIs to import/export are also available: https://timesheet.dev3.evoludata.com/api/#/default/get_tabulars__tabularId__export and https://timesheet.dev3.evoludata.com/api/#/default/post_tabulars__tabularId__import - auth tokens are required, so if you want to use them, please register and let me know to create tokens for your users (currently admin-only task))

Each registered user on timesheet.dev3.evoludata.com has access to manage tabular formats: https://timesheet.dev3.evoludata.com/tiki-tabular-manage - these formats are the key functionality to export/import data from/to Tiki. We have setup Prejournal and Timeld specific formats to handle corresponding APIs. If you wish to support native Tiki format, I'd suggest you use the Full format (https://timesheet.dev3.evoludata.com/tiki-tabular-list?tabularId=6) or clone it and update to suite your specific fields and format. Tabular format allows you to specify data format (JSON, CSV or NDJSON), specific tracker fields to include in export/import, formatting for each of the fields and optional link to external API.

Here's an example Tiki API usage to export timesheet entries via the full tabular format:

curl -X 'GET' \
  'https://timesheet.dev3.evoludata.com/api/tabulars/6/export' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer 08c78....'

Response:

 cache-control: no-store,no-cache,must-revalidate 
 connection: Keep-Alive 
 content-disposition: attachment;filename=Timesheet_Fullexport_full.csv 
 content-type: text/csv; charset=utf-8 
 date: Fri,19 Aug 2022 13:30:00 GMT 
 expires: Thu,19 Nov 1981 08:52:00 GMT 
 keep-alive: timeout=5,max=100 
 pragma: no-cache 
 server: Apache 
 transfer-encoding: chunked 
 vary: Authorization 

Extract from Timesheet_Fullexport_full.csv file:

URI,User,Project,Task,Description,"Start Time","End Time",Date,Duration,"Minutes (Calculated)","Hours (Calculated)"
https://timesheet.dev3.evoludata.com/api/trackers/2/items/45,victor,federated-timesheets,,"Meeting with Michiel, George and others to discuss initial steps for defining the data model of the federated timesheets and other complexities","Thursday March 10, 2022 00:00:00 UTC",,2022-03-10,"1 hour, 9 minutes",69,1.15
https://timesheet.dev3.evoludata.com/api/trackers/2/items/46,victor,federated-timesheets,,"add WkiSuite timesheet example from avan.tech for federated timesheets","Friday March 11, 2022 00:00:00 UTC",,2022-03-11,"30 minutes",30,0.5

Here's an example Tiki API usage to import timesheet entries via the full tabular format:

curl -X 'POST' \
  'https://timesheet.dev3.evoludata.com/api/tabulars/6/import' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 08c78...' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@test_import.csv;type=text/csv'

Contents of test_import.csv file:

URI,User,Project,Task,Description,"Start Time","End Time",Date,Duration,"Minutes (Calculated)","Hours (Calculated)"
your-external-uri,victor,federated-timesheets,,"documenting API examples","Friday August 19, 2022 13:30:00 UTC","Friday August 19, 2022 14:00:00 UTC",2022-08-19,"30 minutes",30,0.5

Response from server:

 cache-control: no-store,no-cache,must-revalidate 
 connection: Keep-Alive 
 content-encoding: gzip 
 content-length: 74 
 content-type: application/json 
 date: Fri,19 Aug 2022 13:35:13 GMT 
 expires: Thu,19 Nov 1981 08:52:00 GMT 
 keep-alive: timeout=5,max=100 
 pragma: no-cache 
 server: Apache 
 vary: Authorization,Accept-Encoding 

{
  "feedback": "Your import was completed successfully."
}

and you can review the created entries via the UI...