OLE DocStore and Discovery

Service Contracts

 

 

This document describes the API of the services provided by OLE DocStore and Discovery. These services can be used from other Kuali applications.

DocStore Services:

1.    Ingest

Class:

            IngestNIndexHandlerService

Method:

            ingestNIndexRequestDocuments()

Description:

            Ingest the given data into DocStore and index it in Discovery.

Input:

            Request object  - Information about the ingest operation to be

                                         performed(operation=batchIngest)

Returns:

            Response object – Information about the response from the service for the given request

Errors  :

            OleException

                        - When there is unsupported document format, type or category

                          - When Ingest or Indexing fails

Support objects used: Request, Response

       Request: Information about the ingest operation to be performed

 

• user (String) -User who initiated  the request
• operation (String) – The operation to be performed (eg: batchIngest, bulkIngest...etc)
• requestDocuments (List<RequestDocument>) – List of documents on which the requested operation is to be performed.

     

            RequestDocument :   Documents on which the requested operation is to be performed.

  

• id  (String) – Identifier of the document
• category (String) -Category of the document
• type (String) – Type of the document
• format (String) – Format of the document
• content (Content) – Content of the document         

Content :

    

• content (String) – xml string representation of the document content
• contentObject (Object) – Pojo representation of the document content

Response: Information about the response from the service for the given request

• user (String) – User  who raised the request related to this response
• operation (String) – Operation performed (eg: batchIngest, bulkIngest...etc)
• status (String) – Status of the operation (eg: sucess, failure)
• message (String) – Information about the operation performed
• documents (List<ResponseDocument>) – List of documents with information about the result of the operation

ResponseDocument : Documents with information about the result of the operation

• id  (String) - Identifier of the document ( unique within the request)
• category (String) -Category of the document
• type (String) -Type of the document
• format (String) -Format of the document
• uuid (String) – uuid of the document (unique within docstore)
• content (Content) - Content of the document          
• linkedDocuments (List<ResponseDocument>) – List of documents which are linked / referred to by the current document

2.    Bulk Ingest

Class:

BulkLoadHandler

Method:

loadBulk()

Description :

Ingest the given data into DocStore.

Input:

            File – File to be ingested

            userName – User initiating the request

            action – Action to be performed (bulkIngest)  

Returns:

            List of uuid’s – uuids of the ingested documents

Errors  :

OleException

-         When the batch size is invalid

-         When the format of input document not valid

-         When a node cannot be created or found in the repository

-         When there is internal error in the repository

Support objects used:

3.    Checkout

Class:

            DocumentStoreManager

Method:

            checkOut()

Description :

            Get the content of the documents specified in the Request object.

Input:

            Request object - Information about the checkout operation to be performed        (operation=checkout)

Returns:

            Respone object - Information about the response from the service for the given request

Errors  :

            OleException

-          When there is problem extracting the content of a node in the repository

Support objects used:

4.    Checkin

Class:

            DocumentStoreManager

Method:

            updateRecord()

Description:

            Check-in the  documents specified in the Request object into DocStore as new versions.

Input:

            Request object - Information about the checkin operation to be performed (operation:checkin)

Returns:

            Response object - Information about the response from the service for the given request

Errors  :

            OleException

-         When there is unsupported document format

Support objects used: Request, Response

5.    Delete

Class:

            DocumentStoreManager

Method:

            processDeleteRequest()

Description:

            Delete the documents specified in the given Request object.

Input:

            Request object -  Information about the delete operation to be performed(operation=delete,

            deleteWithLinkedDocs)

Returns:

            Response object  - Information about the response from the service for the given request

Errors  : No exceptions

Support objects used: Request, Response

6.    REST API

A concrete implementation of a REST Web service follows four basic design principles:

• Expose directory structure-like URIs.
• Transfer XML, JavaScript Object Notation (JSON), or both.
• Use HTTP methods explicitly.
• Be stateless.
  

DocStore API as per design principles of REST

6.1   Create

Create one or more documents with text content:

Create one or more documents with binary content (PDF, DOC etc)

6.2   Retrieve

Retrieve a document (Checkout)

Q: Do we need to identify the user who initiated this request?

Retrieve (references to) one or more documents: (like getUUIDs function in docstore)

Retrieve one or more documents with binary content (PDF, DOC etc)

6.3   Update

If the specified document does not exist, it is not created by this command.

Modify one or more documents:

Modify one or more documents with binary content (PDF, DOC etc):

6.4   Delete

Delete a document:

Delete one or more documents

        

Discovery Services:

 

1. Index Documents

            Class :

                         IndexerServiceImpl

            Method:

                        indexDocuments()

            Description :

                        Index the documents specified in the given list of RequestDocuments

            Input:

                        List<RequestDocument> -  list of documents to be indexed

             Returns:

                        String [ Success, Failure]

             Errors  :

                        OleException

                                    -  When there is unsupported document format

             Support objects used:

      

2. Search

         

            Class :

                        DiscoveryServiceImpl

            Method:

                        search()

            Description:  

                        Search for documents with the given SearchParams.

            Input:

                        SearchParams – Search related conditions and parameters  

             Returns: 

                        Solr xml response – Search results in xml format from solr

            Errors  : No exceptions

                                    -

             Support objects used:

       

                        SearchParams :

                 

