hydramata-works 0.0.1.prerelease

data/documents/diagrams/map-from-fedora-to-work-object.dot

@@ -0,0 +1,51 @@
+digraph "G" {
+    label="Map from Fedora to Work Object"
+    compound=true;
+    node[color="grey15" shape=record penwidth=2 margin="0.15, 0.125"];
+
+    subgraph 1 {
+        label="Records"
+        node[color="grey" style=filled fillcolor=olivedrab3];
+        fedora[label="Fedora"]
+        work[label="{ <f0> Work (in memory) | <f1> #pid | <f2> #work_type | <f3> #property_set }"]
+    }
+
+    subgraph cluster_0 {
+        label="Sequence for Transforming\nFedora object to a Work"
+        color="orange"
+        style="filled"
+        node[style=filled fillcolor=white]
+        fedora_request_pid[label="Request PID"]
+        fedora_retrieve_object[label="Retrieve Object"]
+        fedora_instantiate_work[label="Instantiate Work"]
+        fedora_assign_work_type[label="Assign Work Type"]
+        fedora_retrieve_datastreams[label="Retrieve Datastreams"]
+        fedora_for_each_datastream[label="For each Datastream"]
+        fedora_parse_datastream[label="Parse Datastream"]
+        fedora_for_each_property[label="For each Property"]
+        fedora_loop_for_each_property[label="More Properties" shape="diamond"]
+        fedora_loop_for_each_datastream[label="More Datastreams" shape="diamond"]
+        fedora_push_property_to_work_property_set[label="Push Property to Work Property Set"]
+        return_work[label="Return Work object"]
+
+        fedora_request_pid -> fedora_retrieve_object
+        fedora_retrieve_object -> fedora_instantiate_work ->
+        fedora_instantiate_work -> fedora_assign_work_type
+        fedora_assign_work_type -> fedora_retrieve_datastreams
+        fedora_retrieve_datastreams -> fedora_for_each_datastream
+        fedora_for_each_datastream-> fedora_parse_datastream
+        fedora_parse_datastream -> fedora_for_each_property
+        fedora_for_each_property -> fedora_push_property_to_work_property_set
+        fedora_push_property_to_work_property_set -> fedora_loop_for_each_property
+        fedora_loop_for_each_property -> fedora_for_each_property [label="NEXT"]
+        fedora_loop_for_each_property -> fedora_loop_for_each_datastream [label="NO"]
+        fedora_loop_for_each_datastream -> fedora_for_each_datastream [label="NEXT"]
+        fedora_loop_for_each_datastream -> return_work [label="NO"]
+    }
+
+    fedora_instantiate_work -> work[dir=both]
+    fedora_assign_work_type -> work:f2
+    fedora_retrieve_object -> fedora[dir=both]
+    fedora_push_property_to_work_property_set -> work:f3
+    work -> return_work
+}

data/documents/diagrams/map-from-input-to-work-object.dot

@@ -0,0 +1,37 @@
+digraph "G" {
+    label="Map from User Input to Work Object"
+    compound=true;
+    node[color="grey15" shape=record penwidth=2 margin="0.15, 0.125"];
+
+    subgraph 1 {
+        label="Records"
+        node[color="grey" style=filled fillcolor=olivedrab3];
+        input[label="Input"]
+        work[label="{ <f0> Work (in memory) | <f1> #pid | <f2> #work_type | <f3> #property_set }"]
+    }
+
+    subgraph cluster_0 {
+        label="Sequence for Transforming\nUser Input to a Work"
+        color="orange"
+        style="filled"
+        node[style=filled fillcolor=white]
+        post_user_input[label="Post User Input"]
+        for_each_input_key[label="For each Input Key/Value pair"]
+        determine_predicate_for_key[label="Determine Predicate by Key"]
+        coerce_value[label="Use Predicate to coerce Value into a Property"]
+        push_value_to_onto_work[label="Push Property onto Work"]
+        loop_input_key[label="More input keys?" shape="diamond"]
+        return_work[label="Return Work object"]
+
+        post_user_input -> for_each_input_key
+        for_each_input_key -> determine_predicate_for_key
+        determine_predicate_for_key -> coerce_value
+        coerce_value -> push_value_to_onto_work
+        push_value_to_onto_work -> loop_input_key
+        loop_input_key -> for_each_input_key[label="NEXT"]
+        loop_input_key -> return_work[label="NO"]
+    }
+    coerce_value -> work
+    work -> return_work
+    input -> for_each_input_key
+}

