functional specification web services

of 39

Functional Specification

Web Services

Permission Lookup

Version v2.1

of 39

Document control

Change control

Version Date Description of Change Author

1.0 26/04/2012 First issued version A Cole, N Gomes, Entity

1.1 14/05/2012 Updates A Cole

1.2 05/06/2012 Permission Message Additions Entity

1.3 29/06/2012 Permission Message Additions and Parameter Redefinition

Entity

1.4 03/07/2012 Sample update and corrections Entity

1.5 03/07/2012 Proof A Cole

2.1 15/12/2014 Added extended methods A Cole

of 39

Table of Contents

Contents

1. Introduction .......................................................................................................... 5

1.1 Purpose ..................................................................................................................................... 5

1.2 Glossary .................................................................................................................................... 5

1.3 Architecture .............................................................................................................................. 6

2. Service Description .............................................................................................. 7

2.1 Overview ................................................................................................................................... 7

2.2 User Information....................................................................................................................... 7

2.3 Manifestation Information ....................................................................................................... 7

2.4 Permission Messages .............................................................................................................. 8

2.4.1 Title Permission Message .................................................................................................. 8

2.4.2 Header ................................................................................................................................ 8

2.4.3 PermissionDefinitions ......................................................................................................... 9

2.4.4 Footer ................................................................................................................................. 9

2.4.5 Restrictions ......................................................................................................................... 9

2.4.6 Additional Permissions ....................................................................................................... 9

2.5 Services ..................................................................................................................................... 9

2.5.1 Retrieve Reference Data .................................................................................................. 10

2.5.2 ISN Search ....................................................................................................................... 10

2.5.3 Title Search ...................................................................................................................... 11

2.5.4 Manifestation Id Search ................................................................................................... 12

3. Technical Specification ...................................................................................... 14

3.1 Introduction ............................................................................................................................ 14

3.1.1 Data Type Definitions ....................................................................................................... 14

3.1.2 Mandatory and Optional Elements ................................................................................... 14

3.1.3 Retrieval maximum ........................................................................................................... 14

3.1.4 Generic elements ............................................................................................................. 14

3.2 Retrieve Reference Data ........................................................................................................ 15

3.2.1 Sequence Diagram ........................................................................................................... 15

3.2.2 Request Message ............................................................................................................ 15

3.2.3 Response Message.......................................................................................................... 16

3.3 ISN Search .............................................................................................................................. 19


3.3.2 Request Message ............................................................................................................ 19


3.4 Title Search ............................................................................................................................. 24


3.4.2 Request Message ............................................................................................................ 24


3.5 Manifestation Id Search ......................................................................................................... 29

of 39


3.5.2 Request Message ............................................................................................................ 29


3.6 Get Permission By Identifier Ext .......................................................................................... 33


3.6.2 Request Message ............................................................................................................ 33


3.7 Get Permission By Manifestation Id Ext .............................................................................. 35


3.7.2 Request Message ............................................................................................................ 35


4. Request Status ................................................................................................... 36

Appendix A – Examples from CLA Website Lookup

of 39

1. Introduction

1.1 Purpose This document describes the Permission Lookup web service which allows a client to ascertain the permissions for reuse of UK and foreign repertoire under the terms of a CLA licence and usage. This is achieved by the use of exchanging XML Messages; each Request message by the client is answered by a Response message by the CLA OPS system.

1.2 Glossary The following acronyms and terms are used in this document.

Term Meaning

API Application Programming Interfaces is a source code based specification

intended to be used as an interface by software components to

communicate with each other.

HTTP Hypertext Transfer Protocol. An application protocol for exchanging files

(text, graphic images, sound, video, and other multimedia files) on the

Web.

SOAP Simple Object Access Protocol, It is a protocol specification for exchanging

structured information in the implementation of Web Services. It relies on

XML for its message format.

URL Uniform Resource Locator. The address of a resource accessible on the

Web. The URL includes the name of the protocol required to access the

resource, identifies the address of a specific server on the Web, and

contains a hierarchical description of a file location on the server.

XML Extensible Markup Language. A flexible way to create data formats and

share both the format and the content on the Web, intranets, and

elsewhere.

XSD Extensible Markup Language XML Schema Definition. A file written in

XML that defines the permitted range and data types of attributes and

elements within an application.

WSDL Web Service Description Language an XML document that describes the

methods of the web service

Contributor A person contributing to the creation of a manifestation (e.g. author, editor,

illustrator etc).

ISBN International Standard Book Number. Uniquely identifies a single

manifestation of a work. ISBNs are used for monographic publications.

ISN International Standard Number. A generic term referring to both ISSN and

ISBN identifiers

ISSN International Standard Serial Number. Uniquely identifies a single

manifestation of a work. ISSNs are used for periodical publications.

Licence Types Generic term given to describe the various licences in place between CLA

and its customers.

Manifestation An individual book or serial. Different published editions of the same

textual work are different manifestations. (For example, the Penguin

Popular Classic edition of Pride and Prejudice is a separate manifestation

to the Oxford World Classics edition).

of 39

Term Meaning

NLA Newspaper Licensing Agency – CLA act as an agent for NLA licensing

within the educational sector

OPS The Operations System – CLA’s application which contains a database of

published works (or Manifestations) and Customer licenses.

TitlePermissionMessage An XML message containing bibliographic information about a title and the

associated permissions that users may or may not have to copy this title.

