Issues for Organizational Structure Facility FTF mailing list

List of issues (green=resolved, yellow=pending Board vote, red=unresolved)

List options: All ; Open Issues only; or Closed Issues only

Issue 4352: Inconsistency between IDL in document body and full IDL in appendix
Issue 4353: Two (non-consistent) styles of customized attribution
Issue 4354: Confusing use of OrgTemplate
Issue 4355: Domain Model needs more explanation
Issue 4356: No description for Factory and Finder interfaces in DfOrganizationalEntity
Issue 4357: Need more information on how duplicate attributes will be handled.
Issue 4358: Specification does not provide constraints on relationships between roles
Issue 4359: datatype for OrgModel::export_to_stream seems inadequate in size
Issue 4360: Unclear dependency for HROrgModel on OrgModel
Issue 4361: Despite claims, Factory/Finder functionality does not conform to a consiste
Issue 4362: Inconsistent pattern of getting and setting OrgEntity data from subclasses
Issue 4363: Structural data in DfOrganizationalEntity module needs to be explained
Issue 4364: BusinessUnitData::manager issue
Issue 4365: The semantics of cloning are unclear
Issue 4366: The semantics for publishing an OrgStructure are unclear
Issue 4367: Need a clear way to determine if an OrgStructure is already published
Issue 4368: Need a cleaner and more efficient way of retrieving current versions of Org
Issue 4369: OrgElement is confusing as to whether it is a LifeCycle object or not
Issue 4370: The Lifecycle of an OrgStructure is confusing
Issue 4371: Cannot retire published objects
Issue 4372: The version field of the VersionHistory struct needs more explanation
Issue 4373: Cloned OrgStructure and cloned copy's VersionHistory issue
Issue 4374: referential integrity problem due to ID-based linkage between Entities/Str
Issue 4375: H'..REMOVED' notification event supply issue
Issue 4376: It's unclear what's notified as an 'ORG_ELEMENT_CHANGE'
Issue 4377: what gets notified when a new child OrgElement is added to a OrgStructure?
Issue 4378: Clarify where notifications are supported
Issue 4379: Navigation from a BusinessUnit to its children is too complicated
Issue 4380: Only one RoleType defined in Specification, which seems limiting
Issue 4381: Role doesn't follow the Admin pattern used for all other entities
Issue 4382: Role does not contain Iterator for get_related_objects_by_role operation
Issue 4553: Position should not inherit from Subject in section 4 of document
Issue 4655: An Index would be nice to have.

Issue 4352: Inconsistency between IDL in document body and full IDL in appendix (osf-ftf)

:  p.20 has OrgAttribute and OrgAttributeValue type, p. 88 has OrgElementAttribute and OrgElementValueType instead.  The appendix is internally inconsistent: p103 refers to dfOrganizationalStructure::OrgTemplate which on p88 is OrgElementType (though OrgTemplate on p20).

:  There are two non-consistent styles of customized attribution for no obvious reason: the spec has both OrgElementAttribute (a 4-part struct including name, value_type (numeric/alpha/alphanumeric), value, size), and also NamedAttribute (literally a name, value pair) which seems to apply mainly to Subjects.

. In the OrganizationalEntity Module, OrgTemplate is typedef'd as OrgEntityProperty and is used for attribute values. In OrganizationalStructure module, however, it is not used for attributes (attribute templates are not supported in this module), but is typedef'd as OrgElementType and is used for element 'names'. In fact, this area gets confusing: OrgElement::name indicates the ElementType (e.g. 'Location') and OrgElement::value indicates the name (e.g. "Birmingham")!]. 
This multiple use of OrgTemplate has a practical problem: OrgTemplate has an attribute valid_descriptions: when OrgTemplate is typedef'd as OrgEntityProperty this does not make sense, since an actual Property just has a value not a Description.
Moreover since instances of OrgElementAttribute have a 'value_type' (numeric/alpha/alphanumeric), it seems an omission that OrgTemplates do not - to e.g. allow one to constrain an 'Age' attribute to be Numeric.

:  The Domain Model shows classes CompanyTemplate and DivisionTemplate which aren't mentioned anywhere later. Moreover the Domain Model represents very little of the concepts in the specification and how they are related. Also the relationship from OrgModel to OrgStructure and from that to OrgElement should be shown as UML Compositions ('black diamond') as opposed to the Aggregations shown

