System Manual


Table of Contents


1  Install instructions

You are reading this now even if you're not a System Administrator - an unavoidable side effect of stand-alone testing versions. So, please accept my apologies for this rather geek section!
Please Note:
  • Back button will not always give the expected results in Ajax as it is now.
  • Ajax gets stale with time so the system is set to reconnect if left alone for 20 minutes. If you experience some obscure issues after having left it alone for a while, please go to Home, refresh site and try again, preferrably after you double check that it shows something like "http://bigsig:9000/home?0x=484270" and not "http://bigsig:9000/edit/object/xxxx" (then change that to "http://bigsig:9000/" before refreshing) - that usually does the trick for the same reason.
  • The screen-shots in this manual may have discrepancies for certain terms as we actively tweak these just now and will not update the shots for the manual until they're final. Text should be up to date though.
  • As we're still in development mode we cannot guarantee that all builds will be backward compatible with worlds built with earlier builds. I have good experience in taking screen shots / print of the different builder interfaces - that makes a rebuild real quick and painless.
  • Make backups during a build - just in case - go to the LW interface and choose File from the navigation and do a backup. The backup resides in time-stamped folders in the backup folder in the data folder.
  • Always use Test Mode when you have built or made changes or tweaks when trying those out first time!
Table of Contents


2  Read this first: Basic concepts - how to build the model

Please Note:
  • Please forget all you know about applications, departments, positions and business rules. We'll get to that later - that can be virtualised if need be but the system does not need it.
  • Focus on only one thing: What value is to be created and how is that best done.
Table of Contents


3  "Navigation" (Home area)

The only allowed area for most users, "admin" has access to the second area, "builder", as well as to "Users" - restricted areas for most users. All screenshots herein are for user "admin".


3.1  "Home"

A few navigation choices - mainly the area where Tasks shows up, where reports can be displayed and where flows can be started:
Same as above but now in "Test mode":
With a task, a user specific calendar appears, drag the task by the little icon on right into any date or time and save - this for a graphical overview. Add any non-system tasks (placeholder) manually as well if need be. A star next to a task indicates that it's not yet been added to the calendar. If you have a task in the calendar and want to change the date/time simply drag the task (from the original task list) to the new spot. The placeholder tasks can be deleted of course, while the system tasks simple disappear when completed as it should be!
Table of Contents


3.2  Reports

Allows access to all reports the user have been given rights to (in Users). The reports are created on-the-fly using templates defined in Accounts or Reports. Time and sort order is tweakable:
And can look like this (accounting report) - note the little "X" in the right hand corner; it's how you wipe the report from the interface. Clicking on another report will merely replace it:
Or this (related things report):
And the setting tweak interface can look like this:
Table of Contents


3.3  Start Flow

Any flow that the user has been given start privileges to is available here as long as user has "Run" rights:
When started a flow will give tasks to the assignee (showing up in his/her Home) - and each task has "Complete" (finishes the task and sends to next assignee) and "Save" (saves work done and leaves as active task in "Home") options, and if set in "Flows", a right to "Reassign" as well. In addition there is a "Restore checkpoint" option that will revert the flow to last Display and Fillout task whoever had that. Give the flow a title when starting as well, this makes looking at specific flows easier under the "Active Flows" tab!
Table of Contents


3.4  Workorders

If given access to this area you will be able to see who has what task currently and even step in and do their task. Not an area for all:
Table of Contents

3.5  Users

The area to set user rights, passwords and other details. Normally such can be set in a proper workflow built for that purpose leaving this interface only for manual intervention if need be.
Overview:
User "Guest":
"Reports" allows setting of what reports that will be visible for the user.
"Capabilities" is where you set what navigation choices shall be available as well as right to "Run", i.e. start flows.
"Visible Flows" is where you give right to start chosen flows:
Table of Contents

3.6  Test Mode and backing up during builds.

