Document Management System - Documentation

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.

Index	Method	Parameters	Response Type
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	createDocumentWithAttachments	authToken fileName fileBytes[] classId documentIndexes[] expiryDate comments attachments[]	CreateDocumentResponse
14	deleteDocument	authToken documentId	DeleteDocumentResponse
15	checkOutDocument	authToken documentId	CheckOutDocumentResponse
16	checkInDocument	authToken fileName fileBytes[] documentId majorVersion documentIndexes[] comments	CheckInDocumentResponse
17	cancelCheckout	authToken documentId	CancelCheckoutResponse
18	updateIndexes	authToken documentId documentIndexes[]	UpdateIndexesResponse
19	getDocumentRevisionHistory	authToken documentId	DocumentRevisionHistoryResponse
20	getDocumentAccessHistory	authToken documentId	DocumentAccessHistoryResponse
21	getWorkflowTemplates	authToken	WorkflowTemplatesResponse
22	startWorkflow	authToken fileName fileBytes[] classId templateId documentIndexes[]	StartWorkflowResponse
23	startWorkflowWithAttachments	authToken fileName fileBytes[] classId templateId documentIndexes[] attachments[]	StartWorkflowResponse
24	getWorkflowStatus	authToken templateId documentIndexes[]	WorkflowStatusResponse

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.

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.
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.
Use the available API calls to accomplish a desired integration objective. You session will not expire automatically.
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

Name	Type	Required	Description
username	string	Y	User name for KRYSTAL DMS account
password	string	Y	Password for the specified user
domainName	string	Y	Domain name for sign on

Response

Name

Type

Required

Description

SignOnResponse

Property	Type	Required	Description
errorCode	int	Y
errorMessage	string	Y
authToken	string	Y	Authentication 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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method

Response

Name

Type

Required

Description

SignOutResponse

Property	Type	Required	Description
errorCode	int	Y
errorMessage	string	Y
loggedOut	boolean	Y	Flag 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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method

Response

Name

Type

Required

Description

DocumentClassesResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
availableClasses	KDocumentClass[]	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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
classId	int	Y

Response

Name

Type

Required

Description

DocumentsResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
documents	KDocument[]	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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
documentId	int	Y
revisionId	string	Y

Response

Name

Type

Required

Description

DocumentDetailsResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
documentDetails	KDocument	Y

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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
documentId	int	Y

Response

Name

Type

Required

Description

DocumentResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
documentFile	byte[]	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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
documentId	int	Y
revisionId	string	Y

Response

Name

Type

Required

Description

DocumentContentResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
documentContent	string	Y

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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
documentId	int	Y
revisionId	string	Y

Response

Name

Type

Required

Description

DocumentRevisionResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
documentRevisionFile	byte[]	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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
documentId	int	Y
revisionId	string	Y

Response

Name

Type

Required

Description

DocumentIndexesResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
indexes	KDocumentIndex[]	Y

10. Search Documents

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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
classId	int	Y
searchText	string	Y

Response

Name

Type

Required

Description

SearchDocumentsResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
documents	KDocument[]	Y

11. Search Documents By Indexes

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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
classId	int	Y
documentIndexes	KDocumentIndex[]	Y

Response

Name

Type

Required

Description

SearchDocumentsResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
documents	KDocument[]	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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
fileName	string	Y	File name of the document
fileByte	byte[]	Y	Actual file content in byte format
classId	int	Y	Document Class Identifier
documentIndexes	KDocumentIndex[]	Y	Associated Document Indexes
expiryDate	string	N	Document Expiry Date in dd-MMM-yyyy format (Example : 27-Oct-2017)
comments	string	N	comments / notes for new document

Response

Name

Type

Required

Description

CreateDocumentResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
documentCreated	boolean	Y

13. Create Document With Attachments

Syntax

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

Usage

To add a new document / create document into the document repository along with attachment (additional files) 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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
fileName	string	Y	File name of the document
fileByte	byte[]	Y	Actual file content in byte format
classId	int	Y	Document Class Identifier
documentIndexes	KDocumentIndex[]	Y	Associated Document Indexes
expiryDate	string	N	Document Expiry Date in dd-MMM-yyyy format (Example : 27-Oct-2017)
comments	string	N	comments / notes for new document
attachments	KAttachment[]	Y	Attached Document / Additional Supporting Files

Response

Name

Type

Required

Description

CreateDocumentResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
documentCreated	boolean	Y

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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
documentId	int	Y	Document Identifier

Response

Name

Type

Required

Description

DeleteDocumentResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
documentDeleted	boolean	Y

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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
documentId	int	Y	Document Identifier

Response

Name

Type

Required

Description

CheckOutDocumentResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
checkOutDocument	byte[]	Y

16. Check-In Document

Syntax

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

Usage

Request Parameters

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
fileName	string	Y	File name of the document
fileByte	byte[]	Y	Actual file content in byte format
documentId	int	Y	Document Identifier
majorVersion	boolean	Y	Flag indicating major version for document
documentIndexes	KDocumentIndex[]	Y	Associated Document Indexes
comments	string	Y	comments / notes for new document

Response

Name

Type

Required

Description

CheckInDocumentResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
checkIns	boolean	Y

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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
documentId	int	Y	Document Identifier

Response

Name

Type

Required

Description

CancelCheckoutResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
cancelCheckout	boolean	Y

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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
documentId	int	Y	Document Identifier
documentIndexes	KDocumentIndex[]	Y	New Indexes associated with Document

Response

Name

Type

Required

Description

UpdateIndexesResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
indexUpdated	boolean	Y

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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
documentId	int	Y	Document Identifier

Response

Name

Type

Required

Description

DocumentRevisionHistoryResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
revisionHistory	KRevisionHistory[]	Y

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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
documentId	int	Y	Document Identifier

Response

Name

Type

Required

Description

DocumentAccessHistoryResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
accessHistory	KAccessHistory[]	Y

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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method

Response

Name

Type

Required

Description

WorkflowTemplatesResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
availableWorkflowTemplates	KWorkflowTemplate[]	Y

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

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
fileName	string	Y	Filename
fileBytes	byte[]	Y
classId	int	Y
templateId	string	Y
documentIndexes	KDocumentIndex[]	Y	Indexes associated with Workflow Case

Response

Name

Type

Required

Description

StartWorkflowResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
workflowStarted	boolean	Y

23. Start Workflow Case With Attachments

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 along with attachments (additional files).

Request Parameters

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
fileName	string	Y	Filename
fileBytes	byte[]	Y
classId	int	Y
templateId	string	Y	Workflow template ID
documentIndexes	KDocumentIndex[]	Y	Indexes associated with Workflow Case
attachments	KAttachment[]	Y	Attached Document / Additional Supporting Files

Response

Name

Type

Required

Description

StartWorkflowResponse

Property	Type	Required
errorCode	int	Y
errorMessage	string	Y
workflowStarted	boolean	Y

24. Get Workflow Status

Syntax

WorkflowStatusResponse response = service.getWorkflowStatus(string authToken, string templateId, KDocumentIndex documentIndexes[]);

Usage

This API method call will provide the status of workflow case with given unique reference number.

Request Parameters

Name	Type	Required	Description
authToken	string	Y	Authentication Token received from SignOn method
templateId	string	Y	Workflow template ID
documentIndexes	KDocumentIndex[]	Y	Unique identification on basis of index value associated with workflow case.

Response

Name

Type

Required

Description

WorkflowStatusResponse

Property	Type	Required	Description
errorCode	int	Y
errorMessage	string	Y
wfStatus	string	Y	Completed or In-progress
wfAssignee	string	Y	Assignee name if the workflow is in progress
wfActivity	string	Y	Current activity name if the workflow is in progress

API Type Definition

KDocumentClass

Name	Type	Description
classId	int	Unique identifier for the document class
className	String	Name of the document class
classDescription	String	Description for the document class
created	String	String representation of creation date of the document class
maximumFileSize	int	Maximum size of the file in bytes to be stored in the document class
documentLimit	int	Maximum number of documents that can be stored in the document class
documentIndexes	KDocumentIndex[]	Indexes associated with a document class

KDocument

Name	Type	Description
documentId	int	Unique identifier for the document
revisionId	String	Current Revision Id for the document
classId	int	Document class id to which document belongs
documentType	String	Type of document
status	String	Status of the Document => D = Deleted, A=Active , I – Inactive , H – Hidden, E – Checked Out
created	String	String representation of creation date of the document
modified	String	String representation of modification date of the document
extension	String	Extension of the document file
hasNote	byte	Flag indicating document contains notes or annotations
lastAccessed	String	String representation of last accessed date of the document
accessCount	int	No of times the document is accessed
length	int	Length of the head revision of the document (file size in bytes)
createdBy	String	String representation of expiry date of the document
expiry	String	Name of the user who created the document
fileName	String	Name of the document file
modifiedBy	String	Name of the user who last modified the document
score	Double	Search score of the document
indexes	KDocumentIndex[]	Indexes associated with a document

KDocumentIndex

Name	Type	Description
id	int	Unique Identifier of the document index
indexName	String	Name of the document index
indexDescription	String	Description of the document index
indexType	String	Type of Index – D- Date, N – Numeric , A- Auto , S – String, L - List
operator	int	Comparison operator for searching
value1	String	Value of the index field for the document
value2	String	Second or higher value of the index field for document
mandatory	Boolean	Flag indicating if the index is mandatory
unique	Boolean	Flag indicating if the index value must be unqiue

KAttachment

Name	Type	Description
fileName	String	Name of the attachment file
fileBytes	byte[]	Content of attachment file
title	String	Title for the attachment
keywords	String	Keywords for attachment

KRevisionHistory

Name	Type	Description
userName	String	Name of the user who performed an action on document
userAction	String	Revision Action Performed on the document
documentId	int	Unique Identifier of the document
revisionId	String	Revision Id of the document on which action is performed
fileType	String	Type of document file
comments	String	Comments on the document revision or action
datetime	String	String representation of the date time on which action is performed by the user

KAccessHistory

Name	Type	Description
objectId	int	Unique Identifier for the document / object
objectType	String	Type of object, D – Document
action	String	Action performed on the document / object
userName	String	Name of the user who performed the action
ipAddress	String	IP Address from which action was performed on document / object
parameters	String	Additional parameters on the action
actionDate	String	String representation of the date time on which action is performed by the user
comments	String	Comments on the document revision or action

KWorkflowTemplate

Name	Type	Description
id	int	Unique Identifier for the workflow template
active	String	Flag indicating active status of workflow template
manual	String	Flag indicating manual override
effective	String	Date time string since when the workflow is effective
lastChanged	String	Date time string when template was last changed
templateDefinitionId	String	System generated id for workflow template
called	String	Not used
templateId	String	Unique ID of the workflow template
name	String	Name of the workflow template
data	String	Workflow template business logic
tableNo	int	Database table used with workflow template
classId	int	Document class ID linked with the workflow template
reportingRole	int	ID of the role defined as reporting manager