ISAN API 3.0 - new ISAN applications

/records service enables to register an ISAN record, i.e. a series, a group, an episode, a single work,  or a version: variant, manifestation,  related content, related item. 

The following topics are covered in this article:

• Single work applications: single record
• Episodic work applications: series, group, episode records
• Version applications: variant, manifestation, related content, related item records
• Get the status of the ISAN application
• Manage pending applications: deduplication process 
• Get the new ISAN

 

Single work applications: single record

The ISAN registration process involves several operations

Step 1: submit the single work data

POST /records Register or validate a record before registration

Refer to ISAN swagger interface for details and examples in json and xml

❗️The API user shall have a registrant role (X-ISAN-Authorization)

⚠️ Considerations in case of errors when using the examples provided on the ISAN swagger site:

• The recordId must be unique for the user, values proposed in the swagger examples might need to be changed.

• linked ISAN proposed in swagger examples might need to be replaced with existing valid ISAN in the database (sandbox / production)

• It is likely that swagger examples will result in a pending application as other users might have already registered these examples.

Step 2: Get the status of the application

After the application submission, you will check its status: Get the status of the ISAN application

Step 3: Deduplication

If the status is "pending", Manage pending applications: deduplication process 

Step 4 : Get the new ISAN

Once the status is "active", you can Get the new ISAN

Episodic work applications: series, group, episode records

The episodic ISAN registration process involves several steps and operations

1. First the Series record shall be registered (the series ISAN is not delivered at this stage)
2. Then, a child record of the Series, e.g. a Group or an Episode shall be registered. It's only once the first child record is registered that the Series ISAN is delivered.

 

Step 1: submit the series work data

POST /records Register or validate a record before registration

Refer to ISAN swagger interface for details and examples in json and xml

❗️The API user shall have a registrant role (X-ISAN-Authorization)

⚠️ Considerations in case of errors when using the examples provided on the ISAN swagger site:

• The recordId must be unique for the user, values proposed in the swagger examples might need to be changed.

• linked ISAN proposed in swagger examples might need to be replaced with existing valid ISAN in the database (sandbox / production)

• It is likely that swagger examples will result in a pending application as other users might have already registered these examples.

Step 2: Get the status of the application

After the application submission, you will check its status: Get the status of the ISAN application

Step 3: Deduplication

If the status is "pending", Manage pending applications: deduplication process 

Step 4: submit the series first child data (e.g. group or episode)

POST /records Register or validate a record before registration

Refer to ISAN swagger interface for details and examples in json and xml

❗️The API user shall have a registrant role (X-ISAN-Authorization)

⚠️ Considerations in case of errors when using the examples provided on the ISAN swagger site:

• The recordId and parenRecordId must be unique for the user, values proposed in the swagger examples might need to be changed.

• linked ISAN proposed in swagger examples might need to be replaced with existing valid ISAN in the database (sandbox / production)

• It is likely that swagger examples will result in a pending application as other users might have already registered these examples.

Step 5: Get the status of the child application

After the application submission, you will check its status: Get the status of the ISAN application

Step 6: Chid deduplication

If the status is "pending", Manage pending applications: deduplication process 

Step 7 : Get the new ISAN for the Series and for the first child

Once the status is "active", you can Get the new ISAN

Important considerations:

• For a successful validation of a child application, the parent record mut have been submitted first for registration, otherwise the parentRecordId will not be recognized. 
• parents shall be registered before children:
  • A group can be registered only if the series has been registered first.
  • An episode can be registered only if the Series and/or the Group (it is attached to) is/are registered first
• ⚠️ Warning: The ISAN of a series is delivered only after the first group or first episode is registered.

Version applications: variant, manifestation, related content, related item records

(parents need to be registered first)

[TBD]

 

Get the status of the ISAN application

After submitting you application, you will check its status by invoking /myisan on the recordId. 

/myisan service enables to query the client catalogue in the ISAN Registry for retrieving registered ISAN and ISAN applications made by the client. The scope of the search is restricted to the client catalogue.

possible statuses are: 

