JobParams

JobParams

The JobParams class provides a way of converting a simple set of parameters into a DART job. See the JobParams#toJob method for details on how this small data structure is converted to a Job.

Constructor

new JobParams(opts)

Parameters:
Name Type Description
opts object
Properties
Name Type Attributes Description
workflowName string

The name of the workflow to run. The JobParams#toJob method will create a Job that includes all of the components of the named Workflow, including packaging, validation, and upload to one or more targets. Be sure to name an existing Workflow, or you'll get an error when you call JobParams#toJob.
packageName string <optional>

The name of the package/file your job will create. This may be a tar or zip file. For example, "virginia.edu.Photos_2019-06-26.tar", "pdfs.zip", etc. This parameter is required if your job will be creating a package.
files string <optional>

An array of file paths. These are the files that the job will be packaging and/or uploading. These should be absolute paths.
tags Array.<TagDefinition> <optional>

These are required only if your job will be creating a package in BagIt, OCFL, or another format that requires metadata in name-value pairs. These values will be written into the package. Per the BagIt specification, repeated tags (those with the same tagFile and tagName) will be written in the same order in which they appear in the opts.tags array.
Source:
Example
let opts = {
	workflowName: "Name of Workflow",
	packageName: "test.edu.my_files.tar",
	files: [
		"/path/to/first/directory",
		"/path/to/second/directory",
		"/path/to/some/document.pdf"
	],
	tags: [
		{
			"tagFile": "bag-info.txt",
			"tagName": "Bag-Group-Identifier",
			"userValue": "Photos_2019"
		},
		{
			"tagFile": "aptrust-info.txt",
			"tagName": "Title",
			"userValue": "Photos from 2019"
		},
		{
			"tagFile": "aptrust-info.txt",
			"tagName": "Description",
			"userValue": "What I did with my summer vacation."
		},
		{
			"tagFile": "custom/legal-info.txt",
			"tagName": "License",
			"userValue": "https://creativecommons.org/publicdomain/zero/1.0/"
		}
	]
}

let jobParams = new JobParams(opts);

// Create a job and save it to the DART Jobs database.
let job = jobParams.toJob();
job.save();

// Or just write the job directly to a JSON file.
jobParams.toJobFile("/tmp/dart/job_file.json");

Members

errors :object.<string, string>

A hash of validation errors for this JobParams object. Keys are the names of invalid properies. Values are error messages (strings) describing why the field is invalid.

Source:

files :Array.<string>

A list of files to package and/or upload. These should be absolute paths.

Source:

packageName :string

The name of the package or output file to create.

Source:

tags :Array.<TagDefinition>

A list of metadata tags to include in the package.

Source:

workflowName :string

The name of the workflow. This workflow will provide the template for the job.

Source:

Methods

(static) inflateFrom(data) → {JobParams}

This converts a generic hash/object into an JobParams object. this is useful when loading objects from JSON.

Parameters:
Name Type Description
data object

An object you want to convert to an JobParams. The object should include the same properties as a JobParams object.
Source:

_buildJob() → {Job}

Builds a Job object based on the workflow and other params specified in this JobParams object. Returns the object, but does not save it to the DART Jobs database. It's up to the caller to do that, if they so choose.

Source:

_getOutputPath() → {string}

Returns the output path of the package that will be built during the Job's packaging stage.

Source:

_groupedTags() → {object}

Returns an object in which tags having the same tagFile and tagName are grouped. The order of the tags within each group is preserved. The key to each object is tagFile/tagName and the value is a list of tags having that tagFile and tagName.

Source:

_loadBagItProfile() → {boolean}

Sets this._bagItProfile to the BagItProfile object whose id is stored in this._workFlowObj.bagItProfileId, or does nothing if no profile id is specified. Returns false and sets this.errors['bagItProfile'] if a profile id was specified but no matching BagItProfile could be found. Returns true otherwise. If this returns false, the caller should assume that no further operations on this object will succeed.

