Page Comparison

Many of the PWS web services fall into the category of CRUD (Create, Read, Update, Delete) services. That is, they are concerned with adding, editing or deleting data in Projector. A typical set of CRUD services includes:

...

• Reference Structures
• Summary Structures
• Detail Structures
• Element Structures
• Summary Element Structures

Each structure has a specific purpose or specific purposes, and generally adheres to certain rules and conventions as detailed below.

Reference Structures

Reference Structures uniquely identify a specific instance of an entity (for example, a project reference structure identifies a specific project). Where specific instances of an entity may be uniquely identified by multiple different keys, the reference structure will provide each alternative means of identification (For example, projects may be identified by an internal identifier, a unique identifier or the project code – the project reference structure offers all three means of identification).

...

Note on internal identifiers: Most reference structures contain an internal identifier as one of the alternative means for identifying instances. Internal identifiers are mutable, and while not likely to happen frequently, they are subject to changing over time. As such, they are typically reserved for internal use and by default, the values returned by web services for internal identifiers will be NULL and any internal identifiers specified as inputs to web services will be ignored. Unique identifiers, by contrast, are immutable and should be used by web service consumers instead of internal identifiers.

Summary Structures

Summary structures inherit from reference structures and are typically used in services that return lists of entities. They include a small number of key attributes that are generally considered useful in lists. The size of the structure is intentionally kept pretty small to reduce the size of web service responses containing lists of these structures. As an example, the project summary structure, PwsProjectSummary, includes fields like the project name and identity of the engagement that contains the project, both very basic attributes likely to be useful when working with lists of projects.

Detail Structures

Detail structures inherit from summary structures and are intended to contain (directly or via inheritance) the complete set of attributes describing the underlying entity (excluding those attributes that are derived or considered read-only). These structures are used as input to services that save changes to instances of an entity, and are part of the response from services that retrieve instances. This makes it easy to use the web services to make changes to an instance, as the same structure retrieved by one service call may be edited and passed back up to a different service to save the changes.

...

Element structures contain detail structures, and additionally may contain attributes that are related to the entity and are useful to include with the data about the entity itself, but are not directly attributes of the entity (for example, permission flags). They also may contain read-only or derived (calculated) attributes of the entity that do not belong in the detail structure. Services that retrieve an instance of a particular entity typically contain an element structure in the response.

...

The aim of element structures is to allow the content of detail structures to be restricted only to direct, modifiable attributes of the entity, while allowing for the inclusion of additional, related and useful attributes when retrieving instances of a given entity. Organizing the data in this manner means that the detail structure retrieved by a retrieval web service can be passed back up to the corresponding save web service, while avoiding sending extraneous information up to the service.

...

When a listing of instances of a certain entity needs to contain attributes that are not direct attributes of the entity, summary element structures are used. In the same way that element structures allow detail structures to be limited to direct attributes of the underlying entity, summary element structures allow summary structures to be similarly restricted.

On updating data using web services:

There are two approaches to using web services that save changes to a particular entity:

...

Nullable vs Non-nullable Attributes

Generally, the save services are implemented such that leaving an attribute NULL in the detail structure is an instruction to leave the current value of the attribute unchanged. This works file fine for non-nullable attributes, as NULL is not a valid value for the attribute itself, but this is not the case for nullable attributes. For nullable attributes, there needs to be a way to set the value, NULL the value out or leave it alone. Nullable attributes have a corresponding clear flag that facilitates this as follows:

Grouped Attributes

In some cases, an entity may contain a group of two or more attributes that are related in such a way that it makes more sense to treat the group as a unit rather than independently. In these cases, where a clear flag is appropriate, it will typically apply to the group as a whole. When modifying these attributes, the caller must restate the value of all attributes in the group. There is not a way to specify that one of the individual attributes should be updated and the rest left as is. For example, the various address attributes of a client (street, city, state/province, etc.) are treated as a unit, To leave the address unchanged, one would leave all these attributes NULL. To updated the just the street address, the caller must restate the entire address with just the street address modified from its original value.