KRYSTAL™ DMS - Web Services APIs


The KRYSTAL™ DMS Web Services Application Programming Interface (API) gives your developers standard based access to data, content and document management features of KRYSTAL™ DMS - Enterprise Edition. With these API, you can build your bi-directional data transfers, document management customizations applications, and other applications that need to interface with your KRYSTAL™ DMS from remote locations.

You may want to use these API to:

  • Synchronize and replicate data between KRYSTAL™ DMS and your existing enterprise systems.
  • Build your own document management portal.
  • Build your own reporting dashboard that is drive from report metrics and data.

Because these API is based on service-oriented architecture (SOA) and industry-standard technologies like SOAP and WSDL, your developers can use their choice of development tools to gain programmatic access to your organization's Document Management Repository.

These API enables easy integration of your enterprise systems with the documents and data stored in your KRYSTAL™ DMS system, enabling greater automation of document management tasks and processes.

Web Services API Functionalities


The KRYSTAL™ DMS API supports a subset of the functionalities of the KRYSTAL™ DMS - Enterprise Edition user interface as outlined below.

  • Sign in
  • Sign out
  • Get Document Classes
  • Get Documents
  • Get Document Details
  • Get Document Content
  • Get Document Revision Content
  • Search Documents
  • Get Revision History
  • Create Document
  • Delete Document
  • Checkout Document
  • Check in Document
  • Cancel Document Checkout
  • Update Document Indexes
  • Get Document Access History

Web Services API URL


Once you have installed KRYSTAL™ DMS – Enterprise Edition version 8.0 or later, you will have access to the Web Services API.

Primeleaf team will provide you with the Web Services API URL needed to develop your custom built projects.

You will be able to access the WSDL file using following URL.

http://<Your_Server_IP>:<HTTP_Port> /services/DMSService?wsdl

 

For example : http://10.1.1.1:8080/services/DMSService?wsdl

Where

Your_Server_IP is the IP Address or Fully Qualified Domain Name (FQDN) of server where KRYSTAL™ DMS is installed.

HTTP_Port is the port number on which KRYSTAL™ DMS is configured to be running.

Getting Started


To use this guide you must have basic knowledge of software development, SOAP-based Web Services and KRYSTAL™ DMS user interface.

General Steps


In general, any KRYSTAL™ DMS API client application project will involve following steps.

  1. Use the KRYSTAL™ DMS Web Services API Web Services Definition Language (WSDL) document to generate supporting code for executing SOAP-based client call on the API. Your development environment tool of choice should provide support for accomplishing this step.

  2. Use the “Sign On” call to establish a session with the KRYSTAL™ DMS Web Services API. The “Sign On” call will return an “Authentication Token” that should be passed on to all the sub-sequent API calls.

  3. Use the available API calls to accomplish a desired integration objective. If your client application is inactive for longer than 30 (thirty) minutes, the “Authentication Token” will become invalid and your client application will need to make a new “Sign On” call to start a new session.

  4. Use the “Sign Out” call to end the session.

KRYSTAL™ DMS - Web Services API calls


Sign On


Syntax

String authenticationToken = service.signon(String username, String password,String domainName);

Usage

The first step for any client application is to establish a sign on session. This can be achieved using the sign on call. When a client application invokes the sign on call, it passes a user name and password as user credentials. Upon receiving the client application sign on request, the API authenticates these credentials, and returns an “Authentication Token” object. This object is required for use in all subsequent API calls. After successfully completing the sign on call and retrieving the authentication token, a client application needs to set this authentication token in all subsequent calls as a means of authentication.

Session tokens expire automatically after 30 (thirty) minutes of inactivity. Client applications that make infrequent sign on calls should make explicit sign out calls to prevent the accumulation of unnecessary open sessions. A limit is placed on the number of concurrent API sessions that an account can initiate. It is important to properly manage API sessions to avoid exceeding this limit. If the limit is reached, an error message will be returned, stating that the allowed number of concurrent sessions has been exceeded.

Request Parameters

NameTypeDescription
usernameStringUser name for KRYSTAL™ DMS account
passwordStringPassword for the specified user
domainNameStringDomain name to sign on

