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 - Premium 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.

Index Method Parameters Response Type Description
1 signOn username
password
domainName
SignOnResponse
2 signOut authToken SignOutResponse
3 getDocumentClasses authToken DocumentClassesResponse
4 getDocuments authToken
classId
DocumentsResponse
5 getDocumentDetails authToken
documentId
revisionId
DocumentDetailsResponse
6 getDocument authToken
documentId
DocumentResponse
7 getDocumentContent authToken
documentId
revisionId
DocumentContentResponse
8 getDocumentRevision authToken
documentId
revisionId
DocumentRevisionResponse
9 getDocumentIndexes authToken
documentId
revisionId
DocumentIndexesResponse
10 searchDocuments authToken
classId
searchText
SearchDocumentsResponse
11 searchDocumentsByIndexes authToken
classId
documentIndexes[]
SearchDocumentsResponse
12 createDocument authToken
fileName
fileBytes[]
classId
documentIndexes[]
expiryDate
comments
CreateDocumentResponse
13 deleteDocument authToken
documentId
DeleteDocumentResponse
14 checkOutDocument authToken
documentId
CheckOutDocumentResponse
15 checkInDocument authToken
fileName
fileBytes[]
documentId
majorVersion
documentIndexes[]
comments
CheckInDocumentResponse
16 cancelCheckout authToken
documentId
CancelCheckoutResponse
17 updateIndexes authToken
documentId
documentIndexes[]
UpdateIndexesResponse
18 getDocumentRevisionHistory authToken
documentId
DocumentRevisionHistoryResponse
19 getDocumentAccessHistory authToken
documentId
DocumentAccessHistoryResponse
20 getWorkflowTemplates authToken WorkflowTemplatesResponse
21 startWorkflow authToken
fileName
fileBytes[]
classId
templateId
documentIndexes[]
StartWorkflowResponse

Web Services API URL


Once you have installed KRYSTAL DMS – Premium Edition version 2017 Release 4 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(s)://<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. You session will not expire automatically.

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


KRYSTAL DMS - Web Services API calls


1. Sign On


Syntax

SignOnResponse response = 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 do not expire automatically. 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

NameTypeRequiredDescription
usernamestringYUser name for KRYSTAL DMS account
passwordstringYPassword for the specified user
domainNamestringYDomain name for sign on

Response

NameTypeRequiredDescription
 
SignOnResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
authTokenstringYAuthentication Token or Session Identifier (SID)
   

2. Sign Out


Syntax

SignOutResponse response = service.signout( String authToken );

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

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method

Response

NameTypeRequiredDescription
 
SignOutResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
loggedOutbooleanYFlag indicating the result of the operation
   

3. Get Document Classes


Syntax

DocumentClassesResponse response = service.getDocumentClasses( String authToken );

Usage

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

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method

Response

NameTypeRequiredDescription
 
DocumentClassesResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
availableClassesKDocumentClass[]Y
   

4. Get Documents


Syntax

