Items and item sets¶

The item:* and item-set:* commands list, search, export and import items and item sets. The media:* commands add media to items.

Exports are portable JSON-LD: one resource per file, which you can import into another installation. This is how you seed a demo or test installation with content that you curated on another one. See Export items for what the format keeps.

List and search items¶

omeka-s-cli item:list

+----+-------------------------+-------------------+----------+----------+-------+--------+
| Id | Title                   | Class             | Template | ItemSets | Media | Public |
+----+-------------------------+-------------------+----------+----------+-------+--------+
| 1  | Mona Lisa               | dctype:StillImage |          | 1        | 1     | yes    |
| 2  | Study for the Mona Lisa |                   |          | 0        | 0     | yes    |
+----+-------------------------+-------------------+----------+----------+-------+--------+

The command shows 50 items at a time; use --limit and --page for more. Filter by resource class, resource template, item set, site, or exact property value (--property, -p, repeatable):

omeka-s-cli item:list --class dctype:StillImage --property "dcterms:creator=Leonardo da Vinci"

--public and --private filter on visibility, and --query passes any other Omeka S API search parameter, such as --query "sort_by=title&sort_order=desc".

item:search searches the text of all properties, with the same filters:

omeka-s-cli item:search leonardo

item-set:list and item-set:search do the same for item sets. --json and --csv give the data for scripts.

Export items¶

item:export takes item ids, or the same filters as item:list. One item is printed:

id=$(omeka-s-cli item:list --property dcterms:identifier=obj-2 --json | jq '.[0].id')
omeka-s-cli item:export "$id" --reference-by dcterms:identifier

{
    "@context": {
        "dcterms": "http://purl.org/dc/terms/",
        "o": "http://omeka.org/s/vocabs/o#",
        "o-ref": "https://omeka-s-contrib.github.io/omeka-s-ref/ns#"
    },
    "@type": "o:Item",
    "o-ref:id": {
        "dcterms:identifier": "obj-2"
    },
    "o:title": "Study for the Mona Lisa",
    "o:is_public": true,
    "dcterms:title": [
        {
            "type": "literal",
            "is_public": true,
            "@value": "Study for the Mona Lisa"
        }
    ],
    "dcterms:identifier": [
        {
            "type": "literal",
            "is_public": true,
            "@value": "obj-2"
        }
    ],
    "dcterms:relation": [
        {
            "type": "resource:item",
            "is_public": true,
            "o-ref:ref": {
                "dcterms:identifier": "obj-1"
            }
        }
    ]
}

Several items go to a directory, one file each (<id>-<title>.jsonld); --output writes one item to a file:

omeka-s-cli item:export --class dctype:StillImage --output-dir ~/export --reference-by dcterms:identifier

The export is Omeka S's JSON-LD, made portable:

• The @context is written into the file.
• Everything that only means something on this installation is left out: ids, owner, dates, property_id, thumbnails.
• References use names instead of ids: the class term, the template label, the site slug.
• Item sets and linked items are written as o-ref:ref, and the item itself gets an o-ref:id, both with the property you choose with --reference-by (default dcterms:title). Choose a property whose values are unique, such as an identifier. A record without a value for it is reported, and its link is left out.

Media and data from modules (such as the Mapping module) are not exported; the command lists what it left out. Warnings go to standard error when the export goes to standard output, so you can redirect or pipe it.

item-set:export exports item sets the same way:

omeka-s-cli item-set:export --output-dir ~/export/item-sets --reference-by dcterms:identifier

Import an item set¶

item-set:import creates an item set from a JSON-LD file or URL that holds one item set:

omeka-s-cli item-set:import ~/content/paintings.jsonld

{
    "@context": {
        "dcterms": "http://purl.org/dc/terms/",
        "dctype": "http://purl.org/dc/dcmitype/",
        "o": "http://omeka.org/s/vocabs/o#",
        "o-ref": "https://omeka-s-contrib.github.io/omeka-s-ref/ns#"
    },
    "@type": "o:ItemSet",
    "o-ref:id": {"dcterms:identifier": "set-paintings"},
    "o:title": "Paintings",
    "o:is_public": true,
    "o:is_open": true,
    "dcterms:title": [{"type": "literal", "is_public": true, "@value": "Paintings"}],
    "dcterms:identifier": [{"type": "literal", "is_public": true, "@value": "set-paintings"}]
}

Import the item sets before the items that belong to them.

Import an item¶

item:import creates an item from a JSON-LD file or URL that holds one item. Add media with --media (-m), as ingester=source, once per media:

omeka-s-cli item:import ~/content/mona-lisa.jsonld --media "upload=$HOME/content/mona-lisa.png"

