Example Scenario

Assume institution Org1 is developing a content management system (CMS) and wants to integrate the ARDC Handle Service to obtain handles for identifying objects. Org1 would typically undertake the following process:

• Request registration with the service
• Obtain the appId to use in all administrative requests as described earlier
• Develop service integration code and test the application against the test service
• Request registration with the production service

The integration development required by the CMS developer for the above scenario may be as simple as minting a handle on deposit of content to the CMS and maintaining a single URL associated with that content over time. This requires use of the mint and modifyValueByIndex services. When content is ingested, the CMS using the service mints a handle for the URL of the content. At a technical level this would involve an HTTP POST request to the mint service, for example:

https://identifiers.ardc.edu.au/pids/mint?type=URL&value=http://cms.Org1.au/contentlocation

Since mint is an administrative service, the XML fragment containing client-specific metadata must also be included in the request body:

<request name="mint">
    <properties>
        <property name="appId" value="
            <ARDC-issued identifier>"/>
            <property name="identifier" value="MyCMS"/>
            <property name="authDomain" value="ldap.mycms.org.au"/>
    </properties>
</request>

The mint response would contain the following fragment in the response body, any or all of which may be used by the CMS for auditing or metadata.
 

<response type="success">
    <identifier handle="10378.2/99">
        <property index="1" type="URL" value="http://cms.Org1.au/content1location"/>
    </identifier>
    <timestamp>2009-05-15T01:41:11Z</timestamp>
    <message type="user">Successfully authenticated and created handle</message>
</response>

In this scenario it would be expected the CMS would store the handle to ensure it can manage the URL associated with it into the future.
When content location changes within the CMS domain either by a user re-organising their content or through CMS maintenance the CMS would issue a modifyValueByIndex request using index value 1 (indexes are currently sequential starting at 1 and in this scenario we have only one value associated with a handle).

Again an HTTP POST is sent to the following URL:

https://identifiers.ardc.edu.au/pids/modifyValueByIndex?handle=10378.2/99&value=http://cms.Org1.au/newcontent1location&index=1

Since modifyValueByIndex is an administrative service, the XML fragment containing client-specific metadata must also be included in the request body:

 <request name="mint">
    <properties>
        <property name="appId" value="
            <ARDC-issued identifier>"/>
            <property name="identifier" value="MyCMS"/>
            <property name="authDomain" value="ldap.mycms.org.au"/>
        </properties>
 </request>

The modifyValueByIndex response would contain the following fragment in the response body, any or all of which may be used by the CMS for auditing or metadata.

<response type="success">
    <identifier handle="10378.2/99">
        <property index="1" type="URL" value="http://cms.Org1.au/newcontent1location" />
    </identifier>
    <timestamp>2009-05-15T02:41:11Z</timestamp>
    <message type="user">Successfully modified handle value</message>
</response>

It is the responsibility of the CMS to ensure all URLs associated with the content's handles are kept up to date in the Persistent Identifier service.