DocumentsResponse response = service.getDocuments(String authToken, 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

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
classIdintY 

Response

NameTypeRequiredDescription
 
DocumentsResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
documentsKDocument[]Y
   

5. Get Document Details


Syntax

DocumentDetailsResponse response = service.getDocumentDetails( String authToken, int documentId ,string revisionId );

Usage

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

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
documentIdintY 
revisionIdstringY 

Response

NameTypeRequiredDescription
 
DocumentDetailsResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
documentDetailsKDocumentY
   

6. Get Document


Syntax

DocumentResponse response = service.getDocument( String authToken, int documentId );

Usage

Use this API call to get the document (file) with the given identifier.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
documentIdintY 

Response

NameTypeRequiredDescription
 
DocumentResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
documentFilebyte[]Y
   

7. Get Document Content


Syntax

DocumentContentResponse response = service.getDocumentContent( String authToken, int documentId, string revisionId);

Usage

Use this API call to get the content (extracted text) of the document with the given identifier.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
documentIdintY 
revisionIdstringY 

Response

NameTypeRequiredDescription
 
DocumentContentResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
documentContentstringY
   

8. Get Document Revision


Syntax

DocumentRevisionResponse response = service.getDocumentRevision( String authToken, int documentId, string revisionId);

Usage

Use this API call to get the specific version of the document (file) with the given identifier.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
documentIdintY 
revisionIdstringY 

Response

NameTypeRequiredDescription
 
DocumentRevisionResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
documentRevisionFilebyte[]Y
   

9. Get Document Indexes


Syntax

DocumentIndexesResponse response = service.getDocumentIndexes( String authToken, int documentId, string revisionId);

Usage

Use this API call to get the index information associated with the document.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
documentIdintY 
revisionIdstringY 

Response

NameTypeRequiredDescription
 
DocumentIndexesResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
indexesKDocumentIndex[]Y
   


Syntax

SearchDocumentsResponse response = service.searchDocuments( String authToken, int classId, string searchText);

Usage

Documents in the repository can be searched using this method for a given document class. All indexes and content of the document will be searched during this operation and all matching and active documents are returned using this API call.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
classIdintY 
searchTextstringY 

Response

NameTypeRequiredDescription
 
SearchDocumentsResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
documentsKDocument[]Y
   


Syntax

SearchDocumentsResponse response = service.searchDocumentsByIndexes( String authToken, int classId, KDocumentIndex[] documentIndexes);

Usage

To perform advance search on documents in the repository this method can be used for a given document class.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
classIdintY 
documentIndexesKDocumentIndex[]Y 

Response

NameTypeRequiredDescription
 
SearchDocumentsResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
documentsKDocument[]Y
   

12. Create Document


Syntax

CreateDocumentResponse response = service.createDocument(string authToken, string fileName , byte[] fileBytes,int classId , KDocumentIndex[] documentIndexes, string comments);

Usage

To add a new document / create document into the document repository this method can be used. The document will be created in a specified document class only if user has create permissions on that document class.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
fileNamestringYFile name of the document
fileBytebyte[]YActual file content in byte format
classIdintYDocument Class Identifier
documentIndexesKDocumentIndex[]YAssociated Document Indexes
expiryDatestringNDocument Expiry Date in dd-MMM-yyyy format (Example : 27-Oct-2017)
commentsstringNcomments / notes for new document

Response

NameTypeRequiredDescription
 
CreateDocumentResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
documentCreatedbooleanY
   

13. Delete Document


Syntax

DeleteDocumentResponse response = service.deleteDocument(string authToken, int documentId);

Usage

This API call will allow user to delete a document if user has delete permission on the document class in which document is stored. Document will not be deleted if it is aleady checked out.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
documentIdintYDocument Identifier

Response

NameTypeRequiredDescription
 
DeleteDocumentResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
documentDeletedbooleanY
   

14. Checkout Document


Syntax

CheckOutDocumentResponse response = service.deleteDocument(string authToken, int documentId);

Usage

To checkout a document for editing and locking the document, user can use this API call.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
documentIdintYDocument Identifier

Response

NameTypeRequiredDescription
 
CheckOutDocumentResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
checkOutDocumentbyte[]Y
   

15. Check-In Document


Syntax

CheckInDocumentResponse response = service.createDocument(string authToken, string fileName, byte[] fileBytes, int documentId, boolean majorVersion KDocumentIndex[] documentIndexes, string comments);

Usage

To add a new document / create document into the document repository this method can be used. The document will be created in a specified document class only if user has create permissions on that document class.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
fileNamestringYFile name of the document
fileBytebyte[]YActual file content in byte format
documentIdintYDocument Identifier
majorVersionbooleanYFlag indicating major version for document
documentIndexesKDocumentIndex[]YAssociated Document Indexes
commentsstringYcomments / notes for new document

Response

NameTypeRequiredDescription
 
CheckInDocumentResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
checkInsbooleanY
   

16. Cancel Document Checkout


Syntax

CancelCheckoutResponse response = service.cancelCheckout(string authToken, int documentId);

Usage

This API call will allow user to cancel checkout of a document if user has checked out the document.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
documentIdintYDocument Identifier

Response

NameTypeRequiredDescription
 
CancelCheckoutResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
cancelCheckoutbooleanY
   

17. Update Document Indexes


Syntax

UpdateIndexesResponse response = service.updateIndexes(string authToken, int documentId, KDocumentIndex[] documentIndexes);

Usage

This API call will allow user to update indexes associated with given document.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
documentIdintYDocument Identifier
documentIndexesKDocumentIndex[]YNew Indexes associated with Document

Response

NameTypeRequiredDescription
 
UpdateIndexesResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
indexUpdatedbooleanY
   

18. Document Revision History


Syntax

DocumentRevisionHistoryResponse response = service.getDocumentRevisionHistory(string authToken, int documentId);

Usage

To get complete revision history of document this method should be used.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
documentIdintYDocument Identifier

Response

NameTypeRequiredDescription
 
DocumentRevisionHistoryResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
revisionHistoryKRevisionHistory[]Y
   

19. Document Access History


Syntax

DocumentAccessHistoryResponse response = service.getDocumentAccessHistory(string authToken, int documentId);

Usage

To get complete access history of document this method should be used.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
documentIdintYDocument Identifier

Response

NameTypeRequiredDescription
 
DocumentAccessHistoryResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
accessHistoryKAccessHistory[]Y
   

20. Get Workflow Templates


Syntax

WorkflowTemplatesResponse response = service.getWorkflowTemplates(string authToken);

Usage

This API method call will return all workflow templates to which the user has create , access permissions.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method

Response

NameTypeRequiredDescription
 
WorkflowTemplatesResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
availableWorkflowTemplatesKWorkflowTemplate[]Y
   

21. Start Workflow Case


Syntax

StartWorkflowResponse response = service.startWorkflow(string authToken, string fileName,byte[] fileBytes,int classId,string templateId, KDocumentIndex documentIndexes[]);

Usage

This API method call will start the workflow case with given document file for choosen workflow template.

Request Parameters

NameTypeRequiredDescription
authTokenstringYAuthentication Token received from SignOn method
fileNamestringYFilename
fileBytesbyte[]Y
classIdintY
templateIdstringY
documentIndexesKDocumentIndex[]YIndexes associated with Workflow Case

Response

NameTypeRequiredDescription
 
StartWorkflowResponse
PropertyTypeRequiredDescription
errorCodeintY
errorMessagestringY
workflowStartedbooleanY
   

API Type Definition


KDocumentClass


NameTypeDescription
classIdintUnique identifier for the document class
classNameStringName of the document class
classDescriptionStringDescription 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
documentIndexesKDocumentIndex[]Indexes associated with a 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
scoreDoubleSearch score of the document
indexesKDocumentIndex[]Indexes associated with a document

KDocumentIndex


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
mandatoryBooleanFlag indicating if the index is mandatory
uniqueBooleanFlag indicating if the index value must be unqiue

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

KWorkflowTemplate


NameTypeDescription
idintUnique Identifier for the workflow template
activeStringFlag indicating active status of workflow template
manualStringFlag indicating manual override
effectiveStringDate time string since when the workflow is effective
lastChangedStringDate time string when template was last changed
templateDefinitionIdStringSystem generated id for workflow template
calledStringNot used
templateIdStringUnique ID of the workflow template
nameStringName of the workflow template
dataStringWorkflow template business logic
tableNointDatabase table used with workflow template
classIdintDocument class ID linked with the workflow template
reportingRoleintID of the role defined as reporting manager