Page History
...
- The traditional way is to use the "collection-handle" attribute to map a submission form to it's Collection. Its collection-handle attribute is the Handle of the collection. Its submission-name attribute is the submission definition name, which must match the name attribute of a submission-process element (in the submission-definitions section of item-submission.xml.
For example, the following fragment shows how the collection with handle "12345.6789/42" is assigned the "custom" submission process:
Code Block language html/xml <submission-map> <name-map collection-handle="12345.6789/42" submission-name="custom" /> ... </submission-map> <submission-definitions> <submission-process name="custom"> ... </submission-definitions>
- As of 7.6, another option is to use the "collection-entity-type" attribute to map all Collections which use that Entity Type (requires Configurable Entities) to a specific submission definition name (via the submission-name attribute, similar to above).
For example, the following fragment shows how to map all Collections which use the out-of-the-box Entity Types to a submission definition of the same name:
Code Block language xml <submission-map> ... <name-map collection-entity-type="Publication" submission-name="Publication"/> <name-map collection-entity-type="Person" submission-name="Person"/> <name-map collection-entity-type="Project" submission-name="Project"/> <name-map collection-entity-type="OrgUnit" submission-name="OrgUnit"/> <name-map collection-entity-type="Journal" submission-name="Journal"/> <name-map collection-entity-type="JournalVolume" submission-name="JournalVolume"/> <name-map collection-entity-type="JournalIssue" submission-name="JournalIssue"/> ... <submission-map>
- WARNING: If you create a new Collection using a specific Entity Type, you must currently restart your servlet container (e.g. Tomcat) for the submission form configuration to take effect for the new Collection. This is the result of a known bug where the Submission forms are cached until the servlet container is restarted. See this issue ticket: https://github.com/DSpace/DSpace/issues/7985
It's a good idea to keep the definition of the default name-map, so there is always a default for collections which do not have a custom form set.
...
If a collection collection-handle="12345.6789/42"
configuration will prevail over this configuration. Meaning that if a collection-entity-type
is defined and a collection-handle is also defined and if a collection handle overlaps in both configurations, then, the submission to be considered it will be the one that is defined by collection-handle
(it will prevail the one with more granularity).
Note | ||
---|---|---|
| ||
Due to the way SubmissionConfigReader is loaded into memory (on a initialize process) currently there is no implemented way to reload submission forms. So, every time you assign an entity type to a collection, or create a new collection with an associated entity type, you will need to do a Tomcat restart for that collection to be available at the item submission config. There is an on going fix for that. |
Custom Metadata-entry Steps for Submission
Introduction
Custom Metadata-entry Steps for Submission
Introduction
This section explains how to customize the Web This section explains how to customize the Web forms used by submitters and editors to enter and modify the metadata for a new item. These metadata web forms are controlled by the Describe step within the Submission Process. However, they are also configurable via their own XML configuration file [dspace]/config/submission-forms.xml
.
...
- dc-schema (Required) : Name of metadata schema employed, e.g. dc for Dublin Core. This value must match the value of the schema element defined in dublin-core-types.xml
- dc-element (Required) : Name of the Dublin Core element entered in this field, e.g. contributor.
- dc-qualifier: Qualifier of the Dublin Core element entered in this field, e.g. when the field is contributor.advisor the value of this element would be advisor. Leaving this out means the input is for an unqualified DC element.
- language: If set to true a drop down menu will be shown, containing languages. The selected language will be used as language tag of the metadata field. A compulsory argument value-pairs-name must be given containing the name of the value pair that contains all the languages: e.g.
<language value-pairs-name="common_iso_languages">true</language>
. - repeatable: Value is true when multiple values of this field are allowed, false otherwise. When you mark a field repeatable, the UI will add an "Add more" control to the field, allowing the user to ask for more fields to enter additional values. Intended to be used for arbitrarily-repeating fields such as subject keywords, when it is impossible to know in advance how many input boxes to provide. Repeatable fields also support reordering of values.
- label (Required): Text to display as the label of this field, describing what to enter, e.g. "Your Advisor's Name".
- input-type (Required): Defines the kind of interactive widget to put in the form to collect the Dublin Core value. Content must be one of the following keywords:
- onebox – A single text-entry box (i.e. a normal input textbox)
- textarea – Large block of text that can be entered on multiple lines, e.g. for an abstract.
- name – Personal name, with separate fields for family name and first name. When saved they are appended in the format 'LastName, FirstName'. (By default, this input type is unused. Author fields now use the "onebox" type to support different types of names.)
- date – Calendar date. When required, demands that at least the year be entered.
- series – Series/Report name and number. Separate fields are provided for series name and series number, but they are appended (with a semicolon between) when saved.
- dropdown – Choose value(s) from a "drop-down" menu list. Note: You must also
- Requires that you include a value for the value-pairs-name attribute to specify a list of menu entries from which to choose. Use this to make a choice from a restricted set of options, such as for the language item.
- qualdrop_value – Enter a "qualified value", which includes both a qualifier from a drop-down menu and a free-text value. Used to enter items like alternate identifiers and codes for a submitted item, e.g. the DC identifier field. Note: As for
- Similar to the dropdown type, requires that you
- include the value-pairs-name attribute to specify a menu choice list.
- Because the "qualdrop_value" dynamically sets the qualifier (based on the drop-down menu), the <dc-qualifier> field MUST be empty. The <dc-qualifier> element cannot be used with this field type.
- list list – Choose value(s) from a checkbox or radio button list. If the repeatable attribute is set to true, a list of checkboxes is displayed. If the repeatable attribute is set to false, a list of radio buttons is displayed. Note: You must also (By default, this input type is unused.)
- Requires that you include a value for the value-pairs-name attribute to specify a list of values from which to choose
- .
- tag - A free-text field which allows you to add multiple labels/tags as values. An example is the "Subject Keywords" field.
- Note:A tag field MUST be marked as
- <repeatable>true</repeatable>.
- hint (Required): Content is the text that will appear as a "hint", or instructions, below the input field. Can be left empty, but the tag must be present.
- required: When this element is included with any content, it marks the field as a required input. If the user saves the form without entering a value for this field, that text is displayed as a warning message. For example, <required>You must enter a title.</required> Note that leaving the required element empty will not mark a field as required, e.g.:<required></required>
- vocabulary: When specified, this field uses a controlled vocabulary defined in
[dspace]/config/controlled-vocabularies/[name].xml
. This setting may be used to provide auto-complete functionality, for example in the "Subject Keywords" field (which uses the "tag" input type). See also the "Configuring Controlled Vocabularies" section below. - regex: When specified, this field will be validated against the Regular Expression, and only successfully validating values will be saved. An example is commented out in the default "Author" field.out in the default "Author" field. If the validation fails, the following error message will be shown by default: "This input is restricted by the current pattern: {{ pattern }}.". This can be customized, by adding an entry to the internalization files with the key
error.validation.pattern.schema_element_qualifier
and the schema, element and qualifier of the field. For example: "error.validation.pattern.dc_identifier": "The identifier can only consist of numbers". For instructions on how to add custom entries see: Customize UI labels using Internationalization (i18n) files - style: When specified, this provides a CSS style recommendation to the UI for how to style that field. This is primarily used when displaying multiple fields per row, so that you can tell the UI how many columns each field should use in that row. Keep in mind, these styles should follow the Bootstrap Grid System, where the number of columns adds up to 12. An example can be see in the default "Date of Issue" and "Publisher" fields, which are configured to use 4 (col-sm-4) and 8 (col-sm-8) columns respectively.
- visibility: the submission scope for which the field should be visible. Values allowed are submission or workflow. When one of the two options is given the filed will be visible only for the scope provided and it will be hidden otherwise.
- readonly: this option can be used only together with the visibility element, and it means the field should be a read-only input instead of being hidden out of the scope provided by the visibility element. The value allowed id is readonly, e.g.: <readonly>readonly</readonly>
...
Configuring Controlled Vocabularies
DSpace now supports controlled vocabularies to confine the set of keywords that users can use while describing items. The need for a limited set of keywords is important since it eliminates the ambiguity of a free description system, consequently simplifying the task of finding specific items of information. The controlled vocabulary allows the user to choose from a defined set of keywords organized in an tree (taxonomy) and then use these keywords to describe items while they are being submitted.
...
The vocabulary element has an optional boolean attribute closed that can be used to force input only with the Javascript of controlled-vocabulary add-on. The default behaviour (i.e. without this attribute) is as set closed="false". This allow the user also to enter the value in free way.in free way.
Controlled vocabularies have two main display types in the submission form:
<input-type>onebox</input-type>
will display a onebox style field (optionally repeatable) which pops up the entire hierarchical vocabulary to allow you to select an individual term.<input-type>tag</input-type>
will display a tag-style field (optionally repeatable) which suggests terms within the vocabulary as you type.
The following vocabularies are currently available by default:
...
The "uploadConfigurationService" bean maps an existing "UploadConfiguration" bean (default is "uploadConfigurationDefault") to a specific step/section name used in item-submission.xml.
Code Block <!-- This default configuration says the <step-definition id="upload"> defined in item-submission.xml uses "uploadConfigurationDefault" --> <bean id="uploadConfigurationService" class="org.dspace.submit.model.UploadConfigurationService"> <property name="map"> <map> <entry key="upload" value-ref="uploadConfigurationDefault" /> </map> </property> </bean>
One or more UploadConfiguration beans may exist, providing different options for different upload sections. An "UploadConfiguration" consists of several properties:
name (Required): The unique name of this upload configuration
- configurationService (Required through 7.3): reference to the DSpace ConfigurationService (should always be "org.dspace.services.ConfigurationService"). Starting in 7.4 this is no longer required and should not be set.
- metadata (Required): The metadata "form" to use for this upload configuration. The value specified here MUST correspond to a <form> defined in your submission-forms.xml. In the below example, the "bitstream-metadata" form is used by the "uploadConfigurationDefault" bean...meaning that form will be used to capture metadata about the uploaded bitstream.
- options (Required, but can be empty): list of all "AccessConditionOption" beans to enable. This list will be shown to the user to let them select which access restrictions to place on each bitstream. NOTE: To disable the ability to select bitstream access restrictions, comment out all <ref> tags to create an empty list of options.
- maxSize: Optionally, you can specify a maximum size of file accepted by this UploadConfiguration. If unspecified, default is to use "upload.max" in dspace.cfg/local.cfg, or have no maximum.the maximum file upload limits specified in Spring Boot (see "Basic Settings" above)
required: Optionally, you can specify if a file upload is required for this UploadConfiguration. If true, upload is required and users cannot complete a submission without uploading at least one file. If false, no upload is required to complete the submission. If unspecified, default is to use "webui.submit.upload.required" configuration in dspace.cfg/local.cfg, which defaults to "true" (file upload required).
Code Block <bean id="uploadConfigurationDefault" class="org.dspace.submit.model.UploadConfiguration"> <property name="name" value="upload"></property> <property name="configurationService" ref="org.dspace.services.ConfigurationService"/> <property name="metadata" value="bitstream-metadata" /> <property name="options"> <!-- This is the list of access options which will be displayed on the "bitstream-metadata" form --> <!-- If no <ref> tags appear in this list, then access restrictions will not be allowed on bitstreams --> <list> <ref bean="openAccess"/> <ref bean="lease"/> <ref bean="embargoed" /> <ref bean="administrator"/> </list> </property> </bean>
- Any number of "AccessConditionOption" beans may be added for applying different types of access permissions to uploaded files (based on which one the user selects). These beans are easy to add/update, and just require the following
- id (Required): Each defined bean MUST have a unique "id" and have "class=org.dspace.submit.model.AccessConditionOption".
- groupName: Optionally, define a specific DSpace Group which this Access Condition relates to. This group will be saved to the ResourcePolicy when this access condition is applied.
- name: Give a unique name for this Access Condition. This name is stored in the ResourcePolicy "name" when this access condition is applied.
- hasStartDate: If the access condition is time-based, you can decide whether a start date is required. (true = required start date, false = disabled/not required). This start date will be saved to the ResourcePolicy when this access condition is applied.
- startDateLimit: If the access condition is time-based, you can optionally set an start date limit (e.g. +36MONTHS). This field is used to set an upper limit to the start date based on the current date. In other words, a value of "+36MONTHS" means that users cannot set a start date which is more than 3 years from today. This setting's value uses Solr's Date Math Syntax, and is always based on today (NOW).
- hasEndDate: If the access condition is time-based, you can enable/disable whether an end date is required. (true = required end date, false = disabled/not required). This end date will be saved to the ResourcePolicy when this access condition is applied.
endDateLimit: If the access condition is time-based, you can optionally set an end date limit (e.g. +6MONTHS). This field is used to set an upper limit to the start date based on the current date. In other words, a value of "+6MONTHS" means that users cannot set an end date which is more than 6 months from today. This setting's value use Solr's Date Math Syntax, and is always based on today (NOW).
Code Block <!-- Example access option named "embargo", which lets users specify a future date (not more than 3 years from now) when this file will be available to Anonymous users --> <bean id="embargoed" class="org.dspace.submit.model.AccessConditionOption"> <property name="groupName" value="Anonymous"/> <property name="name" value="embargo"/> <property name="hasStartDate" value="true"/> <property name="startDateLimit" value="+36MONTHS"/> <property name="hasEndDate" value="false"/> </bean>
- NOTE: It's possible to test the Date math syntax via command-line to see what the value would look like starting from today:
Code Block ./dspace dsrun org.dspace.util.DateMathParser +999YEARS Applied +999YEARS to implicit current time: Wed Jun 25 19:42:48 UTC 3023
- By default, DSpace comes with these out-of-the-box Access Conditions (which you can customize/change based on local requirements)
- "administrator" - access restricts the bitstream to the Administrator group immediately (after submission completes)
- "openAccess" - makes the bitstream immediately accessible to Anonymous group (after submission completes)
- "embargoed" - embargoes the bitstream for a period of time (maximum of 3 years, as defined in startDateLimit default setting), after which it becomes anonymously accessible. See also Embargo for discussion of how embargoes work in DSpace.
- "lease" - makes the bitstream anonymously accessible immediately (after submission completes), but that access expires after a period of time (maximum of 6 months, as defined in endDateLimit default setting). After that date it is no longer accessible (except to Administrators)
...