Status	Description
submitted	the ISAN application has been submitted and is waiting for being processed
in_progress	the ISAN application is currently been processed
pending	the ISAN application is pending to a manual deduplication
waiting_for_child	the ISAN application is on hold until a child record is provided (e.g. a series ISAN can be allocated only once the first group or episode is provided)
waiting_for_parent	the ISAN application is on hold until a parent record is provided (e.g. an episode can be registered only if its parent series or group has ben registered first)
active	the ISAN is allocated as an active ISAN
duplicate	the ISAN application has been resolved as a duplicate

Use the myisan service to check the status of a registration application after using the /record service for registering an ISAN

 

Record based search

POST /myisan Query the the client catalogue using the record data that is provided

Refer to ISAN swagger site for details and examples in json and xml

Set the field value to status when checking the status of a registration application

Some arguments can be repeated (i.e. for repeatable fields such as countries, languages, participants), forming a OR condition between the repeated arguments.

 

Query based search

GET /myisan Build the search and query the client catalogue

Refer to ISAN swagger site for details and examples in json and xml

Set the field value to status when checking the status of a registration application

Some arguments can be repeated (i.e. for repeatable fields such as countries, languages, participants), forming a OR condition between the repeated arguments.

Manage pending applications: deduplication process 

The status of the ISAN application is status = pending, this means that the application is matching with one or more active ISAN, and a manual deduplication is required to check wether the ISAN is already registered. In case of a real duplicate, the existing ISAN shall be used and the application will be associated to that ISAN. If none of the matching candidates are real duplicates, a new ISAN is issued.

Pending are resolved  either on the ISAN web interface (ISAN application Deduplication) or with the help of the /deduplication service.

Once the pending is resolved, either a new ISAN is allocated (status = active) or an existing ISAN (status = duplicate) is associated to the application. Thereafter see Get the new (or existing) ISAN

Step 1: list all pending works

To list all pending works of the application, use the /deduplication service

POST /deduplication/queries List all matching candidates

Refer to ISAN swagger site for details and examples in json and xml

• The service is invoked with the recordId of the application
• Specify in fields the data that is to be returned by the service, e.g. titles, status, participants

Exemple (XML encoding, similar for JSON)

<matchCandidateSearchQuery>
    <sortBy>relevance</sortBy>
    <page>0</page>
    <size>10</size>
    <ISAN></ISAN>
    <recordId>test-0001</recordId>
    <fields>
        <field>titles</field>
        <field>status</field>
        <field>participants</field>
    </fields>
</matchCandidateSearchQuery>

The list of results is similar as the results with the /query service

The deduplication review consist to assess if  one of the matching candidate corresponds to the application candidate. The result of the assessment leads to the deduplication action in the next step.

Step 2: deduplication action

• The service is invoked with the recordId of the application
• The deduplication action is specified in the action field:
  • is_new : none of the matching candidates corresponds to the application. A new ISAN will be delivered. Exemple (XML encoding, similar for JSON)

    • <matchResolveQuery>
       <recordId>test-0001</recordId>
       <action>is_new</action>
      </matchResolveQuery>

       
  • is_duplicate: the ISAN is already allocated and will be associated to the application. Exemple (XML encoding, similar for JSON)

    • <matchResolveQuery>
        <recordId>test-0001</recordId>
        <action>is_duplicate</action>
        <candidates>
          <candidate>
              <comment></comment>
              <ISAN>0000-0006-2061-0000-F-0000-0000-T</ISAN>
              <type/>
          </candidate>
        </candidates>
      </matchResolveQuery>

       
  • is_new_and_link_isan: the ISAN does not exist, but one of the candidate is linked to the application (e.g. part of a sequel). Refer to all supported Linked ISAN types. A new ISAN will be delivered and a link with the other ISAN will be created.  Exemple (XML encoding, similar for JSON)

    • <matchResolveQuery>
      <recordId>test-0001</recordId>
      <action>is_new_and_link_isan</action>
      <candidates>
      <candidate>
      <comment></comment>
      <ISAN>0000-0006-2061-0000-F-0000-0000-T</ISAN>
      <type>sequel</type>
      </candidate>
      </candidates>
      </matchResolveQuery>

Get the new (or existing) ISAN

The status of the ISAN application is status = active (new ISAN) or  status = duplicate (existing ISAN). This indicates that the ISAN has been associated to the application and that it can be retrieved in the status information (see Get the status of the ISAN application).

If you wish to retrieve all information associated with that ISAN, renew the query for obtaining the status of the application but make sure you set  all the field value to allRecordData.