When clicking on Test Mode that goes red to indicate that you're now in Test Mode. In Test Mode you can do whatever you like without messing with the system. Exit Test Mode and it reverts to the system prior to entering Test Mode.

But just to be on the safe side, please do backups using the LW interface (backup is under file in navigation) which will make a backed up system file (world) into a time stamped folder inside the "Backup" folder inside the "Data" folder in the system folder (Typically - Win: C:\Program Files\Thingamy-2.2.xx\data\ - Mac: Directly inside the "app".) so note the time or rename the folder to something you could recognise. I always make folders named "Finished without data" and so forth.
"Home" when in Test Mode:
Table of Contents

4  "Builder" (Admin area)

4.1  Strategy

This is OPTIONAL - and have no direct bearing on the system. It is meant solely as a reminder of one particular part of any strategy - overall or only for a small group: What value are you going to deliver?

The moment you have defined a value - say for a hospital I would suggest "Cure medical conditions you know what your first "thing" (object/class) you will have to define - the virtual type of object named "Medical condition". And with that the next thought is "what other objects do I need to cure it?" - obviously a Patient comes in handy, some surgery objects, some x-ray things, blood tests and so forth. Nothing more that a reminder and starting point this, use it or do not use it.
Table of Contents

4.2  Things

Thing is another name for "Class" in this interface: Here you will define the "cookie cutters" that is used to stamp out unique things or objects during a flow. Every time you add a patient you use the Patient thing defined here that allows you to add data to the property fields defined in that thing/class.

4.2.1  Important note re. Properties vs. Relations

Properties: Fields holding details making up a representation of a singular unique real world object - tangible or virtual. Examples are First and second name, Date Of Birth and Social Security number.
Relations: Separate information that relates a subject to another object and vice versa. Examples are Address (relation to a house, another proper object), Children (relation to other person objects) and Car (relation to a Car object).
The important difference in use inside thingamy (and elsewhere for that matter): When you "need" to find an object inside the database one will use a combination of "filters", making up a query. This is possible with both methods - list every object of "person type" that lives in London and that has two children.

The big difference is that a property can be found in one of the objects, sometimes the second object does not even exists in the system (house/address for example). This requires reconciliation over the objects that contains a property that should be the same - address for the family members say.
Relations on the other hand gives at least as much information, but now the other object (house/address) would also know who's related to it - and queries can go both ways. Even to another level like "list all persons that inhabits houses built by builder X". This does away with reconciliation as well as you only have to keep one object (house/address) up to date and only change relations for a person when he moves from one house to another.

"Rule": If possible use relations, if never-changing and/or is a unique describer for a unique real world object, use property.

4.2.2  The Things

The Thing interface has four different boxes:
  1. Things: Here you define the Things by choosing what parent thing it shall inherit properties from as well as adding more properties and setting how the visible Title / Name for a Thing will be generated.
  2. Semantic Things: Sometimes you do not need properties in a Thing, just the collection of Things like "Countries" or "Tags" or anything you'll find useful. The "Instances" of thes Semantic Things, or "objects" of this "class" must be added directly in here.
  3. Special Property Types: User created property types that can be used when defining Things. 1-2-3, Male-Female, that kind of stuff.
  4. As a reminder / navigation tool: We have included a hierarchical navigation of the Things defined showing what Things are built on what other Things (and thus inherits the properties of the Parent Thing).
