Problem: The custom structmap (mets_structmap.xml) functionality of Archviematica isn't documented

[ross-spencer]

Please describe the problem you'd like to be solved.

I would like to see the ability to provide a custom structmap with an Archivematica transfer; and the ability to add one to an Archivematica SIP, documented better.

At present, looking at the pages which reference structmaps in the docs, they all seem to describe those created by the system:

• https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/archival-storage/aip-structure/
• https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/archival-storage/aic/
• https://www.archivematica.org/en/docs/archivematica-1.8/getting-started/troubleshooting/faq/
• https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/transfer/import-metadata/
• https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/administer/dashboard-admin/#document-empty-directories
• https://www.archivematica.org/en/docs/archivematica-1.8/user-manual/ingest/ingest/#arranging-a-sip-for-atom

Yet, it is also possible to add a logical structmap at point of ingest in its own file and it will be reflected in the Archivematica METS. As an example you can run this sampledata tranfer: https://github.com/artefactual/archivematica-sampledata/tree/master/SampleTransfers/structMapSample

There are two methods of providing a custom structmap:

1. In a transfer, in the metadata folder.
2. At ingest one can be added to a SIPs directory after it comes out of the backlog and before it is approved, some of that is discussed in the comments here: Problem: The purpose of 'Verify mets_structmap.xml' during ingest is not clear. #286 (comment)

Both features are verified to work.

Describe the solution you'd like to see implemented.

Describe how a user would go about providing a structmap in either scenario and the specifics of how that structmap should be configured. For example, using the FILEID to provide a filepath (at present)

    <mets:div TYPE="page" LABEL="Inside cover">
      <mets:fptr FILEID="inside_cover.jpg"/>
    </mets:div>

For ingest, we might ask a user have SFTP access to the SIPCreation/SIPsUnderConstruction folder so that they have the ability to place a structmap as required.

We can also describe the output and how that will look in the METS where the file path is replaced with the actual FILEID:

	<mets:div TYPE="page" LABEL="Inside cover">
		<mets:fptr FILEID="file-18959b8f-14c7-46ec-b97f-504a4a06e27d"/>
	</mets:div>

NB. Users should beware that initially, their own structmap will not validate as METS despite looking like METS. Our workaround to providing this capability is very much using the document as a template, and the filepaths once replaced enables the METS extract to validate correctly.

Limitations might be discussed such as only allowing for one structmap (or do we need to answer the question "can multiple structmaps be placed in the same reserved file (mets_structmap.xml) for inclusion in the AIP?")

Additional context

• There is some discussion about the feature on the old Google Group: https://code.google.com/archive/p/archivematica/issues/977
• This ticket here is actually better understood now, and so it has been marked as a documentation issue and it can be closed by whomever takes this ticket on whenever that may be: Problem: The purpose of 'Verify mets_structmap.xml' during ingest is not clear. #286
• Related to: Problem: Archivematica's mechanism to import custom structmaps can only describe flat structures, e.g. no nested-dirs, and only for files with limited character-sets, e.g. not even spaces are allowed #283 (which might change this documentation, so we might want to consider that ticket's impact first)
• Related to Problem: We haven't a canonical list of reserved files and folders that can be associated with and influence a transfer #284 (where we don't have a centralised list of reserved files and how they should be used in Archivematica, e.g. the naming convention and use for mets_structmap.xml)

---

For Artefactual use:
Please make sure these steps are taken before moving this issue from Review to Verified in Waffle:

• All PRs related to this issue are properly linked 👍
• All PRs related to this issue have been merged 👍
• Test plan for this issue has been implemented and passed 👍
• Documentation regarding this issue has been written and it has been added to the release notes, if needed 👍

[peterVG]

Added initial structmap docs to 'import metadata' page in user manual. artefactual/archivematica-docs#274

[ross-spencer]

Hi @peterVG I meant to say, the diff here will show the changes we need to make to the docs so folks can use the feature: artefactual/archivematica-sampledata@0b4fb32

I am tempted to modify the sample data, or make a recommendation, that for most uses, and for users to be safe in the knowledge this will work for them, they populate FILEID with something fairly benign just as a placeholder. FILE001 FILE002 but I don't want to suggest that encodes anything either. It's just the FILEID cannot be blank. And there are a lot of restrictions on the field, I document some of those here: #283