data/documents/diagrams/map-from-work-object-to-database.dot

@@ -0,0 +1,31 @@
+digraph "G" {
+    label="Map from Work Object to Database"
+    compound=true;
+    node[color="grey15" shape=record penwidth=2 margin="0.15, 0.125"];
+
+    subgraph 1 {
+        label="Records"
+        node[color="grey" style=filled fillcolor=olivedrab3];
+        database[label="database"]
+        work[label="{ <f0> Work (in memory) | <f1> #pid | <f2> #work_type | <f3> #property_set }"]
+    }
+
+    subgraph cluster_0 {
+        label="Sequence for Transforming\nan in Memory Work to the Database"
+        color="orange"
+        style="filled"
+        node[style=filled fillcolor=white]
+        save_work[label="Request to save Work"]
+        validate[label="Validate Work"]
+        request_pid[label="Request PID (if applicable)"]
+        serialize_property_set[label="Serialize PropertySet to JSON"]
+
+        save_work -> validate
+        validate -> work[dir=both]
+        work -> serialize_property_set
+        validate -> request_pid
+        request_pid -> serialize_property_set
+        serialize_property_set -> database
+    }
+
+}

data/documents/diagrams/work-rendering.dot

@@ -0,0 +1,53 @@
+digraph "G" {
+    label="Render a Work"
+    compound=true;
+    node[color="grey15" shape=record penwidth=2 margin="0.15, 0.125"];
+
+    subgraph 1 {
+        label="Records"
+        node[color="grey" style=filled fillcolor=olivedrab3];
+        work[label="{ <f0> Work (in memory) | <f1> #pid | <f2> #work_type | <f3> #property_set }"]
+        output_buffer[label=" { Rendered output }"]
+    }
+
+    subgraph cluster_0 {
+        label="Sequence for Transforming\nWork to Rendered Output"
+        color="orange"
+        style="filled"
+        node[style=filled fillcolor=white]
+        request_for_content_type[label="Request Work for Content Type (i.e. XML)"]
+        determine_presentation_structure[label="With Presentation Structure"]
+        for_each_fieldset[label="For each Fieldset"]
+        render_fieldset_container[label="Render Fieldset container"]
+        for_each_predicate[label="For each Predicate"]
+        render_predicate_container[label="Render Predicate container"]
+        fetch_work_property_by_predicate[label="Fetch Property from Work by Predicate"]
+        render_work_property[label="Render Work's Property#values"]
+        loop_for_each_predicate[shape="diamond" label="More Predicates?"]
+        loop_for_each_fieldset[shape="diamond" label="More Fieldsets?"]
+        render_remaining_work_properties_in_junk_drawer_fieldset[label="Render remaining Work Properties (if applicable)"]
+        return_output_buffer[label="Return rendered output to requester"]
+
+        request_for_content_type -> determine_presentation_structure
+        determine_presentation_structure -> for_each_fieldset
+        for_each_fieldset -> render_fieldset_container
+        render_fieldset_container -> for_each_predicate
+        for_each_predicate -> render_predicate_container
+        render_predicate_container -> fetch_work_property_by_predicate
+        fetch_work_property_by_predicate -> render_work_property
+        render_work_property -> loop_for_each_predicate
+        loop_for_each_predicate -> for_each_predicate [label="NEXT"]
+        loop_for_each_predicate -> loop_for_each_fieldset [label="NO"]
+        loop_for_each_fieldset -> for_each_fieldset [label="NEXT"]
+        loop_for_each_fieldset -> render_remaining_work_properties_in_junk_drawer_fieldset [label="NO"]
+        render_remaining_work_properties_in_junk_drawer_fieldset -> return_output_buffer
+    }
+
+    fetch_work_property_by_predicate -> work:f3[arrowhead=none]
+    determine_presentation_structure -> work:f2[arrowhead=none]
+    render_fieldset_container -> output_buffer
+    render_predicate_container -> output_buffer
+    render_work_property -> output_buffer
+    render_remaining_work_properties_in_junk_drawer_fieldset -> output_buffer
+    output_buffer -> return_output_buffer
+}