Copy or Delete: Hook off the tickbox under Delete and press delete. Ditto for Copy - which creates a carbon copy of the Thing in question named "xxx copy 1". Note that a copy of a Thing will create a new set of relations (see those) identical to the relations for the copied Thing but with the copied Thing as new Object or Subject, so take a look at the relations and update their names and settings if relevant:
The system comes with some default type things that can be used as basis for other user defined things. If you forget what they entail (what metadata they already have) you can check them out (but let them be otherwise). The types are:
Here we are in the edit interface of a thing: First you set the name (Title) of the thing type (class), then you choose what other thing type you will build it on - inheriting all properties - and relations! - from that of course.
Add properties by drag and drop or use the '+', the shuffle them around if need be (ordering is set here) and name them.
"Make custom name" is recommended as it sets the "Title" field that every thing has as default. When you want to choose a specific thing in a flow or display something in a report the name of it comes up as human-readable and not as "[Type] Car 45677":
A Semantic category edit interface: Sometimes you do not need properties in "things", more like categories or rather objects that we all know any thing in your system could be related to: "Patient lives in France" - here you have a Patent objects already and why bother creating a full-fledge France object - that's where "Semantic things" comes in - create one named "Country" and make instances like France, Germany, USA etc. Anything is allowed here of course - including tags for those who cannot part with such.
A Special Property: Sometimes user defined properties comes in hand - like 1-2-3 or whatever.
Table of Contents

4.2.3  Properties

Property types used in Things - both as icons for drag and drop or appearing when '+' is used:
Table of Contents

4.2.4  Import of data tables

Please ensure that you have a full backup of the "data" folder so you can revert when (not if) you make a mistake first time!
The function is as follows:
  1. Create a csv or xml file of the data tables to import.
  2. Have a suitable Thing into which you will import, no need to have exact same fields as this can be set during import.
  3. The imported file will be placed in the folder "files/md5/" in the "data" folder.
  4. Then you will have to map fields in the system "Thing" chosen to imported columns.
Add a cvs or xml file:
Choose a file from your own hard disk and click add:
Choose type of file and to which "Thing" it will be mapped to:
Map the fields in the incoming file to the fields in the "Thing"":
Then the import starts which might take a bit of time, but when the spinning wheel at bottom right stops spinning you're there.
Table of Contents

4.3  Relations

The second part of three to create the basis for a flow: Now you have the things, now there is a need to add knowledge to things so you can find the right thing at the right time during a flow as well as to be able to create meaningful reports and accounts.

The relations are defined as N-triples - "subject, predicator, object" - "Sig, lives in, France" as well as the inverse "France, have inhabitant, Sig".

NOTE: Relations are also inherited by things using other user created things as basis. Say you have a "Person" thing, then creating a "Client" thing using "Person" as basis. Then relations to a "Person" will include "Clients", while relations to a "Client" will not include "Persons" or other "Person" derived things. Inheritance comes from parent obviously:
The edit interface for a relation:
Table of Contents

4.4  Flows

The third part of three to create the basis for a flow: Now you have the things and the relations between them, time to create the flows where you manipulate the things in order to add the value your strategy sets out.

I would suggest at this stage to simply try. There are no rules. As the system have a couple of operators - Flow-loop and To-another-flow it will be smart to cut up flows into smaller flows and use those operators to link them. As any flow often have parts of it being identical to parts of other flows it's always smart to create a "library" of flow snippets that can be used in many places.
Copy or Delete: Hook off the tickbox under Delete and press delete. Ditto for Copy - which creates a carbon copy of the Flow in question named "xxx copy 1".
Two main things to start with:

1. The Variables which are "placeholders" for things allowing you to change what or who the variable represents during a flow - like changing what physician shall do the next step, that way you can use the same part of the flow over and over again just choosing a different variable "MD" (which could be set as the assignee).
[NOTE: Set type of thing the variable shall be if possible as it allows the system to present you the right property and other choices.]

2. The flow - which you build by drag and drop or using the '+'. The flow is on "levels" - i.e. if you use a "Choice" (or multiple choice, multiple branch or simple branch) you will end up one level "down". As many levels down as you want. When the flow in a lower level branch is finished it will go up one level and do the next event and so forth.
Table of Contents

4.4.1  Instruction colour coding

Simple:
Table of Contents

4.4.2  Instructions in detail



Thing-maker:

Entrypoint: Set this in any instruction if you want to loop or entry here from another flow.

