CMIS Server: verschil tussen versies

Uit Wiki Memorix Archieven
← Oudere bewerkingNieuwere bewerking →
Geen bewerkingssamenvatting
Replaced content with "[https://picturae.com/images/memorix_archieven_handleidingen/User_Manual_CMIS_Server.pdf Engelstalige handleiding van de CMIS server]"
Regel 1: Regel 1:
= Archivematica CMIS Server User Manual =
[https://picturae.com/images/memorix_archieven_handleidingen/User_Manual_CMIS_Server.pdf Engelstalige handleiding van de CMIS server]
 
This manual will cover the way how to access AIPs and AIP files
 
that were ingested and stored in Archivematica Storage Service.
 
'''Links and References:'''
 
<ul>
<li><p>[http://docs.oasis-open.org/cmis/CMIS/v1.1/errata01/os/CMIS-v1.1-errata01-os-complete.html CMIS Specification]</p></li>
<li><p>[https://chemistry.apache.org/java/opencmis.html Apache Chemistry Open CMIS]</p>
<p>This resorce gathered all needed information for Developers and Users of CMIS Protocol.</p></li>
<li><p>[https://chemistry.apache.org/java/developing/tools/dev-tools-workbench.html CMIS Workbench]</p>
<p>Useful tool for Browsing and Testing CMIS Server.</p></li></ul>
 
'''Features Implemented:'''
 
<ul>
<li><p>Segregated User Access to AIPs per Location.</p>
<p>User can access AIPs from particular location.</p></li>
<li><p>Browse All Ingested AIPs in Location.</p></li>
<li><p>Browse File&amp;Folders structure of AIP.</p></li>
<li><p>Download whole AIP.</p></li>
<li><p>Download particular AIP’s File.</p></li></ul>
 
== Connecting to CMIS ==
 
Current implementation of CMIS allows only
 
[http://docs.oasis-open.org/cmis/CMIS/v1.1/errata01/os/CMIS-v1.1-errata01-os-complete.html#x1-5360005 Browser Binding] connections. So CMIS Clients must use Browser Binding only.
 
Before connection to CMIS Server make sure you have your credentials (user and password)
 
and CMIS Endpoint to access it.
 
Example:
 
* Username – <code>demo</code>
* Password – <code>demo</code>
* URL – <code>http://pic-devel.edepot.picturae.com/</code>
 
For testing purposes it is recommended to use CMIS Workbench (see link above).
 
That can help to understand the overall CMIS Protocol and its Data Structures.
 
For Development bare CMIS Clients you can follow steps from Next Paragraph
 
=== Browser Binding API ===
 
All requests to CMIS Server must include [https://tools.ietf.org/html/rfc7617 HTTP Basic Authentication]
 
with your Username and Password.
 
Example HTTP Request:
 
<source lang="http">
GET / HTTP/1.1
 
Host: pic-devel-cmis.edepot.picturae.com
 
Authorization: Basic ZGVtbzpkZW1v
</source>
Authorization header contains base64 encoded string with credentials <code>demo:demo</code>.
 
In the following sections we assume that all request includes Authorization header
 
and requests are sent to CMIS Endpoint URL. For example <code>GET /</code> will be translated to
 
HTTP Request as following:
 
<source lang="http">
GET /
 
Host: your-cmis-server-endpoint.nl
 
Authorization: Basic <YOUR ENCODED CREDENTIALS>
</source>
==== Getting CMIS Repository ====
 
Request:
 
<source lang="http">
GET /
</source>
Response:
 
<source lang="json">
{
 
    "ea550466-7dff-4b57-844e-c1163b3a7168": {
 
        "repositoryId": "ea550466-7dff-4b57-844e-c1163b3a7168",
 
        "repositoryName": "Archivematica Repository",
 
        "repositoryDescription": "Repository for Accessing Archivematica AIPs",
 
        "vendorName": "Picturae",
 
        "productName": "Picturae CMIS Server",
 
        "productVersion": "0.0.1",
 
        "rootFolderId": "root",
 
        "latestChangeLogToken": null,
 
        "capabilities": {
 
            "capabilityACL": "none",
 
            "capabilityAllVersionsSearchable": false,
 
            "capabilityChanges": "none",
 
            "capabilityContentStreamUpdatability": "none",
 
            "capabilityGetDescendants": false,
 
            "capabilityGetFolderTree": false,
 
            "capabilityOrderBy": "none",
 
            "capabilityMultifiling": false,
 
            "capabilityPWCSearchable": false,
 
            "capabilityPWCUpdatable": false,
 
            "capabilityQuery": "none",
 
            "capabilityRenditions": "read",
 
            "capabilityUnfiling": false,
 
            "capabilityVersionSpecificFiling": false,
 
            "capabilityJoin": "none",
 
            "capabilityCreatablePropertyTypes": null,
 
            "capabilityNewTypeSettableAttributes": null
 
        },
 
        "aclCapability": null,
 
        "cmisVersionSupported": "1.1",
 
        "thinClientURI": null,
 
        "changesIncomplete": null,
 
        "changesOnType": [],
 
        "principalAnonymous": null,
 
        "principalAnyone": null,
 
        "extendedFeatures": [],
 
        "rootFolderUrl": "https://pic-devel-cmis.edepot.picturae.com/ea550466-7dff-4b57-844e-c1163b3a7168/root",
 
        "repositoryUrl": "https://pic-devel-cmis.edepot.picturae.com/ea550466-7dff-4b57-844e-c1163b3a7168"
 
    }
 
}
</source>
Response contains a list of single Repository that user can access.
 
(multiple repositories is not yet supported).
 
Repository Info contains few major parts which must be used in next sections:
 
<ul>
<li><p><code>repositoryId</code> – this field contains unique repositoryId</p></li>
<li><p><code>rootFolderId</code> – CMIS Object ID for root folder to repository.</p>
<p>In current implementation it is always <code>root</code></p></li>
<li><p><code>repositoryUrl</code> and <code>rootFolderUrl</code> – these urls MUST be used as entrypoints for further</p>
<p>communication with Repository (like Get Object, Get Children, Get Content, etc… )</p>
<p>Repository URL and Root Folder URL will use current CMIS Server Hostname and Repository ID</p></li></ul>
 
==== Getting List of Ingested AIPs ====
 
In order to obtain the list of your ingested AIPs use following URL
 
<source lang="http">
GET {rootFolderUrl}/?cmisselector=children&succinct=true
</source>
Response Example:
 
<source lang="json">
{
 
    "numItems": 1,
 
    "moreItems": false,
 
    "objects": [
 
        {
 
            "object": {
 
                "id": "aba7175b-856e-4b03-9201-e9ce551c0f9f",
 
                "relationship": [],
 
                "changeEventInfo": null,
 
                "acl": null,
 
                "exactACL": null,
 
                "policyIds": null,
 
                "renditions": [
 
                    {
 
                        "streamId": "aba7175b-856e-4b03-9201-e9ce551c0f9f",
 
                        "mimeType": "application/x-tar",
 
                        "length": 17408095,
 
                        "kind": "package",
 
                        "title": "Archived Package",
 
                        "height": null,
 
                        "width": null,
 
                        "renditionDocumentId": null
 
                    }
 
                ],
 
                "succinctProperties": {
 
                    "cmis:name": "Test_dubbellebestanden2_20180727_2-aba7175b-856e-4b03-9201-e9ce551c0f9f",
 
                    "cmis:description": "Test_dubbellebestanden2_20180727_2-aba7175b-856e-4b03-9201-e9ce551c0f9f",
 
                    "cmis:objectId": "aba7175b-856e-4b03-9201-e9ce551c0f9f",
 
                    "cmis:baseTypeId": "cmis:folder",
 
                    "cmis:objectTypeId": "cmis:folder",
 
                    "cmis:secondaryObjectTypeIds": null,
 
                    "cmis:createdBy": "Admin",
 
                    "cmis:creationDate": 946681200,
 
                    "cmis:lastModifiedBy": "Admin",
 
                    "cmis:lastModificationDate": 946681200,
 
                    "cmis:changeToken": "946681200",
 
                    "cmis:parentId": "root",
 
                    "cmis:path": "/Test_dubbellebestanden2_20180727_2-aba7175b-856e-4b03-9201-e9ce551c0f9f",
 
                    "cmis:allowedChildObjectTypeIds": null
 
                }
 
            },
 
            "pathSegment": "Test_dubbellebestanden2_20180727_2-aba7175b-856e-4b03-9201-e9ce551c0f9f"
 
        }
 
    ]
 
}
</source>
Response will contain a list of Ingested AIPs in format Name + UUID.
 
The full list of fields is described in [http://docs.oasis-open.org/cmis/CMIS/v1.1/errata01/os/CMIS-v1.1-errata01-os-complete.html#x1-220002 CMIS Object]
 
Let’s focus on major parts that will be used in following sections.
 
* <code>object.id</code> – contains AIP UUID.
* <code>object.succinctProperties.cmis:name</code> – contains AIP Name + UUID. That name will be displayed in CMIS Workbench.
* <code>object.succinctProperties.cmis:path</code> – contains Path via what this object (AIP) can be accessed.
 
So now we can browse AIP’s file structure.
 
==== Browse File and Folder Structure of AIP ====
 
From previous step we can obtain AIP Object ID (UUID) or AIP Access Path.
 
And we can browse its internal structure. Request:
 
<source lang="http">
GET {rootFolderUrl}/{AIP_Path}?cmisselector=children&succinct=true
</source>
Or:
 
<source lang="http">
GET {repositoryUrl}?objectId={AIP UUID}&cmisselector=children&succinct=true
</source>
According to CMIS Specification object can be accessed through Path URL or by ObjectID including to Repository URL. Read more about it in
 
[http://docs.oasis-open.org/cmis/CMIS/v1.1/errata01/os/CMIS-v1.1-errata01-os-complete.html#x1-5580004 CMIS Specification]
 
Response:
 
<source lang="json">
{
 
    "numItems": 5,
 
    "moreItems": false,
 
    "objects": [
 
        {
 
            "object": {
 
                "id": "/Test_grootbestand_20180725_1-5def6da9-9c70-4800-84e9-5e501bc6687e/objects/GDBA-7774-01.pdf",
 
                "relationship": [],
 
                "changeEventInfo": null,
 
                "acl": null,
 
                "exactACL": null,
 
                "policyIds": null,
 
                "renditions": [],
 
                "succinctProperties": {
 
                    "cmis:name": "GDBA-7774-01.pdf",
 
                    "cmis:description": "GDBA-7774-01.pdf",
 
                    "cmis:objectId": "/Test_grootbestand_20180725_1-5def6da9-9c70-4800-84e9-5e501bc6687e/objects/GDBA-7774-01.pdf",
 
                    "cmis:baseTypeId": "cmis:document",
 
                    "cmis:objectTypeId": "cmis:document",
 
                    "cmis:secondaryObjectTypeIds": null,
 
                    "cmis:createdBy": "Admin",
 
                    "cmis:creationDate": 946681200,
 
                    "cmis:lastModifiedBy": "Admin",
 
                    "cmis:lastModificationDate": 946681200,
 
                    "cmis:changeToken": "946681200",
 
                    "cmis:isImmutable": true,
 
                    "cmis:isLatestVersion": null,
 
                    "cmis:isMajorVersion": null,
 
                    "cmis:isLatestMajorVersion": null,
 
                    "cmis:isPrivateWorkingCopy": null,
 
                    "cmis:versionLabel": null,
 
                    "cmis:versionSeriesId": null,
 
                    "cmis:isVersionSeriesCheckedOut": null,
 
                    "cmis:versionSeriesCheckedOutBy": null,
 
                    "cmis:versionSeriesCheckedOutId": null,
 
                    "cmis:checkinComment": null,
 
                    "cmis:contentStreamLength": 0,
 
                    "cmis:contentStreamMimeType": "text/plain",
 
                    "cmis:contentStreamFileName": "GDBA-7774-01.pdf",
 
                    "cmis:contentStreamId": "/Test_grootbestand_20180725_1-5def6da9-9c70-4800-84e9-5e501bc6687e/objects/GDBA-7774-01.pdf"
 
                }
 
            },
 
            "pathSegment": "GDBA-7774-01.pdf"
 
        },
 
        ...
 
    ]
 
}
</source>
The result is presented in the same format as for requesting List of AIPS.
 
Because in terms of CMIS Protocol it is same actions – Get Children of an Object.
 
In that particular example we can see ingested file from AIP Files.
 
All files has <code>cmis:objectTypeId</code> property set to <code>cmis:document</code>.
 
For folders it is <code>cmis:folder</code>.
 
In current implementation of CMIS Server Object IDs are equals to theirs Paths.
 
This is useful for accessing object either via ObjectID or via Path.
 
Difference between files and folders is that File can have Content Stream to download.
 
Response contains following properties that can be used to download particular file:
 
<ul>
<li><p><code>object.succinctProperties.cmis:contentStreamId</code> –</p>
<p>Contains an Content Stream ID that should be used to download File Content.</p>
<p>In current Implementation Content Stream ID is equal to Object ID and thus its path.</p></li>
<li><p><code>object.succinctProperties.cmis:contentStreamFileName</code> –</p>
<p>Contains File Name that can be used as name of downloaded file.</p></li></ul>
 
Following Content Stream related properties needs to be Implemented in the Future:
 
<ul>
<li><p><code>cmis:contentStreamLength</code> – should be used to provide File Size information.</p>
<p>Right now it’s always <code>0</code>.</p></li>
<li><p><code>cmis:contentStreamMimeType</code> – should be used to provide File Content MIME type. To discover file type.</p>
<p>Right now it is always <code>test/plain</code></p></li></ul>
 
==== Downloading File from AIP ====
 
As described above to Download AIP File you have to use its Stream ID which is the same
 
as Object ID or Object Path. So request to download a file is following:
 
<source lang="http">
GET {rootFolderUrl}/{File Path}?cmisselector=content
</source>
Response will Redirect with Http status <code>302 Found</code> to File Location.
 
<source lang="http">
HTTP/1.1 302 Found
 
...
 
Location: /ss-content-proxy/5def6da9-9c70-4800-84e9-5e501bc6687e/Test_grootbestand_20180725_1-5def6da9-9c70-4800-84e9-5e501bc6687e/data/objects/GDBA-7774-02.pdf
</source>
So your CMIS Client has to follow HTTP Redirect in order to Download a file.
 
== Accessing files without CMIS ==
 
As presented in section above CMIS will redirect a HTTP Client to specific File location to
 
download file. It is possible to combine the URL request in order to download needed file without
 
using CMIS even.
 
However there are few requirements:
 
* You have to know exact Repository ID. Which is an Archivematica Location UUID assigned to your user.
* You have to know exact AIP Name (including name and UUID).
* You have to know exact path of needed file inside of AIP Package.
 
If requirements above are met you are able to build an URL to download needed file.
 
The rules are following:
 
<code>{CMIS Endpoint}</code> + <code>/ss-content-proxy/</code> + <code>{Repository ID}</code> + <code>/{AIP Name}</code> + <code>/{File Path inside AIP}</code>
 
For example this url:
 
<code>https://pic-devel-cmis.edepot.picturae.com/ss-content-proxy/5def6da9-9c70-4800-84e9-5e501bc6687e/Test_grootbestand_20180725_1-5def6da9-9c70-4800-84e9-5e501bc6687e/data/objects/GDBA-7774-02.pdf</code>
 
It contains following parts:
 
<ul>
<li><p>CMIS Endpoint – <code>https://pic-devel-cmis.edepot.picturae.com</code></p></li>
<li><p>Repository ID – <code>5def6da9-9c70-4800-84e9-5e501bc6687e</code></p></li>
<li><p>AIP Name – <code>Test_grootbestand_20180725_1-5def6da9-9c70-4800-84e9-5e501bc6687e</code></p></li>
<li><p>File Path – <code>data/objects/GDBA-7774-02.pdf</code></p>
<p>Please notice that file location contains root folder <code>data</code> which is not presented in CMIS AIP Structure. So you have to include it explicitly.</p></li></ul>
 
So now you can download needed file without using CMIS.
 
'''Note''' Downloading big files may be slow. Because it requires some time to Extract file from an AIP Archive.
 
== CMIS Workbench ==
 
=== Installation ===
 
In order to connect via CMIS Workbench you need to install [https://java.com/en/download/ Java].
 
Follow instruction from official Java Web site to download and install it on your Machine (Windows, MacOS, Linux, etc… ).
 
Once you have Java installed, check that it is accessible from your terminal. type:
 
<code>java --version</code> to see that it is working.
 
Example:
 
<source lang="bash">
$ java --version
 
java 10.0.1 2018-04-17
 
Java(TM) SE Runtime Environment 18.3 (build 10.0.1+10)
 
Java HotSpot(TM) 64-Bit Server VM 18.3 (build 10.0.1+10, mixed mode)
</source>
Now you can download CMIS Workbench from [http://www-eu.apache.org/dist/chemistry/opencmis/1.1.0/chemistry-opencmis-workbench-1.1.0-full.zip official mirror]
 
Unpack it to your favorite location. Example (MacOS, Linux):
 
<source lang="bash">
curl -o cmis-workbench.zip http://www-eu.apache.org/dist/chemistry/opencmis/1.1.0/chemistry-opencmis-workbench-1.1.0-full.zip
 
mkdir  cmis-workbench
 
unzip -d cmis-workbench/
 
cd cmis-workbench/
</source>
After you unzipped the package you can run it <code>./workbench.command</code>
 
=== Usage ===
 
After starting CMIS workbench you should see following window:
 
[[File:assets/cmis-open.png|thumb|none|alt=CMIS|CMIS]]
 
Now you need to login.
 
* URL – this is your CMIS Server endpoint. (Example: <code>https://pic-devel-cmis.edepot.picturae.com</code>)
* Binding – Browser
* Username – Your username (Example: <code>demo</code>)
* Password – Your password (Example: <code>demo</code>)
* Authentication – Standard
* Rest parameters leave As Is.
 
Then click on <code>Load Repositories</code> button and after it loads Repositories List click on Login.
 
Now you should see following window:
 
[[File:assets/cmis-browse.png|thumb|none|alt=CMIS Browse|CMIS Browse]]
 
On the left side you can see list of ingested AIPs and on the right side CMIS Object Details.
 
You can double-click on Folders (AIP Packages) in order to browse its file &amp; folder structure.
 
Once you reached needed file Right Click on it and select Download.
 
[[File:assets/cmis-download.png|thumb|none|alt=CMIS File Download|CMIS File Download]]
 
Ignore MIME Error message. This is an issue with CMIS Workbench.
 
After you clicked on the Download Button it may take some time to extract the file from AIP and start downloading it.

Versie van 13 mrt 2019 09:56

Engelstalige handleiding van de CMIS server

Overgenomen van "https://wiki-archives.memorix.nl/index.php?title=CMIS_Server&oldid=506"