SIP Creator Command Line
Setting up the SIP Creator CLI
From Preservica 5.7 the entry point for the SIP Creator CLI will be included as part of the SIP Creator installer. Prior to this the provided script createsip.bat should be copied to the SIP Creator folder. Assuming the SIP Creator has been installed using the standard Windows installer this will be found in the following location:
C:\Preservica\Local\SIP Creator\
This folder will contain the following files:
SIP Creator.exe
SIP Creator.ico
SIP Creator.ini
The first time the createsip.bat script is run it will set up the SIP Creator CLI.
SIP Creator Command Line Interface
The Basics
The standard SIP Creator includes a command line interface (CLI) that allows SIPs to be programmatically created either individually or in bulk.
This section details how to create a SIP using the SIP Creator CLI, bulk creation of SIPs programmatically, or via generated lists of commands is beyond the scope of this guide.
The SIP Creator CLI can be started using the createsip command. Assuming the SIP Creator has been installed using the standard Windows installer this will be found in the following location:
C:\Preservica\Local\SIP Creator\createsip.bat (entry point)
C:\Preservica\Local\SIP Creator\library (library files)
By default, the SIP Creator CLI will use the version of Java installed by the standard Windows installer or the alternative Java specified at the point of installation. If this is not present Java must be installed on the machine and correctly included on the Windows PATH.
The SIP Creator CLI should be run from a suitable command prompt.
On Windows:
In the start menu search for and launch cmd.exe, this will open a terminal session. In the terminal change to the SIP Creator directory enter:
D:
If necessary to change to the appropriate drive
cd \Preservica\Local\SIP Creator
To change to the appropriate directory
The installation of the SIP Creator CLI can be tested by running createsip -h to list out the command line options as shown below:
Specifying Command Line Options
The behaviour of the SIP Creator CLI is controlled by a number of options provided after the createsip command. The options are space separated and the order of the options is not important. A number of the options take a value which is mandatory. The value must immediately follow the option. The option must be enclosed in double quotes if it contains a space character.
An option not requiring a value:
createsip -export
An option requiring an associated value:
createsip -input "c:\location\of\input\files"
The following options are mandatory:
-export
Instructs the SIP Creator CLI to generate a SIP
-input "c:\location\of\input\files"
Directory containing the source files
-output "c:\temp\SIPs"
Directory to contain the generated SIP
Generating a Simple SIP
If you wish to create a SIP that ingests into an existing collection (Corresponding to the Existing/Recent Collection option in the SIP Creator GUI) you must include the following options:
-colref 8d54d6ea-db30-44c3-9daa-29ba63823ef5
-status SAME
Where -colref specifies the Reference of an existing collection as taken from Explorer:
and -status SAME instructs SIP Creator CLI to generate a SIP that does not create a collection on ingest.
The full command would then be:
createsip -export -input "c:\location\of\input\files" -output "c:\temp\SIPs" -colref 8d54d6ea-db30-44c3-9daa-29ba63823ef5 -status SAME
If you wish to create a SIP that creates a new collection to ingest into (Corresponding to the New Collection option in the SIP Creator GUI) you should also include the following options:
-coltitle "New Collection Title"
Title of the new collection
-colcode "New Collection Code"
Collection code for the new collection
If you fail to specify the coltitle option the SIP will be created with the default name of "collection" and if you fail to specify the colcode option the SIP will be created with the default collection code of "code".
While you could also specify -status NEW this is not necessary as this is the default option.
The full command would then be:
createsip -export -input "c:\location\of\input\files" -output "c:\temp\SIPs" -coltitle "New Collection Title" -colcode "New Collection Code"
Command Line Options
In this section we will look at the available Command Line option as they correspond to options within the SIP Creator GUI.
SIP Options
These options correspond to the SIP Options section:
| Option | Value | Description |
|---|---|---|
| -input (or -i) | Valid file path e.g. c:\location\of\input\files | Location of the directory containing the files (and possibly sub-directories) from which to create the SIP to ingest. |
| -ignoreparent | none | This option corresponds to the "Do not create a deliverable unit for the parent folder checkbox." It has no corresponding value, if present the effect is the same as selecting the checkbox. |
| -singledu | none | This option corresponds to the Structure Type, Single Deliverable Unit radio button. If set the generated SIP will only contain a single DU corresponding to the specified directory. DUs will not be created for child DUs effectively flattening any directory hierarchy present. |
| -filedus | none | This option corresponds to the Structure Type, Represent each file and folder as a separate Deliverable Unit. If set DUs will be created for the specified directory and every sub-directory. In addition, a separate DU will be created for each file present and will only contain the corresponding file. |
If neither -singledu or -filedus is set the default Structure Type of Represent each folder as a separate Deliverable Unit will be used and a set of DUs will be created to mirror the directory structure under the specified directory with each DU containing the file object corresponding to the equivalent sub-directory.
Collection Options
These options correspond to the Collection Options section:
| Option | Value | Description |
|---|---|---|
| -status | NEW (default) or SAME | If NEW is specified, the SIP produced will be ingested into a new collection using the values specified. If SAME is specified, the colref parameter must be provide and the SIP produced will be ingested into the collection specified by the colref parameter. If this collection cannot be found the ingest will fail. |
| -coltitle | Title of the collection to create. Ignored if the status is SAME and will default to "collection" if not specified when the status is NEW. | |
| -colcode | Code of the collection to create. Ignored if the status is SAME and will default to "code" if not specified when the status is NEW. | |
| -colref | Unique reference for the collection. Required if the status is SAME and must correspond to a valid collection Reference within Preservica. Not required if the status is NEW causing the reference to be automatically generated but can be specified if required. |
Deliverable Unit Options
These options correspond to the Deliverable Unit Options section:
| Option | Value | Description |
|---|---|---|
| -catref | Used to specify the catalogue reference for all Deliverable Units created as part of the SIP. If not specified, the name of each directory will be used as its catalogue reference.This option can be used with the Preservica catalogue framework to specify the catalogue reference to synchronise with. | |
| -description | Used to specify the description for all Deliverable Units created as part of the SIP. If not specified, the name of each directory will be used as its description. | |
| -dutitle | Used to specify the title for all Deliverable Units created as part of the SIP. If not specified, the name of each directory will be used as its description.Please Note within the SIP Creator GUI this field can only be set on a DU by DU basis once the SIP. | |
| -surrogate | none | If set will cause the Digital Surrogate flag to be set for all Deliverable Units within the SIP produced. If not specified, the Digital Surrogate flag will not be set indicating a digital original. |
| -securitytag | Used to specify the security tag of all Deliverable Units created (and the security tag of the collection if one is created). If not set the default security tag of "open" will be used. If a non-existent security tag is specified, the SIP may fail validation during ingest depending on your system configuration. | |
| -metadataname | Used to specify the name of one or more files containing XML metadata. If specified any files matching the name provided will not be ingested as digital files. Instead the XML within each file will be extracted and used as metadata for the Deliverable Unit in which it is found. | |
| -duCoverageFrom | date in the format: yyyy-mm-dd e.g. 2013-05-23 | Used to specify the coverage from date for all Deliverable Units created as part of the SIP. If not specified this will default to the earliest file date found within the deliverable unit.Please Note within the SIP Creator GUI this field can only be set on a DU by DU basis once the SIP has been created but prior to it being exported. |
| -duCoverageTo | date in the format: yyyy-mm-dd e.g. 2013-05-23 | Used to specify the coverage from date for all Deliverable Units created as part of the SIP. If not specified this will default to the latest file date found within the deliverable unit.Please Note within the SIP Creator GUI this field can only be set on a DU by DU basis once the SIP has been created but prior to it being exported. |
Manifestation Options
This option corresponds to the Manifestation Options section:
| Option | Value | Description |
|---|---|---|
| -initManifType | Used to specify the type of manifestation created as part of the generated SIP. The manifestation ID should be specified. This can vary on an installation by installation basis but typically: 1) Preservation manifestation 2) Presentation manifestation 4) Container manifestation 5) Physical manifestation |
File Options
This option corresponds to the File Options section:
| Option | Value | Description |
|---|---|---|
| -md5 | none | Set by default resulting in MD5 fixity checksums being generated for all digital files. |
| -sha1 | none | If set will result in SHA-1 fixity checksums being generated for all digital files. |
| -sha256 | none | If set will result in SHA-256 fixity checksums being generated for all digital files. |
| -sha512 | none | If set will result in SHA-512 fixity checksums being generated for all digital files. |
Generic Metadata
This option corresponds to the Generic Metadata section:
| Option | Value | Description |
|---|---|---|
| -coltemplate | Full name, including path of a file containing XMLmetadata. If set this metadata will treated as a template entry and a copy applied to the Collection in the generated SIP. Ignored if status of SAME is selected. | |
| -dutemplate | Full name, including path of a file containing XML metadata. If set this metadata will treated as a template entry and a copy applied to all Deliverable Units in the generated SIP. | |
| -filetemplate | Full name, including path of a file containing XML metadata. If set this metadata will treated as a template entry and a copy applied to all Digital Files in the generated SIP. | |
| -mantemplate | Full name, including path of a file containing XML metadata. If set this metadata will treated as a template entry and a copy applied to all Manifestations in the generated SIP. |
Any bulk metadata files (i.e. the “myfile.doc.metadata” files) present in the directory structure that the SIP is created against are handled as described in the SIP Creator SUG.
Other Standard Options
| Option | Value | Description |
|---|---|---|
| -export (or -e) | none | Mandatory - this option must always be present. |
| -output (or -o) | Mandatory - Specifies the directory in which to placethe generated SIPs. | |
| -excludedFileNames | Corresponds to the Files to Ignore list in the SIP Creator Settings. This a comma separated list of file (e.g. desktop.ini,thumbs.db) that will be ignored and not included in any generated SIPs. Please Note: Wildcards are not supported within the filenames. | |
| -help | none | Prints a list of the command line options available. |
Advanced Options
The following advanced options are available within the SIP Creator CLI only and do not have an equivalent setting within the SIP Creator GUI:
-manifestations BOOLEAN
If set the structure should following the multiple manifestation pacakge definition to create multiple manifestations (see the Multiple Manifestation Package chapter in Standard Workflows for details)
-sipconfigpath PATH XML
file containing configuration to apply to SIP
These options are reserved for future use.
Preservica on Github
Open API library and latest developments on GitHub
Visit the Preservica GitHub page for our extensive API library, sample code, our latest open developments and more.
Preservica.com
Protecting the world’s digital memory
The world's cultural, economic, social and political memory is at risk. Preservica's mission is to protect it.