Source:

_loadWorkflow() → {boolean}

Loads the Workflow from the DART Worflow database whose name matches this.workflowName and stores it in this._workflowObj. Returns true if it was able to load the Workflow. Returns false if there is no such workflow in the database.

If this returns false, the caller should check this.errors['workflow'] and should assume that no further operations will succeed.

Source:

_makePackageOp(job)

Creates the PackageOperation for the Job returned by JobParams#buildJob.

Parameters:
Name Type Description
job Job
Source:

_makeUploadOps(job)

Creates the UploadOperations for the Job returned by JobParams#buildJob.

Parameters:
Name Type Description
job Job
Source:

_mergeTags(job)

Merge tags from this.tags into the Job's copy of the BagItProfile. Note that this.tags may include 1..N instances of a tag that is defined 1 time in the BagItProfile. In those cases, this merge function ensures that all values from this.tags will be copied, and that any validation constraints on the original TagDefinition in the BagItProfile will be copied to all instances of the tag. Those constraints include the "required" attribute and the list of valid values in the "values" attribute.

Parameters:
Name Type Description
job Job
Source:

_mergeTagSet(bagItProfile, tags, profileTags)

Merges one or more values from this.tags into job.bagItProfile.tags. Note the following behaviors:

  1. If tags contains one tag with tagFile "bag-info.txt" and tagName "My-Tag", and profileTags also has one tag with that tagFile and tagName, the userValue from the tags version will be copied into the userValue from the profileTags version. That latter version persists in bag.bagItProfile.tags. When it's time to create the bag, the value will be copied from bag.bagItProfile.tags into the tag file.

  2. If tags and profileTags each contain multiple copies of a tag with a given tagFile/tagName combination, all userValues from tags will be copied into the corresponding profileTags.

  3. If tags contains more copies of a tag than are defined in profileTags, this method will add new tags to profileTags, each with a userValue copied from tags.

Parameters:
Name Type Description
bagItProfile BagItProfile

The job.bagItProfile object into which you want to merge tags. Tags in the job's copy of the BagItProfile will have their userValue property updated with the userValue from matching items in the tags list. Items in the tags list that do not exist in the bagItProfile will be added.
tags Array.<object>

A list of tags from this JobParams object that have the same tagFile and tagName attributes.
profileTags Array.<TagDefinition>

A list of tags from the job.bagItProfile.tags list that have the same tagFile and tagName properties as those in the tags list (second param).
Source:

_setSerialization()

This sets the bagItSerialization attribute of the job's PackageOperation, if necessary. Because DART supports only tar serialization (as of July, 2020), this only looks for and sets the values 'application/tar' or 'application/x-tar'.

This method will need to be revisited in the future as DART supports more serialization formats.

Source:

toJob()

Converts the JobParams to a Job object, which DART can then run. This performs the following operations to create a job:

  1. Loads the Workflow speficied in this.workflowName.

  2. Creates a Job object patterned after that Workflow.

  3. Copies the packageName and files (if specified) into the new Job object.

  4. If the Workflow includes a BagItProfile, this copies this.tags into a copy of that BagItProfile. Typically, most tag values in a DART BagItProfile, such as "Source-Organization", "Contact-Email", etc. are set to default values because they do not change from one bag to the next. More specific values, such as "Title", "Description", or "Internal-Sender-Identifier" do change from bag to bag. The JobParams#tags property allows you to overwrite bag-specific tag values withouth having to re-specify any default tag values. Any values you specify in JobParams#tags will overwrite tag values in the job-specific copy of the BagItProfile.

Source:

toJobFile(pathToFile)

This does the same as JobParams#toJob, but instead of returning the Job object, it writes it as JSON to the specified file.

Parameters:
Name Type Description
pathToFile string

The path to the file where you want to write a JSON description of this job.
Source:

validate()

Validates this JobParams object to ensure it can build a valid job.

THIS IS NOT YET IMPLEMENTED.

Source: