Human Resources Module Web Services Implementation

One of the goals of this project was to demonstrate central management of certain objects.   The development of a communications protocol was deferred due to the need to reduce scope.  However, the initial implementation of the web services inteface provides an alternative opportunity for providing a central management mechanism.  The artifacts, conventions and development processes of the web services framework are described in the wiki pages.  However, the execution of the steps described requires a plan for the manner in which a module's data will be exposed.  This document and its attachments represent that design. 

The file  HRWS.xls contains three sheets.

• Table-resource contains each table that is exposed as a resource.  For each table, it shows:
  • the name (although some resources will need renaming);
  • the resource of which each table is a sub-resource;
  • the type (data or metadata);
  • whether this resource is a part of the initial development;
  • the name and description (for metadata); the name, which is also provided for data, is the Display entry of the representation
  • the search parameters and what is searched for each;
    • typically a resource will have at least one search for each of its subresources, whose output will be a list of sub-resource references; 
    • some searches indicate multiple fields, in which case there should be a fuzzy search on all of the indicated fields;
    • the "since" parameter which is used with all resources containing a national_id field is designed to allow an outside program to identify adds, edits and changes made since the last synchronization process was run for use in the synchronization process;
  • the links which will be put in the link field (in addition to the self link which is part of the framework); typically this is used when a resource is a "child" of more than one resource; and
  • explanatory notes. 
• Pseudo-resource describes this construct, which exposes concept sets as if they were stand-alone code tables, and gives a code snippet
• Representations goes through each field of each of the table-resources described in the first sheet and describes how it is exposed in each of the three representations.  Some fields will require renaming.  The creation, change and retire/void information, except for the retire/void boolean itself, is incorporated in the auditinfo object described in the REST documentation.  In addition, there are fields from other table-resources which are exposed.   The three columns describe the contents of the three representations.  A blank cell in a representation column indiciates that the field is not exposed in that representation; some fields are not exposed in any representation, and most of these have been suppressed in the field listing.  The manners of exposure are the following:
  • Display : This is the display element.  In some cases, more than one field will be marked with this notation, meaning that multiple fields are concatenated in the display.  This should correspond to the name column of the table-resource sheet..  In some cases, the ref representation for a field will be marked as Display, while the default and full representations are marked with X.  This indicates that the field is editable and should appear both as the display field and as itself in the response body for editing; whenever the ref representation of a field is marked Display, it will be exposed in the other representations as Display, whether or not it can be edited.
  • Retired, voided, UUID: These correspond to the indicated fields within the ref representation.
  • Link: This indicates that the field is to be exposed as a link.  The annotations here should correspond with the link column of the table-resource worksheet.
  • X: This indicates that the field is to be exposed as a link.
  • Ref: This indicates that the field is to be exposed as a the ref representation of another object.
  • List: This indicates that the field corresponds to a collection and is to be exposed as a list of ref representations.

The use of Ref and List exposures can be seen in the linkage diagram below.  The Refs correspond to "have a" connections with the 1:1 annotation, while the Lists correspond to the "have a" connections without the 1:1 annotation.  The "is a" connections correspond to sub-resources, which contain a link to the parent resource.  In some cases, these links may not have been added to the table-resource worksheet.

Some errors are still being found in the table descriptions.  In particular, leave should be a data table with a voided property.  Some edit_privileges fields need to be removed.