:  There is no description of the Factory or Finder interfaces for the OrganizationalEntity Module: they just appear in the diagrams and IDL. So it's not clear what PositionFactory::create_position_from_template (for example) will actually do with the properties attached to the template - given that no initial value is defined in the template, there seems to be no notion of a 'permitted' set of attributes for an instance, and no concept of an 'undefined'/'unset' attribute value. So if one creates a Position from a template with a property "A1", then what is the effect of then calling get_additional_attributes on the Position? Will A1 be returned, and if so with what value and what type?

:  For Attributes the spec is very unclear as to whether 'duplicates' (many attributes with the same name on the same Entity/Element) are permitted (e.g. if one calls add_attribute and an attribute of that name already exists). And if duplicates are permitted, whether 'remove' will remove them all, and 'replace' replace them all.

:  Although the OrgEntities instantiated from an OrgEntityTemplate can be constrained to a fixed set of Roles, this does not seem to provide any constraint on relationships since there is no limitation on which Roles may be linked to which Roles. So using the example from the spec, an Employee template might include 'Manager' in the constrained set of Roles, but there is nothing to say what other Roles 'Manager' might be linked with. So one could find the 'Manager' role for a person linked with the 'Wife' role of another person. Which probably does not make sense as a relationship. Though there's nothing to say what the intended relationship is meant to be.

OrgModel::export_to_stream returns a String which seems inadequate in size for practical CORBA implementations.

:  Unclear how independent the modules are: HROrgModel inherits from OrgModel: does that then mean that an instance of HROrgModel can or should own its own OrgStructures?

For subclasses Position and HumanResource of OrgEntity there are specific Factory and Finder classes, for Person and BusinessUnit these functions are carried out by AddressBook. For OrgElement, it's the OrgElementAdmin interface that serves as the main Factory for OrgElements (via operation new_child), but this has no relationship with the main Finder which is OrgStructure (the claimed pattern is that factories inherit from finders).

:  There are non-consistent ways of getting/setting the same information.  For instance,  Person inherits from OrgEntity and therefore it will inherit OrgEntity::get_org_entity_data.  However Person also has OrgPerson::get_person_data, which returns a struct PersonData which again contains OrgEntityData. Having obtained a struct one cannot then do anything with it - one has to unpack it to update the property values and call a separate mutator for each (not necessarily bad, but inconsistent).

The OrgEntity module has some direct references for Structural information (e.g. BusinessUnitData::members). According to verbal statements by submitters these are convenience functions that map to the OrgStructure module but this is not stated in the spec. If not, these functions introduce confusion as to which to use. And is this a hidden dependency on that module?

BusinessUnitData::manager does not allow a Position (as opposed to a person) to be referenced, requiring an unnecessary update when the Person filling the position is replaced.

BusinessUnitData::manager does not allow a Position to be referenced, requiring an update when the incumbent Person moves jobs

The semantics of cloning are unclear - I assume that since each OrgElement can belong to only one OrgStructure that cloning an OrgStructure would also clone all of the OrgElements within it, each with a new ID.

:  The semantics of publishing a Structure and the associated state transitions are not made clear. I'd guess that one would publish a Structure and then clone it, to allow any further update. Can one then publish the cloned structure or does one have to retire the first structure first? Is it necessary to first publish a structure before it is retired (I assume not, due to lack of a relevant exception, which is a bit counterintuitive)?

There is no way to discover whether a specific OrgStructure 'isPublished' or not - which seems pretty essential to support the notion of 'tentative changes' as claimed (where the caller does not have any access to the Admin interfaces in which case one could look for the PublishedVersion exception).

:  In order to discover information 'as of' a certain date, it is suggested (p121 of convenience document) that the client go through the hassle of trawling through the entire version history and filtering out the correct timespan to get an ID and then performing a lookup by ID. This is painful enough for one object. However this also 'infects' interfaces such as OrgModel::list_orgstructures which will presumably return *all* OrgStructures for the model regardless of how old/retired/expired they are. And one will have to trawl the version history of each of these.  So this means that each Orgstruct that has ever existed in the model will need to be returned to the client just to get the current ones. And all this information is being returned across 'the wire' rather than being filtered within the OSF Facility. [According to the spec it is purely up to the client to interpret effective/expired dates and the Facility will perform no filtering at all based on these timestamps].

Need a cleaner and more efficient way of retrieving current versions of OrgStructures

OrgElement::new_child (and insert_above_child) takes a LifeCycleData parameter which seems redundant since OrgElement is not a Lifecycle object (although in several places the text contradicts this).