Response

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session. Note: Your client application needs to set this value in all subsequent service calls.

Sign Out


Syntax

boolean result= service.signout( String authenticationToken );

Usage

Use the Sign Out call to end an API session. The last step for any client application is to end a session by signing out.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token received on successful sign on

Response

NameTypeDescription
resultBooleanFlag representing the success of a request to the end the KRYSTAL™ DMS API session.

Get Document Classes


Syntax

KDocumentClass[] = service.getDocumentClasses( String authenticationToken );

Usage

Use this API call to retrieve all the document classes to which authenticated user has at least read access.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.

Response

NameTypeDescription
ResultKDocumentClass[]All the document classes to which user has at least read permissions / access.

Get Documents


Syntax

KDocument[]= service.getDocuments( String authenticationToken, int classId );

Usage

Use this API call to get all documents which are active in the requested Document Class (folder). It returns array of document object stored in the requested Document Class (folder). All documents which are checked out are also returned.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
classIdintDocument Class ID.

Response

NameTypeDescription
ResultKDocument []All the documents which are stored in the requested document class (folder)

Get Document Details


Syntax

KDocument = service.getDocument( String authenticationToken, int documentId );

Usage

Use this API call to retrieve details of an existing document with the given identifier.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
documentIdintDocument ID

Response

NameTypeDescription
ResultKDocumentDetails of existing document with the given identifier.

Get Document Content


Syntax

DataHandler = service.getDocumentContent( String authenticationToken, int documentId );

Usage

Use this API call to get the content of document with the given identifier. The document content is sent as an attachment.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
documentIdintDocument ID

Response

NameTypeDescription
ResultDataHandlerBinary Content of Document wrapped in a data handler or byte [].

Get Document Revision Content


Syntax

DataHandler = service.getDocumentRevisionContent( String authenticationToken, int documentId,String revisionId );

Usage

Use this API call to get the content of specific revision of the document with the given identifier. The document revision content is sent as an attachment/

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
documentIdintDocument ID
revisionIdStringRevision ID of the document

Response

NameTypeDescription
ResultDataHandlerBinary Content of Document wrapped in a data handler or byte [].

Search Documents


Syntax

KDocument[] = service.searchDocument( String authenticationToken, int classId, KIndexData[] searchCriteria );

Usage

Use this API call to get to search document in a particular document class basis the unique identifier for the class and search criteria.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
classIdintUnique Document Class Identifier
searchCrieriaKIndexData[]Search criteria

Response

NameTypeDescription
ResultKDocument[]Array of all matching documents.

Get Revision History


Syntax

KRevisionHistory[] = service.getRevisonHistory( String authenticationToken, int documentId );

Usage

Use this API call to get to revision history of particular document basis the unique identifier.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
documentIdintUnique Document Identifier.

Response

NameTypeDescription
ResultKRevisionHistory[]Array of Revision History Object for particular document.

Create Document


Syntax

boolean result = service.createDocument( String authenticationToken,String fileName,DataHandler fileContent,int classId,KIndexData[] indexData, String comments );

Usage

Use this API call to add document into a particular document class.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
fileNameStringFile Name to be uploaded.
fileContentDataHandlerBinary Content of the file.
classIdintDocument Class Identifier.
indexDataKIndexData[]Index information associated with the document.
commentsStringComments.

Response

NameTypeDescription
resultbooleanFlag indicating the result of document creation process.

Delete Document


Syntax

boolean result = service.deleteDocument( String authenticationToken,int documentId );

Usage

Use this API call to mark a document as deleted in the repository.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
documentIdintUnique Document Identifier.

Response

NameTypeDescription
resultbooleanFlag indicating the result of document deletion process.

Checkout Document


Syntax

DataHandler result = service.checkOutDocument( String authenticationToken,int documentId, String checkoutPath );

Usage

Use this API call to checkout a document from the repository.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
documentIdintUnique Document Identifier
checkoutPathStringPath where document need to be checked out.

Response

NameTypeDescription
resultDataHandlerReturns the binary content of the document to be checked out if document is not already checked out.