data/documents/diagrams/work-structure.dot

@@ -0,0 +1,32 @@
+digraph "G" {
+    label="Work Structure"
+    compound=true;
+    node[color="grey15" shape=record penwidth=2 margin="0.15, 0.125"];
+    edge[arrowhead="crowfeet"]
+
+    work[label="{ <f0> Work (in memory) | <f1> #pid | <f2> #work_type | <f3> #property_set }"]
+    work_type [label="{ WorkType | #name | #presentation_structure }"]
+    property [label="{ Property (in memory) | #predicate | #values }"]
+    workflow [label="{ Workflow | #first_task | #task_graph }"]
+    fieldset [label="{ Fieldset | #name | #predicates | #presentation_sequence_number }"]
+    fieldset_predicates [label="{ FieldsetPredicate | #fieldset | #predicate | #presentation_sequence_number }"]
+    predicate [label="{ <f0> Predicate | <f1> #name | <f2> #uri | <f3> #datastream_name | <f4> #predicate_coercer_class_name | <f5> #predicate_parser_class_name | <f6> #indexing_strategy | <f7> #key }"]
+    work_type_datastream_parser [label="{ WorkTypeDatastreamParser | #work_type | #datastream_name | #parser_class_name }"]
+    presentation_structure [label="{ Presentation Structure | #name }"]
+    presentation_context [label="{ PresentationContext | #work_type | #content_type (ie 'solr', 'xml', 'html') | #context (ie 'show', 'edit') | #renderer_class_name }"]
+    work_type_processing_context [label="{ ProcessingContext | #work_type | #context (ie 'create', 'update', 'destroy') }"]
+    property_set [label="{ PropertySet (in memory) | #work | #push(a_property) }"]
+
+    work_type -> work
+    work -> property_set [arrowhead=lcrow]
+    property_set -> property
+    predicate -> property
+    presentation_structure -> fieldset
+    fieldset -> fieldset_predicates
+    predicate -> fieldset_predicates
+    work_type -> presentation_structure
+    work_type -> presentation_context
+    work_type -> work_type_processing_context -> workflow
+
+    work_type -> work_type_datastream_parser
+}

data/documents/handling-work.md

