functional specification web services
TRANSCRIPT
Page 1 of 39
Functional Specification
Web Services
Permission Lookup
Version v2.1
Page 2 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
Page 3 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.1 Sequence Diagram ........................................................................................................... 19
3.3.2 Request Message ............................................................................................................ 19
3.3.3 Response Message.......................................................................................................... 21
3.4 Title Search ............................................................................................................................. 24
3.4.1 Sequence Diagram ........................................................................................................... 24
3.4.2 Request Message ............................................................................................................ 24
3.4.3 Response Message.......................................................................................................... 25
3.5 Manifestation Id Search ......................................................................................................... 29
Page 4 of 39
3.5.1 Sequence Diagram ........................................................................................................... 29
3.5.2 Request Message ............................................................................................................ 29
3.5.3 Response Message.......................................................................................................... 30
3.6 Get Permission By Identifier Ext .......................................................................................... 33
3.6.1 Sequence Diagram ........................................................................................................... 33
3.6.2 Request Message ............................................................................................................ 33
3.6.3 Response Message.......................................................................................................... 33
3.7 Get Permission By Manifestation Id Ext .............................................................................. 35
3.7.1 Sequence Diagram ........................................................................................................... 35
3.7.2 Request Message ............................................................................................................ 35
3.7.3 Response Message.......................................................................................................... 35
4. Request Status ................................................................................................... 36
Appendix A – Examples from CLA Website Lookup
Page 5 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).
Page 6 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.
Page 7 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.
Page 8 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.
Page 9 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
Page 10 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
SenderName (Optional)
Page 11 of 39
MessageId (Optional)
LicenceType
UsageType
Identifier
CountryCode (Optional)
Response elements
RequestParameters o RequestSystem o SenderName o MessageId o Identifier o LicenceType o UsageType o CountryCode
Status o StatusCode o FieldName o FieldValue o StatusMessage
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
Page 12 of 39
returned.
Request elements
RequestSystem
SenderName (Optional)
MessageId
Title
LicenceType
UsageType
CountryCode (Optional)
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
Status o StatusCode o FieldName o FieldValue o StatusMessage
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
Page 13 of 39
RequestSystem
SenderName (Optional)
MessageId (Optional)
ManifestationId
LicenceType
UsageType
CountryCode (Optional)
Title (Optional)
Identifier (Optional)
Response elements
RequestParameters o RequestSystem o SenderName o MessageId o ManifestationId o LicenceType o UsageType o CountryCode o Identifier
Status o StatusCode o FieldName o FieldValue o StatusMessage
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
Page 14 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
Page 15 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
Page 16 of 39
<RequestParameters>
<RequestParameters xmlns="">
<RequestSystem>string</RequestSystem>
<SenderName>string</SenderName>
<MessageId>int</MessageId>
</RequestParameters>
</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: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/">
<RequestParameters>
<RequestParameters xmlns="">
<RequestSystem>APITestApplication</RequestSystem>
<SenderName>Documentation</SenderName>
<MessageId>100</MessageId>
</RequestParameters>
</RequestParameters>
</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:
Element Name Data Type
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.
Page 17 of 39
Element Name Data Type
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>
<RequestSystem>APITestApplication</RequestSystem>
<SenderName>Documentation</SenderName>
<MessageId>100</MessageId>
</RequestParameters>
<Status>
<StatusCode>SUCCESS</StatusCode>
</Status>
<LicenceTypeGroup>
<LicenceType>
<UsageTypeGroup>
<UsageType>
<UsageDescription>Photocopying</UsageDescription>
<UsageCode>1</UsageCode>
</UsageType>
<UsageType>
<UsageDescription>Scanning</UsageDescription>
<UsageCode>2</UsageCode>
</UsageType>
<UsageType>
<UsageDescription>Digital</UsageDescription>
<UsageCode>8</UsageCode>
</UsageType>
</UsageTypeGroup>
<LicenceDescription>Business</LicenceDescription>
<LicenceCode>134</LicenceCode>
</LicenceType>
Page 18 of 39
<LicenceType>
<UsageTypeGroup>
<UsageType>
<UsageDescription>Photocopying</UsageDescription>
<UsageCode>1</UsageCode>
</UsageType>
<UsageType>
<UsageDescription>Scanning</UsageDescription>
<UsageCode>2</UsageCode>
</UsageType>
<UsageType>
<UsageDescription>Digital</UsageDescription>
<UsageCode>8</UsageCode>
</UsageType>
</UsageTypeGroup>
<LicenceDescription>Further Education</LicenceDescription>
<LicenceCode>132</LicenceCode>
</LicenceType>
<LicenceType>
<UsageTypeGroup>
<UsageType>
<UsageDescription>Photocopying</UsageDescription>
<UsageCode>1</UsageCode>
</UsageType>
<UsageType>
<UsageDescription>Scanning</UsageDescription>
<UsageCode>2</UsageCode>
</UsageType>
<UsageType>
<UsageDescription>Digital</UsageDescription>
<UsageCode>8</UsageCode>
</UsageType>
</UsageTypeGroup>
<LicenceDescription>Higher Education</LicenceDescription>
<LicenceCode>136</LicenceCode>
</LicenceType>
</LicenceTypeGroup>
<CountryGroup>
<Country>
<CountryDescription>United Kingdom of Great Britain & N.
Ireland</CountryDescription>
<CountryCode>1</CountryCode>
</Country>
<Country>
<CountryDescription>Afghanistan</CountryDescription>
<CountryCode>6</CountryCode>
</Country>
<Country>
<CountryDescription>Albania, People's Socialist Republic
of</CountryDescription>
<CountryCode>7</CountryCode>
</Country>
</CountryGroup>
<ResultsPerPageGroup>
<ResultsPerPage>
<MaxResults>25</MaxResults>
</ResultsPerPage>
<ResultsPerPage>
<MaxResults>50</MaxResults>
</ResultsPerPage>
<ResultsPerPage>
<MaxResults>100</MaxResults>
</ResultsPerPage>
</ResultsPerPageGroup>
<ResultsSortByGroup>
Page 19 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
3.3.1 Sequence Diagram
3.3.2 Request Message
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
"Permission" Message
"No Match Found" Message
"ISN Search" Request
Page 20 of 39
<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>
<GetPermissionByIdentifier
xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">
<RequestParameters>
<RequestParameters xmlns="">
<RequestSystem>string</RequestSystem>
<SenderName>string</SenderName>
<MessageId>int</MessageId>
<Identifier>string</Identifier>
<LicenceType>int</LicenceType>
<UsageType>int</UsageType>
<CountryCode>int</CountryCode>
</RequestParameters>
</RequestParameters>
</GetPermissionByIdentifier>
</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
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: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>
<GetPermissionByIdentifier
xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">
<RequestParameters>
<RequestParameters xmlns="">
<RequestSystem>APITestApplication</RequestSystem>
<SenderName>Documentation</SenderName>
<MessageId>103</MessageId>
<Identifier>9781111111111</Identifier>
<LicenceType>111</LicenceType>
<UsageType>1</UsageType>
<CountryCode>1</CountryCode>
</RequestParameters>
</RequestParameters>
</GetPermissionByIdentifier>
</soap12:Body>
</soap12:Envelope>
Page 21 of 39
3.3.3 Response Message
Successful responses contain items of reference data to be used in subsequent search requests.
Elements:
Element Name Data Type Mandatory Comments RequestParameters Values returned from request. See
request details
RequestSystem a..50 Yes
SenderName a..100 No
MessageId n..9 No
Identifier a..50 Yes
LicenceType n..9 Yes
UsageType n..9 Yes
CountryCode n..9 No
Status See section 4
StatusCode a..50 Yes
FieldName a..50 No
FieldValue a..500 No
StatusMessage a..500 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
Address a..500 No The address of the resource
ResourceText a..500 No The text of the resource
CommentResource No Describes an comment reference to another resource
Address a..500 No The address of the resource
ResourceText a..500 No The text of the 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
Page 22 of 39
Footer Yes
FooterInformation No Describes text after 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
InformationEmphasisText a..500 No Informational emphasis text block
ImportantEmphasisText a..500 No Important emphasis text block
CommentEmphasisText a..500 No Comment emphasis 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
Address a..500 No The address of the resource
ResourceText a..500 No The text of the resource
CommentResource No Describes an comment reference to another resource
Address a..500 No The address of the resource
ResourceText a..500 No The text of the resource
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"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<GetPermissionByIdentifierResponse
xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">
<GetPermissionByIdentifierResult>
<Response xmlns="">
<RequestParameters>
<RequestSystem>APITestApplication</RequestSystem>
<SenderName>Documentation</SenderName>
<MessageId>101</MessageId>
<Identifier>9781111111111</Identifier>
<LicenceType>134</LicenceType>
<UsageType>1</UsageType>
<CountryCode>1</CountryCode>
</RequestParameters>
<Status>
<StatusCode>SUCCESS</StatusCode>
</Status>
<Permission>
<ManifestationId>111111</ManifestationId>
<Title>Finance</Title>
<Identifier>978111111111</Identifier>
<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>
Page 23 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>
Page 24 of 39
3.4 Title Search
3.4.1 Sequence Diagram
3.4.2 Request Message
Method: SearchTitle
URL: http://<HOST>/Public/lookupapi/v1/lookup.asmx?op=SearchTitle
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>
<SearchTitle xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">
<RequestParameters>
<RequestParameters xmlns="">
<RequestSystem>string</RequestSystem>
<SenderName>string</SenderName>
<MessageId>int</MessageId>
<Title>string</Title>
<LicenceType>int</LicenceType>
3.0 Title Search
"Permission" Message
Manifestation ID Search
"List of Manifestations" Message
"No Match Found" Message
"Title Search" Request
External
Application
Public Lookup
APIUse Case End
[Response Either]opt
[Response Or]opt
"Permission" Message
Manifestation ID Search
"List of Manifestations" Message
"No Match Found" Message
"Title Search" Request
Page 25 of 39
<UsageType>int</UsageType>
<CountryCode>int</CountryCode>
<SortBy>string</SortBy>
<PageIndex>int</PageIndex>
<MaxResults>int</MaxResults>
</RequestParameters>
</RequestParameters>
</SearchTitle>
</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
Title a..300 Yes Title to be searched
LicenceType n..9 Yes LicenceCode from reference data
UsageType n..9 Yes UsageCode from reference data
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: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>
<SearchTitle xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">
<RequestParameters>
<RequestParameters xmlns="">
<RequestSystem>APITestApplication</RequestSystem>
<SenderName>Documentation</SenderName>
<MessageId>101</MessageId>
<Title>Economics</Title>
<LicenceType>111</LicenceType>
<UsageType>1</UsageType>
<CountryCode>1</CountryCode>
<SortBy>title_asc</SortBy>
<PageIndex>0</PageIndex>
<MaxResults>25</MaxResults>
</RequestParameters>
</RequestParameters>
</SearchTitle>
</soap12:Body>
</soap12:Envelope>
3.4.3 Response Message
Successful responses contain items of reference data to be used in subsequent search requests.
Elements:
Page 26 of 39
Element Name Data Type
Mandatory
Comments
RequestParameters Yes Values returned from request. See request details.
RequestSystem a..50 Yes
SenderName a..100 No
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
StatusCode a..50 Yes
FieldName a..50 No
FieldValue a..500 No
StatusMessage a..500 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.
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 Yes Publisher of the manifestation
Permission No 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,
Page 27 of 39
Element Name Data Type
Mandatory
Comments
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 andRestriction elements
Header Yes Header container
PositiveHeader a..500 One is mandato
ry
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
Address a..500 No The address of the resource
ResourceText a..500 No The text of the resource
CommentResource No Describes an comment reference to another resource
Address a..500 No The address of the resource
ResourceText
a..500 No The text of the 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
Footer Yes
FooterInformation No Describes text after 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
InformationEmphasisText
a..500 No Informational emphasis text block
ImportantEmphasisText a..500 No Important emphasis text block
CommentEmphasisText a..500 No Comment emphasis 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
Address a..500 No The address of the resource
ResourceText
a..500 No The text of the resource
CommentResource No Describes an comment reference to another resource
Address a..500 No The address of the resource
ResourceText
a..500 No The text of the resource
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
Page 28 of 39
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>
<SearchTitleResponse xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">
<SearchTitleResult>
<Response xmlns="">
<RequestParameters>
<RequestSystem>APITestApplication</RequestSystem>
<SenderName>Documentation</SenderName>
<MessageId>101</MessageId>
<Title>Economics</Title>
<LicenceType>111</LicenceType>
<UsageType>1</UsageType>
<CountryCode>1</CountryCode>
<SortBy>title_asc</SortBy>
<PageIndex>0</PageIndex>
<MaxResults>25</MaxResults>
</RequestParameters>
<Status>
<StatusCode>SUCCESS</StatusCode>
</Status>
<Manifestations>
<ResultsReturned>25</ResultsReturned>
<MaxPossibleResults>250</MaxPossibleResults>
<Manifestation>
<ManifestationId>1111112</ManifestationId>
<Title>ECONOMICS</Title>
<Identifier>9781111111112</Identifier>
<IdentifierType>ISBN</IdentifierType>
<PublicationType>Book</PublicationType>
<PublicationForm>Print</PublicationForm>
<PublicationCountry>United Kingdom of Great Britain & N.
Ireland</PublicationCountry>
<Publisher>Economical</Publisher>
</Manifestation>
<Manifestation>
<ManifestationId>1111112</ManifestationId>
<Title>ECONOMICS</Title>
<Identifier>9781111111112</Identifier>
<IdentifierType>ISBN</IdentifierType>
<PublicationType>Book</PublicationType>
<PublicationForm>Print</PublicationForm>
<PublicationCountry>United Kingdom of Great Britain & N.
Ireland</PublicationCountry>
<Publisher>Education Publishing</Publisher>
</Manifestation>
<Manifestation>
<ManifestationId>1111113</ManifestationId>
<Title>BUSINESS ECONOMICS</Title>
<Identifier>9781111111113</Identifier>
<IdentifierType>ISBN</IdentifierType>
<PublicationType>Book</PublicationType>
<PublicationForm>Print</PublicationForm>
<PublicationCountry>United Kingdom of Great Britain & N.
Ireland</PublicationCountry>
<Publisher>Economics Education</Publisher>
</Manifestation>
</Manifestations>
</Response>
Page 29 of 39
</SearchTitleResult>
</SearchTitleResponse>
</soap:Body>
</soap:Envelope>
3.5 Manifestation Id Search
3.5.1 Sequence Diagram
See 3.4.1
3.5.2 Request Message
Method: GetPermissionByManifestationId
URL: http://<HOST>/Public/lookupapi/v1/lookup.asmx?op=GetPermissionByManifestationId
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>
<GetPermissionByManifestationId
xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">
<RequestParameters>
<RequestParameters xmlns="">
<RequestSystem>string</RequestSystem>
<SenderName>string</SenderName>
<MessageId>int</MessageId>
<ManifestationId>int</ManifestationId>
<LicenceType>int</LicenceType>
<UsageType>int</UsageType>
<CountryCode>int</CountryCode>
<Title>string</Title>
<Identifier>string</Identifier>
</RequestParameters>
</RequestParameters>
</GetPermissionByManifestationId>
</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
ManifestationId n..9 Yes Manifestation ID to be searched
LicenceType n..9 Yes LicenceCode from reference data
UsageType n..9 Yes UsageCode from reference data
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)
Page 30 of 39
e.g: <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>
<GetPermissionByManifestationId
xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">
<RequestParameters>
<RequestParameters xmlns="">
<RequestSystem>APITestApplication</RequestSystem>
<SenderName>Documentation</SenderName>
<MessageId>102</MessageId>
<ManifestationId>111</ManifestationId>
<LicenceType>111</LicenceType>
<UsageType>1</UsageType>
<Title>Econometrics</Title>
<Identifier>9781111111111</Identifier>
</RequestParameters>
</RequestParameters>
</GetPermissionByManifestationId>
</soap12:Body>
</soap12:Envelope>
3.5.3 Response Message
Successful responses contain items of reference data to be used in subsequent search requests.
Elements:
Element Name Data Type
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
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
Page 31 of 39
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
InformationEmphasisText a..500 No Informational emphasis text block
ImportantEmphasisText a..500 No Important emphasis text block
CommentEmphasisText a..500 No Comment emphasis text block
InformationResource No Describes an information reference to another resource
Address a..500 Yes The address of the resource
ResourceText a..500 Yes The text of the resource
ImportantResource No Describes an important reference to another resource
Address a..500 Yes The address of the resource
ResourceText a..500 Yes The text of the resource
CommentResource No Describes an comment reference to another resource
Address a..500 Yes The address of the resource
ResourceText a..500 Yes The text of the 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
Footer
FooterInformation No Describes text after 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 Yes The address of the resource
ResourceText a..500 Yes The text of the resource
ImportantResource No Describes an important reference to another resource
Address a..500 No The address of the resource
ResourceText a..500 No The text of the resource
CommentResource No Describes an comment reference to another resource
Address a..500 No The address of the resource
ResourceText a..500 No The text of the resource
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"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<GetPermissionByManifestationIdResponse
xmlns="http://titlelookup.cla.co.uk/public/lookupapi/v1/">
Page 32 of 39
<GetPermissionByManifestationIdResult>
<Response xmlns="">
<RequestParameters>
<RequestSystem>APITestApplication</RequestSystem>
<SenderName>Documentation</SenderName>
<MessageId>102</MessageId>
<ManifestationId>111113</ManifestationId>
<LicenceType>111</LicenceType>
<UsageType>1</UsageType>
<Title>Business Economics</Title>
<Identifier>9781111111112</Identifier>
</RequestParameters>
<Status>
<StatusCode>SUCCESS</StatusCode>
</Status>
<Permission>
<ManifestationId>3111113</ManifestationId>
<Title>Business Economics</Title>
<IdentifierType>ISBN</IdentifierType>
<Contributor>KING</Contributor>
<PublicationType>Book</PublicationType>
<PublicationForm>Print</PublicationForm>
<PublicationCountry>United Kingdom of Great Britain & N.
Ireland</PublicationCountry>
<Publisher>Education Publications</Publisher>
<TitlePermissionMessage>
<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>
</FooterInformation>
</Footer>
</TitlePermissionMessage>
</Permission>
</Response>
</GetPermissionByManifestationIdResult>
</GetPermissionByManifestationIdResponse>
</soap:Body>
</soap:Envelope>
Page 33 of 39
3.6 Get Permission By Identifier Ext
3.6.1 Sequence Diagram
3.6.2 Request Message
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
3.6.3 Response Message
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
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
2.0 ISN Search
"Permission" Message
"No Match Found" Message
"ISN Search" Request
External
Application
Public Lookup
API
[Response Either]opt
[Response Or]opt
"Permission" Message
"No Match Found" Message
"ISN Search" Request
Page 34 of 39
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
Address a..500 No The address of the resource
ResourceText a..500 No The text of the resource
CommentResource No Describes an comment reference to another resource
Address a..500 No The address of the resource
ResourceText a..500 No The text of the 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
Footer Yes
FooterInformation No Describes text after 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
InformationEmphasisText a..500 No Informational emphasis text block
ImportantEmphasisText a..500 No Important emphasis text block
CommentEmphasisText a..500 No Comment emphasis 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
Address a..500 No The address of the resource
ResourceText a..500 No The text of the resource
CommentResource No Describes an comment reference to another resource
Address a..500 No The address of the resource
ResourceText a..500 No The text of the resource
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 additional XML portion of a response that is nested in the Permission tags is shown below (Note - some lines might be wrapped): <AdditionalPermissionMessages>
<TitlePermissionMessage>
<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>
Page 35 of 39
<Paragraph>
<ImportantText>For permissions not listed
above, please contact the publisher direct.</ImportantText>
</Paragraph>
</FooterInformation>
</Footer>
</TitlePermissionMessage>
<TitlePermissionMessage>
<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>
</FooterInformation>
</Footer>
</TitlePermissionMessage>
</AdditionalPermissionMessages>
3.7 Get Permission By Manifestation Id Ext
3.7.1 Sequence Diagram
See 3.4.1
3.7.2 Request Message
Method: GetPermissionByManifestationId
URL: http://<HOST>/Public/lookupapi/v1/lookup.asmx?op=GetPermissionByManifestationId
Format (SOAP 1.2): see 3.5.2
3.7.3 Response Message
Page 36 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
StatusCode a..50 Yes
FieldName a..50 No
FieldValue a..500 No
StatusMessage a..500 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>
Page 37 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
}
Page 38 of 39
A.2 Warning Message
Coding the ZX Spectrum in 2010
271828183
HEADER
INFORMATION
PERMISSION
DETAILS } FOOTER
Page 39 of 39
A.3 Negative Message
Life on the edge: a Memoir
161803399
Themistoclea
Pythagorus
HEADER
PERMISSION
DETAIL