• searchType (String)  - Type of search (eg: advancedSearch, quickSearch...etc)
• docCategory (String) – Category of documents to be searched for
• docType  (String)  - Type of documents to be searched for
• docFormat (String) – Format of documents to be searched for
• searchFieldsList (List<SearchCondition>) - List of search conditions
• sortField  (String) -Field to be sort by
• sortOrder  (String) – Order to be sort by
• facetFieldList  (List<String>) - List of facet fields
• facetField (String) – Field to be filter for search results
• facetValue (String) – Value to be filter for search results
• fieldList  (List<String>) - Field to be display in the search results   
• rows  (int) – No of rows to be returned
• start   (int) – Start index of the results to be returned

SearchCondition: Condition to be applied for searching the results

• searchText  (String) – Text to be searched for
• searchScope  (String) – Scope of the search text (All of these, Any of these, As a phrase)
• docField      (String) – Field to be searched for
• operator      (String) – To join with next condition

3. Query For OleDocs

       

             Class:

                        QueryServiceImpl

              Method:

                        queryForDocs()

             Description: 

                        Search for documents with the given* * OleDocument. Uses the field values

                                      in the input OleDocument to look for similar OleDocuments in the Solr and

                                      returns them.

            Input:

                        OleDocument

             Returns:

                        List<OleDocument>

            Errors  : No exceptions

             Support objects used:

 OleDocument:

• id (String) – uuid of the document to be searched for
• docCategory (DocCategory) - Category of the document to be searched for
• docType (DocType) - Type of the document to be searched for

                        WorkBibDocument extends  OleDocument:

• titles   (List<String>) - one or more titles of the document
• authors  (List<String>) - one or more authors of the document
• subjects  (List<String>) - one or more subjects of the document
• issns    (List<String>) - one or more issns of the document
• isbns (List<String>) - one or more isbns of the document
• publicationPlaces (List<String>) - one or more publicationPlaces of the document
• publishers  (List<String>) - one or more publishers of the document
• descriptions   (List<String>) - one or more descriptions of the document
• publicationDates   (List<String>) - one or more publicationDates of the document
• editions  (List<String>) - one or more editions of the document
• formGenres  (List<String>) - one or more formGenres of the document
• languages  (List<String>) - one or more languages of the document
• formats    (List<String>) - one or more formats of the document
• itemLinks    (List<String>) - one or more itemLinks of the document

 

=====================================================================

Reference

--- Forwarded Message ---
From: Jonathan Keller <keller.jonathan@gmail.com>
To: "Ma, Nianli" <nianma@indiana.edu>
Cc: "Wadia, Percy Dadabhoy" <pwadia@indiana.edu>; Joseph Kumar <kumartkumar@yahoo.com>
Sent: Thursday, January 12, 2012 11:05 PM
Subject: Re: Service Registry approach

The reference to service contracts was that, since these are separate systems, we want to define and document *what* the calls will be, what parameters they will take and what will be returned.

Having this defined up front will make it easier to design the process from both ends.  I recommend starting with the Select module code base so as to define the contents of the API message objects so that they contain all the data you need to create a purchase order (or whatever document you need to create.)  The Rice team has been doing a lot of work for client/server service compatibility in the 2.0 line.  If these projects stay separate, we may want to look into that in the future.  But for now, it would only complicate things.

Actually, I created a spec for an API for creating requisitions a while ago. (extract below) You could consider using something similar.  Some of the objects were designed to be generic, and used for multiple document creation services.

I hope this helps.  Please let me know if you have any questions.

------------------------------------------------------------

Create Purchase Requisition

Create (in select module) the PurchasingDocumentsInterfaceService.

Method Name: uploadRequisition
Inputs: orderInfo (PurchaseRequisitionInfo)
Returns: DocumentCreationResult

Support objects for service calls:

PurchaseRequisitionInfo:

• documentInfo (DocumentInfo)
• requestorUserId (String)
• sourceSystemOrderId (String)
• requestTypeCode (String - 4 chars) type of document being requested
• deliveryAddress (PurchasingAddressInfo)
• deliveryInstructionText (String)
• vendorHeaderId (String)
• vendorDetailId (String)
• freightAmount (String) String to avoid parsing problems; will be
    handled on the server during validation
• shippingAndHandlingAmount (String)
• items (PurchasingItemInfo)

DocumentInfo:

• initiatorUserId (String)

• documentNote (String - 4000 characters) Note which will be attached to the document
  once created.

• description (String - 40 characters)
• explanation (String - 400 characters)
• organizationTrackingNumber (String - 10 characters)

PurchasingAddressInfo:

• name (String)
• addressLine1 (String - 45 chars)
• addressLine2 (String - 45 chars)
• cityName (String - 45 chars)
• stateCode (String - 2 chars)
• countryCode (String - 3 chars)
• emailAddress (String)
• phoneNumber (String)
• campusCode (String)
• buildingCode (String)
• roomNumber (String)

PurchasingItemInfo:

• unitOfMeasureCode (String - 4 chars)
• description (String - 400 chars)
• commodityCode (String)
• unitPrice (String)
• quantity (String)
• itemTypeCode (String - 4 chars)
• accountingInfo (List<PurchasingAccountingInfo>)

PurchasingAccountingInfo:

• chartOfAccountsCode (String - 2 chars)
• accountNumber (String - 7 chars)
• subAccountNumber (String - 5 chars)
• objectCode (String - 4 chars)
• subObjectCode (String - 3 chars)
• projectCode (String - 10 chars)
• distributionPercent (String)

DocumentCreationResult:

• success (boolean)
• messages (List<ResultMessage>)
• documentNumbers (List<String>)

ResultMessage:

• message (String)
• code (String)
• severity (String)

--
Jonathan Keller
Kuali OLE - Kuali Technologies Consultant
jkeller@kuali.org