Usage Types Defines the type of usage under a given licence, e.g. photocopying,

scanning etc.

1.3 Architecture

The API uses SOAP to receive requests and send responses. As SOAP is not tied to any particular transport protocol, operating system, or programming language, clients and servers in these dialogues can run on any platform and use any language as long as they can formulate and understand SOAP messages. Sessions are not used in the API.

of 39

2. Service Description

This section gives an overview of the Permission Lookup API, describes the high level functionality of the available services and lists the request and response elements within each (from the business perspective).

2.1 Overview

Institutions and businesses that hold CLA licences may wish to check specific titles that they intend to copy in order to ensure that the license they hold covers the usage that they hope to carry out. Licensees hold licences that are tailored to their sector or industry and consequently the publishers can set usage permissions by these sectors. The varying needs of the sectors mean that there is no general rule of thumb available for permissions. Licensees therefore needed a mechanism to ascertain whether they can legally copy particular books or journals.

The Permission Lookup API is intended to provide external parties with a way in which to fulfil queries on copyright permissions. The form of this could include, but is not restricted to, a final dedicated resource such as a mobile app or incorporation into an existing service hosted on a company or institution’s intranet. Formerly, the only method for searching for permission was restricted to look ups conducted on the CLA website (http://permissions.cla.co.uk/titlesearch.html). The mechanics that provide the business logic of the API is inherited from the CLA website lookup, so both the website look up and API request / response messages, function in the same way. The CLA website look up can therefore be used to demonstrate examples of how the data might be displayed. See Appendix A for examples of the CLA website look up results. Note that the API only carries the bibliographic and permission data and does not include formatting data.

Using the external client and API, a user (licensee) will select their licence and the usage that they intend to carry out and then search for a manifestation. They may search by either ISN using the ‘ISN Search’ service or by title using the ‘Title Search’ service.

Following the completion of a successful search the user will be provided with the relevant permission information regarding the manifestation relative to their licence and the proposed copying usage. The three possible permission results are:

Positive – the licensee is covered to copy the work

Negative – the title is excluded from their licence

Warning – the title does not have a record at the CLA, but permission is outlined dependent on certain conditions

Each of these messages contain further information that details the types of copying allowed and any terms and exceptions that apply to either the license held or the title that is being queried. These are outlined further in the section 2.4.

2.2 User Information

As stated above, in order to conduct a search the user is required to select the licence (i.e. Licence Type) that they hold and the type of copying that they intend to do (i.e. Usage Type). The available Licence Types, e.g. ‘Business’, ‘Law’ etc., and the available Usage Types, e.g. ‘photocopying’, ‘scanning’ etc., are provided by the ‘Retrieve Reference Data’ service. The Licence Type and Usage Type are required parameters in the permission request messages (i.e. ‘ISN Search’, ‘Title Search’ and ‘Manifestation Id Search’ services) and are subsequently used by the CLA OPS system to retrieve the appropriate permissions. Note that the Usage Types available may vary for each Licence Type.

2.3 Manifestation Information

Along with the licence and usage information, manifestation information must also be provided as a parameter in the permission request message.

http://permissions.cla.co.uk/titlesearch.html

of 39

The manifestation may be searched by its title, using the ‘Title Search’ service or by ISBN/ISSN, using the ‘ISN Search’ service.

A Title Search will potentially return a list of many titles that have been found to match the request. The user must then select the result that matches the manifestation that they intend to copy. The title search may return different manifestations of similar name or different editions of the same title. Depending on the number of titles returned, more than one page of information may be available. The request message for a Title Search must therefore also specify the page number that it requires returned. On selection of the correct manifestation, a search using the CLA OPS system manifestation identifier, through the ‘Manifestation Id Search’ service, is conducted for the available permissions. This search is similar to the ISN Search as it will retrieve permissions for a single manifestation.

The user has the option to provide the country of publication for both the ISN Search and the Title Search although this is not required and will filter out titles where there is a title or identifier match and the country does not match.

2.4 Permission Messages

2.4.1 Title Permission Message

The content of the permission part of the message is set by the CLA. The content description given here is intended to show examples of messages in order to provide an understanding of the structure that messages can take and does not represent actual responses. On the successful completion of an ISN Search or Title Search (and subsequent Manifestation Id Search) the permission message is returned. The permission part of the message takes one of three possible types of result – positive, negative or warning. The structure of each message has four main areas, two of which are mandatory to every message. Each message section may also take some optional parts.

The two mandatory parts of the title permission message:

Header

Permission definitions

The optional parts are referred to as the Footer and the Restriction.

2.4.2 Header

The header contains the type of response to the query as well as the associated text. Some examples that are currently in use are

Positive

o Text – “Subject to defined extent limits, this title is covered by your CLA licence for the following uses”

Warning

o Text – “Not Found” or

o Text – “US Publisher not found”

Negative

o Text - “Excluded”

This may be followed by non-mandatory information text detailing the information that the recipient may need before they see the actual permissions.

of 39

2.4.3 PermissionDefinitions

This part outlines the permissions applicable to the search. There will be at least one permission definition here, and some searches return many permission definitions.

An example of a Negative Reusage message is

This title has been excluded from the CLA Licence by the rightsholder and cannot be copied.

Examples of Positive Reusage include

Photocopy extracts from paper originals and share with colleagues

Fax to colleagues

Supply copies for regulatory and technical submissions in the UK

Outsource photocopying

The results are dependent on the type of usage and licence that the user selected.

2.4.4 Footer

The footer part of the message can contain legal information and links to licence terms.

2.4.5 Restrictions

This optional part describes any restriction specific to the manifestation (also referred to as ‘terms apply’). Publishers may have set additional terms that apply to the title and these will be contained here.

2.4.6 Additional Permissions

The ‘additional permissions’ extension allows CLA to show permission results for reusage that falls outside of the CLA licence. For example, for organizations where CLA acts as an agent. Using the extended methods all applicable usage types that contain positive permissions will be returned for a covered title.

The first use of the additional permissions is for the education NLA licence, where CLA act as an agent for the NLA. Using the extended methods with the CLA education licences will return additional permissions when the requested title is covered by an NLA licence.

The UsageTypeDescriptions relating to the NLA and are the only items used at this time are:

NLA Print Hardcopy

NLA Print Electronic

NLA Web Hardcopy

NLA Web Electronic

2.5 Services

of 39

2.5.1 Retrieve Reference Data

This service returns the reference data that is required to be used in future search requests and permitted values which can be searched on. The reference data returned includes:

a list of the CLA licences and the usages associated with each licence

a list of countries and country code

permitted values for the number of titles that can be returned in a search

permitted values for the sort order the titles are returned in Usually the reference data is requested before any search is made.

The optional elements in the request messages will not be included in the response if omitted from the request. The optional elements of the response depend upon the information that it is trying to relate.

Request elements

RequestSystem

SenderName (Optional)

MessageId (Optional)

Response elements

RequestParameters o RequestSystem o SenderName o MessageId

Status o StatusCode o FieldName o FieldValue o StatusMessage

LicenceTypeGroup (list of Licence types and their usage) o LicenceType

UsageTypeGroup

UsageType o UsageDescription o UsageCode

LicenceDescription LicenceCode

CountryGroup (list of countries) o Country

CountryDescription CountryCode

ResultsPerPageGroup (list of values detailing how many results per page are allowed) o ResultsPerPage

MaxResults

ResultsSortByGroup (list of values indicating how results may be sorted) o ResultsSortBy

SortDescription SortCode

2.5.2 ISN Search

This service returns the permissions for reuse for the ISBN / ISSN, licence and usage from the request. The response will include the metadata for the title of the ISBN / ISSN and permission details. The permission details can include an assertion of coverage, a number of permission types and a disclaimer which may also include a link to the CLA website and additional text to be displayed.

Request elements

RequestSystem


of 39


LicenceType

UsageType

Identifier

CountryCode (Optional)

Response elements

RequestParameters o RequestSystem o SenderName o MessageId o Identifier o LicenceType o UsageType o CountryCode


Permission o ManifestationId o Title o Identifier o Contributor (Optional) o PublicationType o PublicationForm o PublicationCountry o Publisher o TitlePermissionMessage

2.5.2.1 ISN Search – Extended

As section 2.5.2 with additional permissions included where applicable in the permission part of the response

Permission o ManifestationId o Title o Identifier o Contributor (Optional) o PublicationType o PublicationForm o PublicationCountry o Publisher o TitlePermissionMessage o AdditionalPermissionMessage (Optional)

TitlePermissionMessage UsageTypeDescription

2.5.3 Title Search

This service returns a list of titles which meets the search criteria in the request message (title, licence and usage). The maximum number of titles which will be returned in the response will depend on the value specified in MaxResults in the request. The list of titles will be sorted in the order specified in SortBy in the request.

For each title, the title’s metadata and the internal id (Manifestation Id) from the CLA database will be

of 39

returned.

Request elements

RequestSystem


MessageId

Title

LicenceType

UsageType


SortBy (Optional)

PageIndex (Optional)

MaxResults (Optional)

Response elements

RequestParameters o RequestSystem o SenderName o MessageId o Title o LicenceType o UsageType o CountryCode o SortBy o PageIndex o MaxResults


Manifestations o Manifestation

ManifestationId Title Identifier IdentifierType Contributor (Optional) PublicationType PublicationForm PublicationCountry Publisher

2.5.4 Manifestation Id Search

This service is used when the Manifestation id (CLA unique indexed key for a manifestation) is known for a manifestation i.e. when a title has been selected from the list of titles returned by the Title Search response message. The response will include the metadata for the manifestation and permission details. The permission details can include an assertion of coverage, a number of permission types and a disclaimer which may also include a link to the CLA website and additional text to be displayed.

Request elements

of 39

RequestSystem



ManifestationId

LicenceType

UsageType


Title (Optional)

Identifier (Optional)

Response elements

RequestParameters o RequestSystem o SenderName o MessageId o ManifestationId o LicenceType o UsageType o CountryCode o Identifier


Permission o ManifestationId o Title o Identifier o IdentifierType o Contributor (Optional) o PublicationType o PublicationForm o PublicationCountry o Publisher o TitlePermissionMessage

2.5.4.1 Manifestation Id Search – Extended

As section 2.5.4 with additional permissions included where applicable in the permission part of the response

Permission o ManifestationId o Title o Identifier o Contributor (Optional) o PublicationType o PublicationForm o PublicationCountry o Publisher o TitlePermissionMessage o AdditionalPermissionMessage (Optional)

TitlePermissionMessage UsageTypeDescription

of 39

3. Technical Specification

3.1 Introduction

This section specifies the format of specific request response pairs.

3.1.1 Data Type Definitions

The following definitions will be used to define the type of data used in request message elements.

n decimal digits 0 through 9

a text – data of this type may contain any XML safe character

These definitions can be followed by a number indicating the length, or one or two numbers separated by two dots indicating variable length with min and max length.

e.g.

n..15 no more than fifteen decimal digits

n6 exactly six decimal digits.

a..250 no more than 250 characters

3.1.2 Mandatory and Optional Elements

Requests may contain any combination of mandatory and optional elements. The mandatory column in the Elements tables for each request and response message will show if an element is mandatory or optional. Some optional elements may be required in some circumstances, dependent upon other optional elements. If the optional elements are supplied then they must contain a valid value.

The addition of new optional elements or response values may be introduced and will update the latest version of the messages. These changes will not introduce a new version and will be backward compatible. It is assumed that clients will parse XML responses correctly, ignoring any unrecognised elements or attributes (i.e. elements or attributes added to the responses since the client was written), and including unrecognised error response status keys.

New versions will be created when the request / response pairs cannot be made backward-compatible. In order to make use of these new features, clients must be updated to use the latest message versions.

3.1.3 Retrieval maximum

The current maximum number of overall results that will be returned is 250 (or lower depending on the number of results for the specific search).

3.1.4 Generic elements

The following describes generic elements that are relevant to all requests and responses.

(Generic) Request Elements

RequestSystem: This is mandatory. A string supplied by CLA which will be used to authenticate any request made to the API. If this is not matched to CLA’s database a message will be returned ‘invalid request system’.

SenderName: This is optional. The name of the end user / institutional body making the

of 39

request.

MessageId: This is optional. Used by the client application to identify requests and responses. If the message id is supplied in the request message, it will be included in the response message.

(Generic) Response Elements

RequestSystem: This is the value supplied in the RequestSystem parameter of the request.

SenderName: If supplied, this is the value from the request.

MessageId: If supplied, this is the value from the request.

Status (Complex Element): Elements describing the status of the request and any other valid information about the returned status (See Section 4 Request Status).

3.2 Retrieve Reference Data

3.2.1 Sequence Diagram

3.2.2 Request Message

Method: GetReferenceData

URL: http://<HOST>/Public/lookupapi/v1/lookup.asmx?op=GetReferenceData

Format (SOAP 1.2):

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<GetReferenceData xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">

1.0 Retrieve Reference Data

Reference Data

Request

External

Application

Reference Data

API

Reference Data

Request

of 39

<RequestParameters>

<RequestParameters xmlns="">

<RequestSystem>string</RequestSystem>

<SenderName>string</SenderName>

<MessageId>int</MessageId>

</RequestParameters>


</GetReferenceData>

</soap12:Body>

</soap12:Envelope>

Elements:

Element Name Data Type

Mandatory Comments

RequestSystem a..50 Yes See Section 3.14

SenderName a..100 No See Section 3.14

MessageId n..9 No See Section 3.14

e.g.:




<soap12:Body>

<GetReferenceData xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">

<RequestParameters>


<RequestSystem>APITestApplication</RequestSystem>

<SenderName>Documentation</SenderName>

<MessageId>100</MessageId>



</GetReferenceData>

</soap12:Body>

</soap12:Envelope>

3.2.3 Response Message

Successful responses contain items of reference data to be used in subsequent search requests.

Elements:


Mandatory Comments

RequestParameters See Section 3.1.4

RequestSystem a..50 Yes

SenderName a..100 No

MessageId n..9 No

Status See Section 4

StatusCode a..50 Yes

FieldName a..50 No

FieldValue a..500 No

StatusMessage a..500 No

LicenceTypeGroup Yes LicenceTypes container. Can contain 1 or more valid licence types.

LicenceType Yes Repeating group containing CLA licences and associated usages.

UsageTypeGroup Yes UsageTypes container. Can contain 1 or more valid Usage types.

of 39


Mandatory Comments

UsageType Yes Repeating group of usages associated with the licence

UsageDescription a..100 Yes Text description of the usage type.

UsageCode n..9 Yes Numeric identifier of the usage type. To be supplied in subsequent searches.

LicenceDescription a..100 Yes Text description of the licence type.

LicenceCode n..9 Yes Numeric identifier of the licence type. To be supplied in subsequent searches.

CountryGroup Yes Country container. Can contain 1 or more valid countries

Country Yes Repeating group of countries

CountryDescription a.100 Yes Text description of the Country.

CountryCode n..9 Yes Numeric identifier of the country type. To be supplied in subsequent searches.

ResultsPerPageGroup Yes ResultsPerPage container. Can contain 1 or more valid Results per page

ResultsPerPage Yes Repeating group of maximum results per page returned.

MaxResults n..9 Yes Maximum number of titles that will be returned in the response. To be supplied in subsequent Title searches.

ResultsSortByGroup Yes ResultsSortBy container. Can contain 1 or more valid ResultsSortBy.

ResultsSortBy Yes Repeating group of sort options.

SortDescription a..100 Yes Text description of the sort option.

SortCode a..50 Yes Text identifier of the sort option. To be supplied in subsequent Title searches.

An example of the XML portion of a response is shown below (Note - some lines might be wrapped): <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<GetReferenceDataResponse

xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">

<GetReferenceDataResult>

<Response xmlns="">

<RequestParameters>





<Status>

<StatusCode>SUCCESS</StatusCode>

</Status>

<LicenceTypeGroup>

<LicenceType>

<UsageTypeGroup>

<UsageType>

<UsageDescription>Photocopying</UsageDescription>

<UsageCode>1</UsageCode>

</UsageType>

<UsageType>

<UsageDescription>Scanning</UsageDescription>


</UsageType>

<UsageType>

<UsageDescription>Digital</UsageDescription>


</UsageType>

</UsageTypeGroup>

<LicenceDescription>Business</LicenceDescription>

<LicenceCode>134</LicenceCode>

</LicenceType>

of 39

<LicenceType>

<UsageTypeGroup>

<UsageType>



</UsageType>

<UsageType>



</UsageType>

<UsageType>



</UsageType>

</UsageTypeGroup>

<LicenceDescription>Further Education</LicenceDescription>


</LicenceType>

<LicenceType>

<UsageTypeGroup>

<UsageType>



</UsageType>

<UsageType>



</UsageType>

<UsageType>



</UsageType>

</UsageTypeGroup>

<LicenceDescription>Higher Education</LicenceDescription>


</LicenceType>

</LicenceTypeGroup>

<CountryGroup>

<Country>

<CountryDescription>United Kingdom of Great Britain & N.

Ireland</CountryDescription>

<CountryCode>1</CountryCode>

</Country>

<Country>

<CountryDescription>Afghanistan</CountryDescription>


</Country>

<Country>

<CountryDescription>Albania, People's Socialist Republic

of</CountryDescription>


</Country>

</CountryGroup>

<ResultsPerPageGroup>

<ResultsPerPage>

<MaxResults>25</MaxResults>

</ResultsPerPage>

<ResultsPerPage>


</ResultsPerPage>

<ResultsPerPage>


</ResultsPerPage>

</ResultsPerPageGroup>

<ResultsSortByGroup>

of 39

<ResultsSortBy>

<SortDescription>Title (Relevance)</SortDescription>

<SortCode>title_rel</SortCode>

</ResultsSortBy>

<ResultsSortBy>

<SortDescription>Title (Ascending)</SortDescription>

<SortCode>title_asc</SortCode>

</ResultsSortBy>

<ResultsSortBy>

<SortDescription>Title (Descending)</SortDescription>

<SortCode>title_desc</SortCode>

</ResultsSortBy>

</ResultsSortByGroup>

</Response>

</GetReferenceDataResult>

</GetReferenceDataResponse>

</soap:Body>

</soap:Envelope>

3.3 ISN Search



Method: GetPermissionByIdentifier

URL: http://<HOST>/Public/lookupapi/v1/lookup.asmx?op=GetPermissionByIdentifier

Format (SOAP 1.2):

2.0 ISN Search

"Permission" Message

"No Match Found" Message

"ISN Search" Request

External

Application

Public Lookup

API

[Response Either]opt

[Response Or]opt




of 39




<soap12:Body>

<GetPermissionByIdentifier


<RequestParameters>





<Identifier>string</Identifier>

<LicenceType>int</LicenceType>

<UsageType>int</UsageType>

<CountryCode>int</CountryCode>



</GetPermissionByIdentifier>

</soap12:Body>

</soap12:Envelope>

Elements:


Mandatory Comments

RequestSystem a..50 Yes see section 3.14

SenderName a..100 No see section 3.14

MessageId n..9 No see section 3.14

Identifier a..50 Yes ISSN/ISBN to be searched

LicenceType n..9 Yes LicenceCode from reference data

UsageType n..9 Yes UsageCode from reference data

CountryCode n..9 No CountryCode from reference data

e.g:




<soap12:Body>

<GetPermissionByIdentifier


<RequestParameters>





<Identifier>9781111111111</Identifier>

<LicenceType>111</LicenceType>

<UsageType>1</UsageType>




</GetPermissionByIdentifier>

</soap12:Body>

</soap12:Envelope>

of 39



Elements:

Element Name Data Type Mandatory Comments RequestParameters Values returned from request. See

request details



MessageId n..9 No

Identifier a..50 Yes

LicenceType n..9 Yes

UsageType n..9 Yes

CountryCode n..9 No

Status See section 4


FieldName a..50 No



Permission Yes Permission container

ManifestationId n..9 Yes CLA unique indexed key for a manifestation

Title a..300 Yes Actual title of the manifestation

Identifier a..50 Yes ISSN/ISBN of the manifestation

IdentifierType a..50 Yes Whether the manifestation is an ISBN or ISSN

Contributor a..100 No Author of the manifestation

PublicationType a..50 Yes Publication type of the manifestation

PublicationForm a..50 Yes Format of the manifestation e.g. digital, website

PublicationCountry a..50 Yes Country of publication of the manifestation

Publisher a..100 No Publisher of the manifestation

TitlePermissionMessage Yes Title Permission Message Contains a Header element with optional Header Information, one or more Permission Definition elements and optional Footer and Restriction elements

Header Yes Header container

PositiveHeader a..500 One is mandatory

Indicates a positive header

NegativeHeader a..500 Indicates a negative header

WarningHeader a..500 Indicates a warning header

NeutralHeader a..500 Indicates a neutral header

HeaderInformation No Describes text before the permission list. Can contain 1 or more paragraph elements

Paragraph No A Paragraph containing any number of the below elements in any order that can be repeated

InformationText a..500 No Informational text block

ImportantText a..500 No Important text block

CommentText a..500 No Comment text block

InformationResource No Describes an information reference to another resource

Address a..500 No The address of the resource

ResourceText a..500 No The text of the resource

ImportantResource No Describes an important reference to another resource



CommentResource No Describes an comment reference to another resource



PermissionDefinitions No Describes a list of permission definitions. Contains 0 or more of the following

PositiveReusageSpec a..500 No A positive permission text

NegativeReusageSpec a..500 No A negative permission text

NeutralReusageSpec a..500 No A neutral permission text

of 39

Footer Yes

FooterInformation No Describes text after the permission list Can contain 1 or more paragraph elements





InformationEmphasisText a..500 No Informational emphasis text block

ImportantEmphasisText a..500 No Important emphasis text block

CommentEmphasisText a..500 No Comment emphasis text block










Restriction No A restriction of the specified manifestation

RestrictionText a..500 No The title of the restriction

RestrictionMessage a..500 No The text of the restriction

An example of the XML portion of a response is shown below (Note - some lines might be wrapped):

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"



<soap:Body>

<GetPermissionByIdentifierResponse


<GetPermissionByIdentifierResult>

<Response xmlns="">

<RequestParameters>









<Status>


</Status>

<Permission>

<ManifestationId>111111</ManifestationId>

<Title>Finance</Title>


<IdentifierType>ISBN</IdentifierType>

<Contributor>KING</Contributor>

<PublicationType>Book</PublicationType>

<PublicationForm>Print</PublicationForm>

<PublicationCountry>United Kingdom of Great Britain & N.

Ireland</PublicationCountry>

<Publisher>FINANCIAL BOOK CORP.</Publisher>

<TitlePermissionMessage>

<Header>

of 39

<PositiveHeader>Subject to defined extent limits, this title is

covered by your CLA licence for the following uses:</PositiveHeader>

</Header>

<PermissionDefinitions>

<PositiveReusageSpec>Photocopy extracts from paper originals and

share with colleagues</PositiveReusageSpec>

<PositiveReusageSpec>Fax to colleagues</PositiveReusageSpec>

<PositiveReusageSpec>Supply copies for regulatory and technical

submissions in the UK</PositiveReusageSpec>

<PositiveReusageSpec>Outsource photocopying</PositiveReusageSpec>

</PermissionDefinitions>

<Footer>

<FooterInformation>

<Paragraph>

<ImportantText>This text is intended for use as guidance only

and not as a substitute for the CLA</ImportantText>

<ImportantResource>

<Address>http://www.cla.co.uk/business/business_documents</Address>

<ResourceText>Licence Terms</ResourceText>

</ImportantResource>

<ImportantText>themselves, which should be read in full. In the

event of conflict between the two, the Licence shall prevail.</ImportantText>

</Paragraph>

<Paragraph>

<ImportantText>For permissions not listed above, please contact

the publisher direct.</ImportantText>

</Paragraph>

</FooterInformation>

</Footer>

</TitlePermissionMessage>

</Permission>

</Response>

</GetPermissionByIdentifierResult>

</GetPermissionByIdentifierResponse>

</soap:Body>

</soap:Envelope>

of 39

3.4 Title Search



Method: SearchTitle

URL: http://<HOST>/Public/lookupapi/v1/lookup.asmx?op=SearchTitle

Format (SOAP 1.2):




<soap12:Body>

<SearchTitle xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">

<RequestParameters>





<Title>string</Title>


3.0 Title Search


Manifestation ID Search

"List of Manifestations" Message


"Title Search" Request

External

Application

Public Lookup

APIUse Case End


[Response Or]opt


Manifestation ID Search

"List of Manifestations" Message


"Title Search" Request

of 39



<SortBy>string</SortBy>

<PageIndex>int</PageIndex>

<MaxResults>int</MaxResults>



</SearchTitle>

</soap12:Body>

</soap12:Envelope>

Elements:


Mandatory Comments




Title a..300 Yes Title to be searched



CountryCode n..9 No Country identifier to be searched on (from reference data)

SortBy a..50 No Indicates how results should be sorted (ResultsSortBy->SortCode from reference data). The default sort order is by relevance (title_rel)

PageIndex n..9 No Page index to display, 0 being first page. The default page index is 0

MaxResults n..9 No The maximum number of manifestations to be retuned in the response. (ResultsPerPage->MaxResults from reference data). The default maximum number is 50.

e.g:




<soap12:Body>

<SearchTitle xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">

<RequestParameters>





<Title>Economics</Title>




<SortBy>title_asc</SortBy>

<PageIndex>0</PageIndex>




</SearchTitle>

</soap12:Body>

</soap12:Envelope>



Elements:

of 39


Mandatory

Comments

RequestParameters Yes Values returned from request. See request details.



MessageId n..9 No

Title a..300 Yes

LicenceType n..9 Yes

UsageType n..9 Yes

CountryCode n..9 No

SortyBy a..50 Yes Default values returned if none sent in request

PageIndex n..9 Yes Default values returned if none sent in request

ResultsPerPage n..9 Yes Default values returned if none sent in request

Status Yes See Section 4


FieldName a..50 No



Manifestations No Manifestation container. Can contain 1 or more Manifestations.

ResultsReturned n..9 Yes Number of manifestations retuned in this response

MaxPossibleResults n..9 Yes Maximum number of possible results which can be returned for the search criteria

Manifestation Yes Repeating group of manifestations. Contains the metadata for the manifestation.



Identifier a..50 Yes ISSN/ISBN of the manifestation




PublicationForm a..50 Yes Format of the manifestation e.g. digital, website


Publisher a..100 Yes Publisher of the manifestation

Permission No Permission container



Identifier a.50 Yes ISSN/ISBN of the manifestation




PublicationForm a..50 Yes Format of the manifestation e.g. digital,

of 39


Mandatory

Comments

website


Publisher a..100 No Publisher of the manifestation

TitlePermissionMessage Yes Title Permission Message Contains a Header element with optional Header Information, one or more Permission Definition elements and optional Footer andRestriction elements


PositiveHeader a..500 One is mandato

ry












ResourceText

a..500 No The text of the resource






ResourceText






Footer Yes






InformationEmphasisText

a..500 No Informational emphasis text block





ResourceText




ResourceText




ResourceText



RestrictionText a..500 No The title of the restriction.


of 39





<soap:Body>

<SearchTitleResponse xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">

<SearchTitleResult>

<Response xmlns="">

<RequestParameters>




<Title>Economics</Title>




<SortBy>title_asc</SortBy>

<PageIndex>0</PageIndex>



<Status>


</Status>

<Manifestations>

<ResultsReturned>25</ResultsReturned>

<MaxPossibleResults>250</MaxPossibleResults>

<Manifestation>


<Title>ECONOMICS</Title>







<Publisher>Economical</Publisher>

</Manifestation>

<Manifestation>


<Title>ECONOMICS</Title>







<Publisher>Education Publishing</Publisher>

</Manifestation>

<Manifestation>


<Title>BUSINESS ECONOMICS</Title>







<Publisher>Economics Education</Publisher>

</Manifestation>

</Manifestations>

</Response>

of 39

</SearchTitleResult>

</SearchTitleResponse>

</soap:Body>

</soap:Envelope>

3.5 Manifestation Id Search


See 3.4.1


Method: GetPermissionByManifestationId

URL: http://<HOST>/Public/lookupapi/v1/lookup.asmx?op=GetPermissionByManifestationId

Format (SOAP 1.2):




<soap12:Body>

<GetPermissionByManifestationId


<RequestParameters>





<ManifestationId>int</ManifestationId>




<Title>string</Title>

<Identifier>string</Identifier>



</GetPermissionByManifestationId>

</soap12:Body>

</soap12:Envelope>

Elements:


Mandatory Comments




ManifestationId n..9 Yes Manifestation ID to be searched



CountryCode n..9 No Country identifier to be searched on (from reference data)

Title a..300 No Optional title (for support purposes)

Identifier a..50 No Optional Identifier (for support purposes)

of 39

e.g: <soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"



<soap12:Body>

<GetPermissionByManifestationId


<RequestParameters>








<Title>Econometrics</Title>




</GetPermissionByManifestationId>

</soap12:Body>

</soap12:Envelope>



Elements:


Mandatory Comments

RequestParameters Values returned from request. See request details

RequestSystem a..50 Yes SenderName a..100 No MessageId n..9 No ManifestationId n..9 Yes LicenceType n..9 Yes UsageType n..9 Yes CountryCode n..9 No Title a..300 No Identifier a..50 No

Status See section 4

StatusCode a..50 Yes FieldName a..50 No FieldValue a..500 No StatusMessage a..500 No

Permission Permission container


Title a..300 Yes Actual title of the manifestation Identifier a..50 Yes ISSN/ISBN of the manifestation IdentifierType a..50 Yes Whether the manifestation is an ISBN

or ISSN Contributor a..100 No Author of the manifestation PublicationType a..50 Yes Publication type of the manifestation PublicationForm a..50 Yes Format of the manifestation e.g.

digital, website PublicationCountry a..50 Yes Country of publication of the

manifestation Publisher a..100 No Publisher of the manifestation TitlePermissionMessage Yes Title Permission Message

Contains a Header element with optional Header Information, one or more Permission Definition elements and optional Footer and Restriction

of 39

elements Header Yes Header container


Indicates a positive header NegativeHeader a..500 Indicates a negative header WarningHeader a..500 Indicates a warning header


HeaderInformation No Describes text before the permission list Can contain 1 or more paragraph elements









Address a..500 Yes The address of the resource

ResourceText a..500 Yes The text of the resource











Footer






















<soap:Body>

<GetPermissionByManifestationIdResponse


of 39

<GetPermissionByManifestationIdResult>

<Response xmlns="">

<RequestParameters>







<Title>Business Economics</Title>



<Status>


</Status>

<Permission>


<Title>Business Economics</Title>


<Contributor>KING</Contributor>





<Publisher>Education Publications</Publisher>


<Header>

<PositiveHeader>Subject to defined extent limits, this title is

covered by your CLA licence for the following uses:</PositiveHeader>

</Header>

<PermissionDefinitions>

<PositiveReusageSpec>Photocopy extracts from paper originals and

share with colleagues</PositiveReusageSpec>

<PositiveReusageSpec>Fax to colleagues</PositiveReusageSpec>

<PositiveReusageSpec>Supply copies for regulatory and technical

submissions in the UK</PositiveReusageSpec>

<PositiveReusageSpec>Outsource photocopying</PositiveReusageSpec>

</PermissionDefinitions>

<Footer>

<FooterInformation>

<Paragraph>

<ImportantText>This text is intended for use as guidance only

and not as a substitute for the CLA</ImportantText>

<ImportantResource>

<Address>http://www.cla.co.uk/business/business_documents</Address>

<ResourceText>Licence Terms</ResourceText>

</ImportantResource>

<ImportantText>themselves, which should be read in full. In the

event of conflict between the two, the Licence shall prevail.</ImportantText>

</Paragraph>

<Paragraph>

<ImportantText>For permissions not listed above, please contact

the publisher direct.</ImportantText>

</Paragraph>


</Footer>


</Permission>

</Response>

</GetPermissionByManifestationIdResult>

</GetPermissionByManifestationIdResponse>

</soap:Body>

</soap:Envelope>

of 39

3.6 Get Permission By Identifier Ext



Method: GetPermissionByIdentifierExt

URL: http://<HOST>/Public/lookupapi/v1/lookup.asmx?op=GetPermissionByIdentifierExt

Format (SOAP 1.2):

For Example message and elements description see 3.3.2


The response message has the same structure as 3.3.3 with the additional fields described below

Element Name Data Type Mandatory Comments AdditionalPermissionMessages a..250 No

TitlePermissionMessage

UsageTypeDescription a..250 No The type of Usage








2.0 ISN Search




External

Application

Public Lookup

API


[Response Or]opt




of 39


















Footer Yes





















An example of the additional XML portion of a response that is nested in the Permission tags is shown below (Note - some lines might be wrapped): <AdditionalPermissionMessages>


<UsageTypeDescription>NLA Print

Hardcopy</UsageTypeDescription>

<Header>

<PositiveHeader>Subject to defined extent

limits, this title is covered by your NLA licence</PositiveHeader>

</Header>

<Footer>

<FooterInformation>

<Paragraph>

<ImportantText>This text is intended for

use as guidance only and not as a substitute for the NLA Licence Terms

themselves, which should be read in full. In the event of conflict between

the two, the Licence shall prevail.</ImportantText>

</Paragraph>

of 39

<Paragraph>

<ImportantText>For permissions not listed

above, please contact the publisher direct.</ImportantText>

</Paragraph>


</Footer>



<UsageTypeDescription>NLA Print

Electronic</UsageTypeDescription>

<Header>

<PositiveHeader>Subject to defined extent

limits, this title is covered by your NLA licence</PositiveHeader>

</Header>

<Footer>

<FooterInformation>

<Paragraph>

<ImportantText>This text is intended for

use as guidance only and not as a substitute for the NLA Licence Terms

themselves, which should be read in full. In the event of conflict between

the two, the Licence shall prevail.</ImportantText>

</Paragraph>

<Paragraph>

<ImportantText>For permissions not listed

above, please contact the publisher direct.</ImportantText>

</Paragraph>


</Footer>


</AdditionalPermissionMessages>

3.7 Get Permission By Manifestation Id Ext


See 3.4.1


Method: GetPermissionByManifestationId

URL: http://<HOST>/Public/lookupapi/v1/lookup.asmx?op=GetPermissionByManifestationId

Format (SOAP 1.2): see 3.5.2


of 39

4. Request Status

Below are the various statuses which can be returned in the response messages. Each Status element contains a StatusCode and a combination of FieldName (indicating the name of the field the status refers to if appropriate), FieldValue (indicating the value of the field the status refers to if appropriate) and StatusMessage (showing a friendly message if appropriate).

Element Name Data Type Mandatory


FieldName a..50 No



Element configuration:

StatusCode Severity Field Value Message Comments

SUCCESS SUCCESS N/A N/A

Service successful. Response data if any is returned inside the Body element of the response.

FAILURE

FAILURE N/A N/A

The service was unsuccessful due to an internal error.

UNAVAILABLE

FAILURE N/A N/A

The service requested is currently unavailable; this may be due to maintenance.

REQUEST_TIMEOUT FAILURE N/A N/A N/A The service has timed out trying to perform the request, this may be due to server issues.

MISSING_MANDATORY_ELEMENT FAILURE The name of the missing field.

N/A

A mandatory element has not been included in the request.

INVALID_REQUEST_SYSTEM FAILURE RequestSystem RequestSystem value

The RequestSystem in the request does not match CLA system records.

INVALID_VALUE FAILURE Request parameter field name with the incorrect value

Value that is incorrect

The value of one of the request parameters was invalid. E.g. this may be due to the wrong licence type being specified.

NO_RESULTS SUCCESS N/A N/A N/A No results were found matching the search request.

INVALID_PARAMETER_FORMAT FAILURE N/A N/A

The parameter list was not in the correct XML format.

UNKNOWN_PARAMETER FAILURE Unknown Parameter Name

Unknown Parameter value

One of the parameters received was unknown.

Example: <Status> <StatusCode>INVALID_VALUE</StatusCode> <FieldName>Identifier</FieldName> <FieldValue>1234</FieldValue> <StatusMessage>The check digit is incorrect</StatusMessage> </Status>

of 39

Appendix A - Examples from CLA Website Lookup

A.1 Positive Message

Yeti sightings in Rural Wales

314159265

Cryptid Society

HEADER

PERMISSION

DETAILS

FOOTER

RESTRICTION

}

of 39

A.2 Warning Message

Coding the ZX Spectrum in 2010

271828183

HEADER

INFORMATION

PERMISSION

DETAILS } FOOTER

of 39

A.3 Negative Message

Life on the edge: a Memoir

161803399

Themistoclea

Pythagorus

HEADER

PERMISSION

DETAIL

functional specification web services

Documents