{
    "@context": {
        "dcterms": "http://purl.org/dc/terms/",
        "dctype": "http://purl.org/dc/dcmitype/",
        "o": "http://omeka.org/s/vocabs/o#",
        "o-ref": "https://omeka-s-contrib.github.io/omeka-s-ref/ns#"
    },
    "@type": ["o:Item", "dctype:StillImage"],
    "o-ref:id": {"dcterms:identifier": "obj-1"},
    "o:title": "Mona Lisa",
    "o:is_public": true,
    "o:resource_class": {"o:term": "dctype:StillImage"},
    "o:item_set": [{"o-ref:ref": {"dcterms:identifier": "set-paintings"}}],
    "dcterms:title": [{"type": "literal", "is_public": true, "@value": "Mona Lisa"}],
    "dcterms:creator": [{"type": "literal", "is_public": true, "@value": "Leonardo da Vinci"}],
    "dcterms:identifier": [{"type": "literal", "is_public": true, "@value": "obj-1"}],
    "dcterms:source": [{"type": "uri", "is_public": true, "@id": "https://en.wikipedia.org/wiki/Mona_Lisa", "o:label": "Wikipedia"}]
}

Item 'Mona Lisa' created (id 1).

The upload ingester takes a local path or a URL. The other ingesters take what Omeka S expects: a URL for url, iiif, iiif_presentation, oembed and youtube, and HTML for html. The item and its media are created together: if Omeka S rejects a media file (for example, an extension that is not allowed), the item is not created either.

--site (-s, repeatable) assigns the item to a site, by slug or title, instead of the sites in the file. When none of the names matches a site, the item goes to the default site. Without --site, the file's o:site applies. Without either (or without a default site), Omeka S adds the item to every site that takes new items. Put --site after the file: it takes several values.

omeka-s-cli item:import ~/content/sketchbook.jsonld --site collections

Options for a media follow its source, separated by ;: title, altText, public, a property term such as dcterms:description, or anything else the ingester takes, such as YouTube's start (see Add media to an item). Write a ; inside a value as \;. A --media value can also be a JSON media object.

omeka-s-cli item:import ~/content/lecture.jsonld \
    --media 'youtube=https://www.youtube.com/watch?v=dQw4w9WgXcQ;start=30;title=Recording'

References in the file are resolved on the installation you import into:

• o:item_set and links to other items ("o-ref:ref": {"dcterms:identifier": "obj-1"}) name a property and a value. Import the records they point to first.
• o:resource_class is a term and o:resource_template a label.
• Properties are matched by vocabulary namespace, so a file may use another prefix than the installation does.

A reference that matches nothing, or more than one record, is an error: the import fails and the item is not created, so it never loses a link without notice. Two items that link to each other (for example dcterms:hasPart and dcterms:isPartOf) cannot both be imported as exported: the first one's link has nothing to point to yet. Keep the link only in the file you import second. An item that already exists is skipped, even when its file has such a problem.

omeka-s-cli item:import ~/content/study.jsonld

Import with a configuration file¶

To import an item with several media, or to keep an import repeatable, describe it in a JSON file and pass it with --config. Relative paths in it are relative to the file. It takes the JSON-LD source, the item's sites, and its media as media objects; the title is only used in messages:

{
    "source": "portrait.jsonld",
    "title": "Portrait of a woman",
    "sites": ["collections"],
    "media": [
        { "ingester": "upload", "source": "mona-lisa.png", "title": "Front", "altText": "A woman, half-length" },
        { "ingester": "iiif",
          "source": "https://iiif.io/api/image/3.0/example/reference/918ecd18c2592080851777620de9bcb5-gottingen/info.json" }
    ]
}

omeka-s-cli item:import --config ~/content/portrait.import.json

Without a source, the file creates an item from a title alone (its dcterms:title), with its itemSets (by title), sites and media. Any other property needs a JSON-LD file:

{
    "title": "Notebook page",
    "itemSets": ["Paintings"],
    "media": [
        { "ingester": "html", "source": "<p>Notes on light and shade.</p>" }
    ]
}

omeka-s-cli item:import --config ~/content/notebook.import.json

--site can't be combined with a configuration file: put the sites in the file. A configuration file has the same shape as a blueprint's x-omeka-s-cli.items entry, see Content.

Import without creating duplicates¶

Before creating a resource, item:import looks for it on the installation: by its o-ref:id (a property and a value, written by item:export), else by its title. When it exists, the command changes nothing, prints a notice and exits with code 0. So you can run the same import again:

omeka-s-cli item:import ~/content/mona-lisa.jsonld --dry-run

Item 'Mona Lisa' already exists (id 1); skipped.

A resource with neither an o-ref:id nor a title cannot be matched: it is created on every import, and the command warns about it.

--dry-run reports what would happen without creating anything. --identify-by <term> matches on another property of the file, and --json prints the result (created, exists, ambiguous or would create) as JSON.

When an import fails¶