To edit: Choose expand/hide all if you'd like to do all in one go or simply click on the icon. When closing it it also saves your changes.

Type: Is the type of thing you use as template or cookie cutter.

Result Variable: Is the variable this specific instance of the class, or specific thing, will be assigned to in the flow at this point:
Display/Fillout:

A most useful operator/instruction as this is what you use to allow users to see information as well as add data to thing properties - workorder + all required information + toolset - all in one go.

Add in the sequence you want to show it:

Text: Any text - typically some instruction or helping message.
Fillout: Here you add the properties to be filled out by the assignee and the relations to be chosen.
Object/value: Just like the Fillout but now only displaying.
Report: Set any report so show directly in the task. Often not required as reports are available at all times without messing with the flow (they display on bottom of screen).
Assigned to: Who's getting this task? Either a specific user or a Variable if of user type.
Can reassign: If ticked the assignee can choose to reassign to another user during a flow.
Show relations as objects: Ticked off the set relations in an object display will show as full objects showing all properties. If not only the relation will show.
Choice:

As the title says - here you can choose between two or more paths/branches:
Here you set the assignee and add as many choices you want:
Here inside one of the choices where you can define any type of sub-flow:
Select:

This allows you to select any thing and assign it to a Variable.

Options: Choose any combination of [Type] and [Variable] - that would give you all things of [Type] that are related to [Variable]s:
Multiple-choice:

As the title says - here you can choose two or more paths/branches. Note that all events herein will have to be finished before the branch flows moves to next event. [NOTE: Keep in mind that if you let many different assignees manipulate the same thing only the last one will survive! This is for different things to be manipulated in parallel.]:
Here you set the assignee and add as many choices you want:
Then as with Choice, inside one of the choices you can define any type of sub-flow.


Multiple-branch:

As the title says - here you can pre-set two or more paths/branches. Note that all events herein will have to be finished before the branch flows moves to next event. [NOTE: Keep in mind that if you let many different assignees manipulate the same thing only the last one will survive! This is for different things to be manipulated in parallel.]:
Here you set the paths you want:
Then as with Choice, inside one of the choices you can define any type of sub-flow:


Thing-modification:

This allows for any changes to properties of any thing to be changed without any assignee involvement:


Simple-branch:

As the title says - here you can pre-set one paths/branches. This is mainly for house-keeping purpose:
Here you build the flow happening in this path/branch:


To-other-flow:

