What is a primary key?
Every document stored within OpenGroupware has a numeric id that is unique. In fact, almost every entry concerning anything in OpenGroupware has one of these ids. This id namespace is flat; that is: ids do not overlap between document types; if there is a person with an id of 99450 then there is no enterprise, file, appointment, or anything else with the id of 99450. When anything is created it is assigned one of these unique numbers, called the primary key (often abbreviated pkey or pk. And that is the id of that document for its entire lifetime.

One note of clarification: by "document" we don't mean "file". An enterprise, person, job, project, file, appointment, or resource are all documents. You could call them objects too, but that gets even more confusing. :)

What is an EOGlobalID/EOKeyGlobalID?
Serialized an EOKeyGlobalID looks something like "<0x0x82cb23c[EOKeyGlobalID]: Date 28260>". Yea, that was helpful wasn't it? But look at it... there is the string "Date" and a number of "28260". If you guessed that this refers to the date [appointment] document with a pkey of 28260 then you are correct. Internally EOKeyGlogalIDs (often abbreviated as gid/gids) are what OpenGroupware uses, on the database level, in order to retrieve and store data. OGo/SOPE uses a database abstraction layer called GDL, apparently very much like the GDL from GNU-Step. You can think of the EOKeyGlobalID as a "handle" for the data related to a given document.

The EOKeyGlobalID object has the following accessors:
- (NSString *)entityName;
- (unsigned int)keyCount;
- (id *)keyValues;
- (NSArray *)keyValuesArray;

The entityName accessor will provide the type of document that the key refers like. The keyValuesArray provides access to the payload which is the pkey of the object. Since the value of keyValuesArray is an NSArray, and you almost certainly want just the single value which it contains you'd use code like: [[key keyValuesArray] objectAtIndex: 0] which in the above example would provide you with the value "28260" (as an NSNumber object).

How to turn a pkey into an EOKeyGlobalId?
It is a very frequency case where you have a pkey or an NSArray of pkeys for which you need to marshal the corrsponding document objects. Marshalling an object requires having the EOKeyGlobalId (handle). Fortunately the OpenGroupware framework provides a very simple means to generate an EOKeyGlobalId from a pkey; this is via the typeManager object.

The first requirement for getting handles from typeManager is that your pkey or array of pkeys must be NSNumber objects. You cannot use NSString objects. Use the NSString class's intValue method to produce NSNumber objects: [NSNumber numberWithInt:[_arg intValue]] where _arg is your NSString object. Of course the contents of _arg have to actually be numeric. Then you can invoke the typeManager object like:
gid = [[[self commandContext] typeManager] globalIDForPrimaryKey:_arg]
where _arg is the NSNumber object containing your pkey.