Table 2 URI patterns for the Contribution builder

URI path template

Example path(s)

Description

/cb/

Shows a page describing Contribution builder usage and links to further pages

/cb/{committer_id}/

Lists EHR IDs for which the user has active uncommitted contribution builds

/cb/{committer_id}/{ehr_id}/

/cb/dr_who/12344321/

Lists active builds for ehr_id by committer_id

/cb/{committer_id}/{ehr_id}/new-cb-id/

A POST request creates a new empty Contribuition Build and redirects to it. A query parameter 'description' can be used to set a customized name of the contribution build.

/cb/{committer_id}/{ehr_id}/{cb-id}/

Lists the VERSION objects contained in the selected build and commands to view, modify, or delete those objects or the data contained in the versions. A form that can be used to create new VERSION objects is also provided. (Often the contribution_id will have the value ‘default’)

/cb/{committer_id}/{ehr_id}/{cb-id}/{temp-id}/

GET shows a page that allows viewing and editing of metadata for the VERSION object identified by temp_id

DELETE deletes the VERSION object

POST can be used to modify contents

/cb/{committer_id}/{ehr_id}/{cb-id}/{temp-id}/data/

GET views the data field of the version identified by temp_id. If the application/xml media type is requested by the client an XML serialization of the data is returned, but if a text/html media type is requested, a html view of the data including a data editing interface is returned.

PUT replaces the contents of the data field

POST can be used to modify data contents

Converters can be implemented and attached to this resource to accept data entry in more formats.

/cb/{committer_id}/{ehr_id}/{cb-id}/new/{command}/

POST is used to create new VERSION objects with the data field based on different sources determined by the command. Valid commands are:

• update-version: creates a new version based on an object that already exists in the EHR, it will be stored as an updated version of the original when committed.

• copy-version: creates a new object based on a copy of an object that already exists in the EHR, it will be stored in a new VERSIONED_OBJECT and not be related to the original.

• from-form: bases data completely from the form variable named ‘data’

• from-url: the data field will be a copy of the content of a resource identified by the ‘url’ field in the POSTed form with the request. This command is useful for example in debugging and testing.

• from-instance-template: like ‘from-url’ but the file at the url will be interpreted as a FreeMarker template and that will execute in a context populated with all variables sent in the POST request. This command allows a simple way of combining data in ordinary html forms with a skeleton structure provided by an instance example where target values have been replaced by variable names. This makes form field names flexible. (The FreeMarker template engine is only available in Java; thus some other templating language or mechanism for variable substitution should be investigated if this approach is used in an openEHR service specification.)

• from-ehr-path: like ‘from-instance-template’ but the form fields must be named as EHR paths corresponding to nodes that will be replaced in the file identified by the ‘url’ field.

Note that the last three commands create outgoing GET requests and thus can be exploited for denial-of-service attacks by malicious (but logged in) users or pose an information disclosure risk if URLs to external sites are allowed. Many HTTP clients include a ‘Referer’ field in the header that in this case may include both committer_id and ehr_id that could be transmitted to the external system if implemented badly. In the LiU EEE implementation, the ‘Referer’ field is instead set to the hostname of the system followed by the path ‘/static/restricted.txt’ where an explaining file is placed.

/cb/{committer_id}/{ehr_id}/{cb- id}/validate/

GET returns a validation report indicating validity or errors of all VERSIONs in the contribution build

/cb/{committer_id}/{ehr_id}/{cb- id}/commit/

POST commits the entire contribution build as a CONTRIBUTION and then deletes the build. If the commit is successful, a ‘201 Created’ response will be returned containing the contribution ID of the newly created CONTRIBUTION.