@@ -0,0 +1,224 @@
+The audience for (most of) the specs that verify the feature is a developer.
+
+RSpec with a statement of target audience for each spec (i.e. product_owner: true).
+
+# To Render a New Work's SIP Form
+
+For the requested work_type
+  Instantiate a work with a presentation structure
+For each fieldset in the instatiated work's presentation structure
+  For each property key (predicate) in the fieldset
+    Render property key with Work's property
+
+## Done Looks Like
+
+```gherkin
+Given work_type 'Article' has the following presentation structure:
+    | fieldset    | property_key
+    | :required   | [['DC:TITLE', multi_value: true]]
+    | :optional   | [['DC:ABSTRACT', multi_value: false]]
+When I request an HTML form for a new 'Article'
+Then I should see a well-structured output with CSS selectors:
+    | css_selector
+    | .required .dc-title.multi_value input.value
+    | .optional .dc-abstract input.value
+And in the response document the .required container preceeds the .optional container.
+```
+
+# To Submit a Work's SIP Form
+
+This is a PO-level feature.
+
+## Done Looks Like
+
+```gherkin
+Given I have a valid form for a work_type
+When I submit the form
+Then a SIP is created with a unique PID
+And the SIP is submitted for processing
+And a :created response is issued
+```
+
+# To Render a Work's SIP
+
+For the requested PID
+  Find the work in the database and assign the work's properties
+For each fieldset in the work's presentation structure
+  For each property key (predicate) in the fieldset
+    Render property key with Work's property
+
+## Done Looks Like
+
+```gherkin
+Given a PID that exists in the database
+And it has the following serialized structure properties:
+    {'DC:TITLE' => ['My Book', 'A Lengthy Treatise'], 'DC:ABSTRACT' => 'Lots of Words'}
+And its work_type of Article has a presentation structure of:
+    | fieldset    | property_key
+    | :required   | [['DC:TITLE', multi_value: true]
+    | :optional   | ['DC:ABSTRACT']
+When I request an HTML version of that PID
+Then I should see a well-structured output with CSS selectors:
+    | css_selector                           | text_value
+    | .required .dc-title.multi_value .value | "My Book"
+    | .required .dc-title.multi_value .value | "Lengthy Treatise"
+    | .optional .dc-abstract .value          | "Lots of Words"
+And in the response document the .required container preceeds the .optional container.
+```
+
+# To Render a Work's AIP
+
+For the requested PID
+  Find the work in Fedora and assign the work's properties
+For each fieldset in the work's presentation structure
+  For each property key (predicate) in the fieldset
+    Render property key with Work's property
+
+## Done Looks Like
+
+```gherkin
+Given a PID that exists in Fedora
+And it has the following RDF properties:
+    | predicate   | object
+    | DC:TITLE    | My Book
+    | DC:TITLE    | A Lengthy Treatise
+    | DC:ABSTRACT | Lots of Words
+And its work_type of Article has a presentation structure of:
+    | fieldset    | property_key
+    | :required   | ['DC:TITLE']
+    | :optional   | ['DC:ABSTRACT']
+When I request an HTML version of that PID
+Then I should see a well-structured output with CSS selectors:
+    | css_selector                  | text_value
+    | .required .dc-title .value    | "My Book"
+    | .required .dc-title .value    | "Lengthy Treatise"
+    | .optional .dc-abstract .value | "Lots of Words"
+And in the response document the .required container preceeds the .optional container.
+```
+
+# A workflow processing a SIP
+
+For queued up SIP Workflow (eg State Machine).
+A task is a discreet function that can be run in isolation (i.e. characterize all files associated with this SIP).
+A workflow is composed of a sequence of tasks.
+
+**Workflow properties**
+
+A workflow has a unique name
+A workflow is comprised of tasks definitions
+A task definition is comprised of a unique name
+
+**Outstanding questions**
+
+How is the workflow defined?
+How each task is defined (i.e. what is the object interface)?
+How is a workflow processed (i.e. how do we run one task, then respond accordingly and start another task)?
+How are errors reported/monitored/recovered from?
+
+*Look to [Heracles](https://github.com/ndlib/heracles) for guidance.*
+
+## Done Looks Like
+
+```gherkin
+Given a workflow with tasks:
+  | task_name | responder
+  | :a        | { ok: :b }
+  | :b        | { ok: :done }
+And `first_task :a`
+When the workflow is started
+Then task :a is invoked
+```
+
+```gherkin
+Given a workflow with tasks:
+  | task_name | responder
+  | :a        | { ok: :b }
+  | :b        | { ok: :done }
+And `first_task :a`
+When task :a is completed with response :ok
+Then task :b is invoked
+```
+
+```gherkin
+Given a workflow with tasks:
+  | task_name | responder
+  | :a        | { ok: :b }
+  | :b        | { ok: :done }
+And `first_task :a`
+When task :a throws an exception
+Then task :b is not invoked
+And an error is submitted to the monitoring system
+```
+
+```gherkin
+Given a task of :generate_derivatives
+When the task :generate_derivatives is invoked with a SIP
+Then derivatives are generated for each of the SIP's associated primary files (i.e. don't generate derivatives for the derivatives)
+And append the derivatives to the SIP's payload
+```
+
+```gherkin
+Given a task of :run_antivirus
+When the task :run_antivirus is invoked with a SIP
+And one of the attached files is a virus
+Then return a :virus_found
+```
+
+```gherkin
+Given a task of :run_antivirus
+When the task :run_antivirus is invoked with a SIP
+And none of the attached files contain a virus
+Then return :virus_not_found
+```
+
+See the [Raw Object Format repository](https://github.com/ndlib/rof).
+
+```gherkin
+Given a task :validate_rof
+And a SIP that is will-formed and ready for ingest
+When the task :validate_rof is invoked with a SIP
+Then return :rof_is_valid
+```
+
+# To Index a Work's AIP
+
+SOLR strategy for a given property appears to be the same across work types.
+Each Property has a SOLR strategy
+
+# To Represent a Work's Files
+
+If we ask an object for its datastreams, how do we know which ones are files?
+Files are attached on children of a Work.
+There are manifestations of the Work's files in the datastreams.
+Predicate :realization for the File "Work"
+
+# Glossary?
+
+## Work
+
+Responsible for being a container of the data that is persisted in a data store.
+
+* Each work has many properties
+* Each property has a key (predicate) and one or more values
+
+## Presentation Structure
+
+Responsible for saying where in the rendering something occurs (eg Title occurs before Author).
+Provides logical groupings via Fieldsets (eg the "Required fields" occur before the "Optional fields")
+
+* Each work type has one presentation structure
+* Each presentation structure has many fieldsets
+* Each fieldset has many property keys
+
+## Fieldset
+
+Responsible for providing logical groupings of properties.
+Arbitrarily named; use internationalization (I18n) for name and legend.
+
+## Property Key
+
+## Work's Property
+
+## Renderers
+
+ShowRenderer, EditRenderer, NewRenderer

data/documents/high-level-stories.md

@@ -0,0 +1,105 @@
+# High-level Stories
+
+Below are stories that are supported in the `./documents` directory.
+
+## Done
+
+### (1) Transform in memory Work object to Show JSON Document
+
+### (2) Transform Fedora object to in memory Work object
+
+  * Done Looks Like: All of the persisted datastreams are in the database are reified in the Work object's #properties.
+
+### (1) Create an interface for rendering a fieldset
+
+### (1) Transform in memory Work object to Show HTML Document
+
+**Done looks like**
+
+```gherkin
+Given a work object with the following propety_set:
+  | fieldset  | predicate | value         |
+  | :required | :title    | 'Hello'       |
+  | :required | :title    | 'World'       |
+  | :required | :title    | 'Bang!'       |
+  | :optional | :abstract | 'Long Text'   |
+  | :optional | :abstract | 'Longer Text' |
+  | :optional | :keyword  | 'Programming' |
+When I request an HTML version of the work
+Then I should have the following css-selectors and text:
+  | css_selector               | text        |
+  | .required .title .label    | Title       |
+  | .required .title .value    | Hello       |
+  | .required .title .value    | World       |
+  | .required .title .value    | Bang!       |
+  | .optional .abstract .label | Abstract    |
+  | .optional .abstract .value | Long Text   |
+  | .optional .abstract .value | Longer Text |
+  | .optional .keyword .label  | Keyword     |
+  | .optional .keyword .value  | Programming |
+```
+
+## Must Have
+
+### (4) Transform in memory Work object to New HTML Document
+
+**Done looks like**
+
+```gherkin
+Given a work object with the following propety_set:
+  | fieldset  | predicate | value         |
+  | :required | :title    | 'Hello'       |
+  | :required | :title    | ''            |
+  | :optional | :abstract | ''            |
+  | :optional | :keyword  | ''            |
+When I request an HTML version of the work
+Then I should have the following css-selectors and text:
+  | css_selector                                         | text       |
+  | fieldset.required.caption                            | 'Required' |
+  | .required .title label.label                         | 'Title'    |
+  | .required .title input.value[name=work[title]]       | 'Hello'    |
+  | .required .title input.value[name=work[title]]       | ''         |
+  | fieldset.optional.caption                            | 'Optional' |
+  | .optional .abstract input.value[name=work[abstract]] | ''         |
+  | .optional .keyword input.value[name=work[keyword]]   | ''         |
+```
+
+### (3) Create an interface for rendering a property
+
+  * in Edit HTML
+  * in New HTML
+  * in Show HTML
+  * in Solr Document
+
+### (1) Transform Database object to in memory Work object
+
+  * Done Looks Like: All of the persisted properties in the database are reified in the Work object's #properties.
+
+### (2) Transform Solr object to in memory Work object
+
+### (2) Transform in memory Work object to SOLR Document
+### (3) Transform in memory Work object to Raw Datastreams
+### (1) Transform in memory Work object to Edit HTML Document
+### (1) Transform in memory Work object to Database
+### (3) Transform in memory Work to Fedora object
+### (1) Transform user input from Edit Form to in memory Work object
+### (1) Transform user input from New Form to in memory Work object
+
+#### Components
+
+* Define a Work type's suggested predicates
+* Define a Work type's presentation structure
+* Define an abstract Predicate
+* Create a presented fieldset
+  * Should render itself for its context
+* Create a presented property
+  * Should render itself for its context
+
+## Nice to Have
+
+* Transform in memory Work object to New JSON Document
+
+## There are Small Work Items
+
+* Predicate parsers and coercers
+* Datastream parsers and coercers