OrgModel::create_orgstructure does not take a LifecycleData parameter. Moreover neither OrgStructureAdmin nor LifecycleAdmin provide an ability to set lifecycle dates except via publish/retire. The effect seems to be that it is not possible to set an effective/termination date except for 'today'. I can only assume that this is a (fairly large) typo and that the Lifecycle parameter belongs on OrgStructure not OrgElement.
Resolution:

The Lifecycle of an OrgStructure is confusing, such as how the dates get set, and whether it should be created with LifecycleData

:  Since the LifecycleAdmin::publish operation disables the Admin interface for the object, this then also disables access to the retire() operation - which only allows unpublished structures to be retired!.

Nothing meaningful is said about the 'version' field of the VersionHistory struct - presumably the Facility sets the value, but to what/what format?

The version field of the VersionHistory struct needs more explanation as to how it would be formatted

:  If an OrgStructure is cloned to allow further changes after publishing then (in some cases at least - where the cloning is intended to mean 'create new version') it is not clear whether the clone will copy the VersionHistory of the original. It might also be desirable for the Published version to share the clone's VersionHistory (so that one can see that it has been succeeded by a later version). However this could get into problems if the original Published Object were to be cloned a second time.

When an OrgStructure is cloned it is not clear what happens to the cloned copy's VersionHistory

:  There is a referential integrity problem due to the ID-based linkage between Entities and Structures. So that if a new version of a BusinessUnit is created, all the OrgStructures that refer to that BusinessUnit will have to be navigated to by the caller and updated (and published!) to refer to the ID of the new version.

There is a referential integrity problem due to the ID-based linkage between Entities and Structures.

:  How can the '..REMOVED' notification event supply a 'relevantObject' if it's been deleted

How can '..REMOVED' notification event supply  'relevantObject' if it's been deleted?

:  It's unclear what's notified as an 'ORG_ELEMENT_CHANGE' - all the other notifications are also to do with changing an OrgElement? (descriptions for the events would help).

:  If a new child Org_Element is added, is that notified as a change to any or all of: the new child? its parent? the containing OrgStructure? the containing OrgModel?

It's unclear what gets notified when a new child OrgElement is added to a OrgStructure

Unclear why notifications are only supported for OrgStructure module and not OrgEntity

Unclear why notifications are only supported for DfOrganizationalStructure module and not the DfOrganizationalEntity module

BusinessUnits seems unnecessarily hard, as shown in the following pseudocode. 
Assume I'm starting with the BusinessUnit in a variable called myBusinessUnit, and that I've already set up variables for the myOrgFinder and that I know the name of the orgmodel.

	myId = myBusinessUnit.get_id() // get the ID for the BusinessUnit
	mySubject = myOrgFinder.find_subject_by_external_id(myId) // find the Subject for it, treating myId as 'external' to the OrgStructure
	myStructure = myOrgFinder.find_orgstructure_by_name("my model name", "org hierarchy structure", "some version identifier") //get the appropriate org structure by 'knowing' the right name
	myNodeList = myStructure.list_org_elements_with_subject (mySubject.identifier, 1, 0, myOrgElementIter) // get the node for the BusinessUnit within the structure - assuming there is only one
	myNode=myNodeList[0] // get the node from the list
	myChildrenNodes = myNode.listChildren(MAXLIST, MAXITER, myOrgElementIter) // navigate to the children nodes
	for each childNode in myChildrenNodes do
		childData = childNode.getData()  // get the OrgElement data
		nextChildSubject = childData.subject // extract the subject
		childExtId = nextChildSubject.external_identifier // extract the external id to allow lookup in the Address Book

Now there is the problem of not knowing what type of object these ids represent, to know whether to call myAddressBook.find_business_unit_by_id, or myAddressBook.find_person_by_id. Do I just need to try one and if it fails try the other?

:  The specification supports only the one 'RoleType' of HumanResource. There is no factory specified or usable for any other, be it a subclass of HumanResource that might get added, or Role itself. This also precludes BusinessUnits having roles.
Resolution:

Operations such as Role::add_related_object seems inconsistent with the stated principle in the spec that updates should be separated into 'Admin' interfaces).

The fact that there is no Iterator support for get_related_objects_by_role (which could return all the employees in a company) seems inconsistent with the stated principle in the spec.

Role does not contain Iterator for get_related_objects_by_role operation which potentially could return huge amounts.

 In the OrganizationalEntity Module, in section 4.7.2 it
incorrecty shows Position inheriting from Subject
Resolution: In section 4..7.2, where the IDL for Position Interface is
shown, remove the inheritance from DfOrganizational::Subject

 Since the document is fairly large, an index would be helpful.