This allows sending off the current flow into another then wait for that other flow to complete or keep on. [NOTE: this operator actually creates another flow so use it with extreme care inside same flow - i.e. big logic exercise it is - otherwise you'll be having quite a few orphan flows going on!]

Flow: Choose what other flow to go to. Then update so you get the right choices.
Wait for completion: Yes - then it will wait for the other flow to finish and even accept new variables (see mapping below), No - then it'll let the other flow go in parallel, no return mapping necessary then.
Variable/ReturnVariable assignements: As other flows may have different names on variables this will be required - but keep in mind (IMPORTANT) that mapping variables to and from variables of a different [Type] would not work at all!:


Flow-loop:

This allows a loop to any other entrypoint in the same flow. This one is red as it is a task with an assignee who get's a question (Title) to which he/she will have to choose Yes or No. If no then the flow goes on as usual, if yes the flow is moved to that other entry point event:


Container Transfer:

Here you can preset or let an assignee choose an amount to be transferred from one Container (or Money) type thing to another. Example: Move a sum from a Bank Account (Money type) to a Payable (Money type created when purchasing something with initial amount = payable) - this will allow you to trace history and at all times see how much you still owe for a particular purchased item. Move four pills from Medication Package (type Container) to Medication (type Container created when a medication is prescribed) - this will allow you to trace every medication for a patient knowing when and how many pills each time and from precisely what package.
From: Specify from container.
To: ditto for to container.
Amount: If left open it will become a task (red) and the assignee must choose the amount. If a figure is set here it will happen in the background (blue).


Foreach:

In certain situations it can be useful to make changes to a batch of things. Note that the resulting variables are created during the flow and thus of little use in the flow after this point as the flow builder would not know what variables to use!


Assert Relation:

Normally the relations for a thing/object is set in a Display & Fillout Task, but sometimes a direct setting is useful to minimise a task and possible user errors. Just choose what relation and the two things/objects (being variables in the flow of course).


Retract Relation:

The opposite of Assert Relations.


Input:

For user input of any type to create a variable to be used in either Thing-modification or Conditional-branch:


Conditional Branch:

Setting conditions to be fulfilled for any thing during a flow - using it's properties or relations. With two outcomes - true or false sending the flow into one of two branches.
The settings interface with links to the two branches that both can have any number of instructions therein:
Table of Contents

4.5  Accounts

Note: The Accounts area would be like the accounts from the "Account plan" you're used to, the Account Reports are then built from the Accounts. In addition you can use it for non-accounting, non-monetary reports like hours and whatnot if need be.

Any numerical property value can be used - but as "Cost" is included in Item type anyway it's quite useful. For Container and Money type one would have to use the "Cost" as it is a result of unit-cost and current-amount giving the real value at the time of reporting.

Note: In normal accounting systems typically dynamic reports like P&L reports are based on static snapshots by registering of say "Sales" into the system. Thingamy does not do this as no transaction is registered in the same manner. For Thingamy a "transaction" follows the rules as give, example:

Sales: If a transaction called sales is defined as the moment an object changes ownership from company to a client and when it leaves the company's premises then Thingamy will use relations ("owned by" and "is in place"). Then creating sales would require a query over "Every object of [Type] that is not [Owned] by us and that is not in [Place] our premises" then choosing the time period. That way you can run two or more different GAAPs in parallel or get real-time Sales numbers for any period up to now.
Copy or Delete: Hook off the tickbox under Delete and press delete. Ditto for Copy - which creates a carbon copy of the Account or Account Report in question named "xxx copy 1":
Account template settings: Note the grey field - that's where you set the rules for what things will be included in the report. The query uses logical operator like "and, or, not" and other operators in any nested format. NOTE 1: That any useful result will be dependent on setting a query that picks up only one [Type] of thing!
NOTE 2: When you make an error building a query (and you will!) just set the top one to "none" and you can start over. Do not despair, you'll learn quickly!

Accounts are not available directly for users, only the Account Reports appears as choice in User settings:
The Account Report is where you can use the Accounts in a structured way using '+' and '-'. The Account Type time setting will be the default and should normally be set to "Now". When invoking a report the user will be allowed to set a different point-of-time or time-period. Note also that typical static, snapshot type reports like Balance Sheet, can also deliver a time period report showing changes to the Balance Sheet for a period. This as all accounts are created dynamically.
Account Report template settings:
Table of Contents

4.6  Reports

There are three different kind of reports or report types - all possible to be set as available for any user.

NOTE: The first time you run a report you will get the "Tweak" interface first, save and get the report. The Related Report Group type have even to be run twice the very first time after having been built - after this first round of tweaks it will display correctly.
Copy or Delete: Hook off the tickbox under Delete and press delete. Ditto for Copy - which creates a carbon copy of the Report or Report Group in question named "xxx copy 1":
Reports (upper part): Here you set the rules for what things to use, using the same query mechanism as in Accounts plus other rules. Set time to be Now would be normal, letting user change the time.

NOTE 1: That any useful result for detailed views (i.e. setting of cells) will be dependent on setting a query that picks up only one [Type] of thing!
NOTE 2: When you make an error building a query (and you will!) just set the top one to "none" and you can start over. Do not despair, you'll learn quickly!
Reports (lower part): Here you set the layout in tables adding columns and rows and setting property and layout for each cell:
Related Report Group:
Columned Report Group:
Table of Contents

4.7  Logs and Settings

Nothing here yet, but there will be two types of logs:
1. Changes for a chosen time period to system itself, and
2. Changes for a chosen time period to specific things.
Table of Contents

5  Run and test

Every task comes up as a dated link at the assignee's Home page. Dating is colour coded going from blue to red over time. If a user have access to "Workorders" he might override the assignee and do the task himself.
When a user is given a task - in the interface on the bottom there will be certain choices:

"Save": This allows keeping input so far while task remains uncompleted as a task in his Home area.
"Complete": This completes the task and sends it off to next step in the flow.
"Restore checkpoint": For practical reasons we have set "checkpoints" to be Display & Fillout tasks (the ones where you fill out property fields). So clicking on this will revert the flow to last previous D/F task whoever had it.
"Reassign task": If checkbox for this is hooked off in the flow-template (in Builder) this choice will be given the user. Choose another user and click and that other user will get the task instead of you.


VERY IMPORTANT NOTE:

First time you run a flow after building something or even tweaking something DO enter "Test Mode" (Right bottom side should give you that choice as default, if not there go to Users/Owners and edit "admin" and highlight "test mode" and refresh after saving).

That allows you to crash and get stuck without loosing the build!

Just exit test mode and you're back to where you entered test mode. This because the probability of forgetting something, having a small logical lapse etc is approximately 100%. Luckily, keeping an eye on it when you run a test you will know where to look for the problem.
When back in normal mode again, enter builder and look where you suspect the issue lies and fix. Again, enter test mode and try again. Rinse and repeat until all is well.
In a run, if you have set other assignees anywhere in the flow but yourself (admin if you're logged on as admin or initiator) you will not get the task (duh), but you can cheat and enter "Workflows" in the navigation bar and find who has it and take it over from there. Most useful when testing indeed.
Sometimes tasks comes directly without bothering sending you to the Home area and task overview - this is normal as long as you are the next assignee. Then it gets a kind of wizardy feel to it.
Good luck!
Table of Contents

6  Layout Tweaks

Currently the tools you have are several CSS files and some .js files plus the "logo.jpg" file that can be exchanged with any other using same name (and you can use text there too, for that look in the "stylesheet.css" file)
First find the files, tweak and save (read-only, but just override that) here:
Windows: C:\Program Files\Thingamy\thingamy-2.2.xx\static\yyy.css
Mac: right-click and choose "Show Package Content" for program file folder/thingamy.2.2.xx.app and find it here: Contents/Resources/static/yyy.css
After having saved the changes you have restart the application and refresh the user interface in the browser from "Home".
Table of Contents

7  TIP - the API

[Not yet fully implemented! Documentation etc. coming]
Thingamy Interface Protocol - TIP
Server side requirement: The TIP_test_client.java is a testing client for accessing the TIP protocol. It requires the Apache XMLRPC java library (currently version 3.1) from

XMLRPC site: http://ws.apache.org/xmlrpc/
Downloads: http://www.smudge-it.co.uk/pub/apache/ws/xmlrpc/

It needs all but the xmlrpc server jar file to work
Setup: In "User" interface any user can be given access to the TIP by highlighting and saving the "Tip" capability. With that capability set the XML/RPC calls will succeed for that user/password (XML/RPC goes over "http://:8080/RPC2")
  1. setup java's classpath appropriately to get the XML/RPC libs,
  2. java TIP_test_client http://localhost:8080/RPC2
In the code its setting up Basic Auth "admin" pw "admin"
Table of Contents

8  User support

Friendly advice and help always available at sigurd.rinde on Skype, sigrind52 on iChat/AIM, sig@thingamy.com per mail or +33 6 8887 9944 (if at lunch please excuse the noisy French in the background, if Sunday morning ring twice (not always with any result though) as I probably will be cycling some mountain, skiing an even higher one or in the woods looking for orange-white posts in some orienteering race :)
After lunch on Sundays works better!
Table of Contents