The command checks what Omeka S cannot handle on its own, and reports every problem of the file at once. Nothing is created:

if ! omeka-s-cli item:import ~/content/letter.jsonld; then
    echo "Install what is missing, then import again." >&2
fi

letter.jsonld: property "letters:recipient" uses vocabulary https://example.org/ns/letters#, which is not installed (vocabulary:import)
letter.jsonld: property "dcterms:date": data type "numeric:timestamp" is not available (install the NumericDataTypes module)

{
    "@context": {
        "dcterms": "http://purl.org/dc/terms/",
        "letters": "https://example.org/ns/letters#"
    },
    "@type": "o:Item",
    "o:title": "Letter to Ludovico Sforza",
    "dcterms:title": [{"type": "literal", "@value": "Letter to Ludovico Sforza"}],
    "letters:recipient": [{"type": "literal", "@value": "Ludovico Sforza"}],
    "dcterms:date": [{"type": "numeric:timestamp", "@value": "1482"}]
}

Install the vocabulary (see Vocabularies) or the module (see Modules) and import again. Omeka S checks the rest itself, such as the properties a resource template requires.

Add media to an item¶

media:ingesters lists the ways media can be added on the installation:

omeka-s-cli media:ingesters

+-------------------+-------------------+
| Name              | Label             |
+-------------------+-------------------+
| upload            | Upload            |
| url               | URL               |
| html              | HTML              |
| iiif              | IIIF image        |
| iiif_presentation | IIIF presentation |
| oembed            | oEmbed            |
| youtube           | YouTube           |
+-------------------+-------------------+

media:add adds one media to an existing item. --source is what the ingester ingests; --title and --alt-text are optional. The same source works for every core ingester:

url, iiif, iiif_presentation, oembed and youtube fetch from the internet when the media is added.

omeka-s-cli media:add "$id" --ingester upload --source ~/content/mona-lisa.png --title "Scan"

omeka-s-cli media:add "$id" --ingester url \
    --source https://iiif.io/api/image/3.0/example/reference/918ecd18c2592080851777620de9bcb5-gottingen/full/max/0/default.jpg

omeka-s-cli media:add "$id" --ingester html --source '<p>Preparatory drawing, about 1503.</p>'

omeka-s-cli media:add "$id" --ingester iiif \
    --source https://iiif.io/api/image/3.0/example/reference/918ecd18c2592080851777620de9bcb5-gottingen/info.json

omeka-s-cli media:add "$id" --ingester iiif_presentation \
    --source https://iiif.io/api/cookbook/recipe/0001-mvm-image/manifest.json

omeka-s-cli media:add "$id" --ingester oembed --source https://www.youtube.com/watch?v=dQw4w9WgXcQ

omeka-s-cli media:add "$id" --ingester youtube --source https://youtu.be/dQw4w9WgXcQ

What an ingester takes can't be predicted, especially for ingesters added by modules. Give the media as a JSON object with --data, or in a file with --json-file:

omeka-s-cli media:add "$id" --data '{
    "ingester": "youtube",
    "source": "https://youtu.be/dQw4w9WgXcQ",
    "start": "30",
    "title": "Recording",
    "dcterms:description": "The first minute of the talk"
}'

• ingester is required.
• source goes where the ingester reads it: ingest_source for upload, ingest_url for url, html for html, o:source for any other ingester.
• title, altText and public set the media's dcterms:title, o:alt_text and o:is_public.
• A property term (dcterms:description) takes a string, a list of strings or JSON-LD values.
• Every other key is passed to the ingester unchanged, for example YouTube's start and end, or a module ingester's own key. A raw key such as o:source wins over a mapped one.

The flags (--ingester, --source, --title, --alt-text) are shortcuts and override the JSON. With --json-file, a relative upload source is relative to the file. The same media objects go in an item:import configuration file and in --media.

Reference¶

All commands also accept the global options.

item:list¶

List items

omeka-s-cli item:list [options]

item:search¶

Search items by text

omeka-s-cli item:search [options] <text>

item:export¶

Export items as portable JSON-LD

omeka-s-cli item:export [options] [ids...]

item:import¶

Import one item from a JSON-LD file or URL

omeka-s-cli item:import [options] [source]

item-set:list¶

List item sets

omeka-s-cli item-set:list [options]

item-set:search¶

Search item sets by text

omeka-s-cli item-set:search [options] <text>

item-set:export¶

Export item sets as portable JSON-LD

omeka-s-cli item-set:export [options] [ids...]

item-set:import¶

Import one item set from a JSON-LD file or URL

omeka-s-cli item-set:import [options] [source]

media:add¶

Add a media to an item

omeka-s-cli media:add [options] <item>

media:ingesters¶

List the media ingesters (the ways media can be added)

omeka-s-cli media:ingesters [options]