Check In Document


Syntax

DataHandler result = service.checkInDocument( String authenticationToken, String fileName, int documentId,boolean majorVersion, DataHandler documentContent, KIndexData[] indexData, String comments );

Usage

Use this API call to check-in a document to the repository.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
fileNameStringFile Name to be uploaded.
documentIdintDocument ID.
majorVersionbooleanFlag indicating the version is major change or minor
documentContentDataHandlerBinary content of the document to be checked in as new version.
indexDataKIndexData[]Index information associated with the document.
commentsStringComments for check-in document.

Response

NameTypeDescription
resultbooleanFlag indicating the result of document check-in process.

Cancel Document Checkout


Syntax

boolean result = service.cancelDocumentCheckOut( String authenticationToken, int documentId );

Usage

Use this API call to cancel document checkout from repository.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
documentIdintUnique identifier of the document to be checked In.

Response

NameTypeDescription
resultbooleanFlag indicating the result of document cancellation process.

Update Document Indexes


Syntax

boolean result = service.updateDocumentIndexes( String authenticationToken, int documentId,KIndexData[] indexData );

Usage

Use this API call to update indexes of a particular document.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
documentIdintUnique identifier of the document.
indexDataKIndexData[]Array of index values to be updated.

Response

NameTypeDescription
resultbooleanFlag indicating the result of update index process.

Get Document Access History


Syntax

boolean KAccessHistory[] = service.getDocumentAccessHistory( String authenticationToken, int documentId );

Usage

Use this API call to retrieve complete access history of the document.

Request Parameters

NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
documentIdintUnique identifier of the document.

Response

NameTypeDescription
resultKAccessHistory[]Array of access history of the document.

API Type Definition


Authentication Token


NameTypeDescription
authenticationTokenStringAuthentication Token associated with this session.
Note: Your client application needs to set this value in all subsequent service calls.

KDocumentClass


NameTypeDescription
classIdintUnique identifier for the document class
classNameStringName of the document class
classDescStringDescription for the document class
createdStringString representation of creation date of the document class
maximumFileSizeintMaximum size of the file in bytes to be stored in the document class
documentLimitintMaximum number of documents that can be stored in the document class

KDocument


NameTypeDescription
documentIdintUnique identifier for the document
revisionIdStringCurrent Revision Id for the document
classIdintDocument class id to which document belongs
documentTypeStringType of document
statusStringStatus of the Document => D = Deleted, A=Active , I – Inactive , H – Hidden, E – Checked Out
createdStringString representation of creation date of the document
modifiedStringString representation of modification date of the document
extensionStringExtension of the document file
hasNotebyteFlag indicating document contains notes or annotations
lastAccessedStringString representation of last accessed date of the document
accessCountintNo of times the document is accessed
lengthintLength of the head revision of the document (file size in bytes)
createdByStringString representation of expiry date of the document
expiryStringName of the user who created the document
fileNameStringName of the document file
modifiedByStringName of the user who last modified the document

KIndexData


NameTypeDescription
idintUnique Identifier of the document index
indexNameStringName of the document index
indexDescriptionStringDescription of the document index
indexTypeStringType of Index – D- Date, N – Numeric , A- Auto , S – String, L - List
operatorintComparison operator for searching
value1StringValue of the index field for the document
value2StringSecond or higher value of the index field for document

KRevisionHistory


NameTypeDescription
userNameStringName of the user who performed an action on document
userActionStringRevision Action Performed on the document
documentIdintUnique Identifier of the document
revisionIdStringRevision Id of the document on which action is performed
fileTypeStringType of document file
commentsStringComments on the document revision or action
datetimeStringString representation of the date time on which action is performed by the user

KAccessHistory


NameTypeDescription
objectIdintUnique Identifier for the document / object
objectTypeStringType of object, D – Document
actionStringAction performed on the document / object
userNameStringName of the user who performed the action
ipAddressStringIP Address from which action was performed on document / object
parametersStringAdditional parameters on the action
actionDateStringString representation of the date time on which action is performed by the user
commentsStringComments on the document revision or action