Client API

The Process development kit provides a new API which allows you to connect remotely to the Process server. This new client API manipulates the same interfaces and modules as the server API.

The client API includes all you need to integrate the features of Process Platform on any rich client-type applications.

Overview

All exchanges are done through HTTP. The client API is based on the XML and JSon flows which have been rewritten with XStream technology.

The client API is fully generated from the annotated Java Beans, provided for XStream, and an XML definition. In this way, other languages could be supported in the next releases.

Client api overview Client api overview

Available services

The following services are available:

  • Authentication
  • Directory consultation (limited to the recovering of a user)
  • Document spaces consultation:
    • List of document spaces (ILibrary);
    • List of folders (IFolder);
    • List of categories (ICategory);
    • List of files (IFile).
    • Download an attachment from a file URI (IAttachment).
  • Consulting the objects related to the process management:
    • List of applications (IProject);
    • List of process groups (ICatalog);
    • List of processes (IWorkflowContainer);
    • List of process versions (IWorkflow, IResourceDefinition);
    • List of views (IView);
    • List of documents (IWorkflowInstance, ILinkedResource).
  • Consulting the objects related to the data stockrooms:
    • List of views (IView);
    • List of tables (IResourceDefinition);
    • List of records (IStorageResource).

Currently, the API is delivered for Objective-C and Java languages (in read mode). The first use of this API is for mobile applications (iPhone or Android).

This topic provides information about how to use this client API.

Programming tasks

This section describes some developments that are possible using client API.

Summary tables of programming tasks:

Modules Programming tasks
Portal Authenticate a user and retrieve a context Get access to the modules
Directory Retrieve a user by its login Retrieve the user associations Retrieve the directory object by its protocol URI
Project Retrieve projects Retrieve a project by its protocol URI
Workflow Retrieve the definition objects Use a view controller to retrieve documents Retrieve a workflow object by its protocol URI
Library Retrieve the library structures Retrieve the files

Portal module

Authenticate a user and retrieve a context

The com.axemble.vdoc.sdk.client.platform.VDocModules is the main entry point of the client API. In order, the following code shows how to use the client API to authenticate a user.

public void portal_authenticate() {
  try {
    String serverUrl = "http://localhost:8080/vdoc";
    IContext context = VDocModules.getPortalModule().authenticate( serverUrl, "sboirol", "manager" );
  } catch( SDKClientException e ) {}
}

Get access to the modules

The following code indicates how to use the forum API. The method initialize() is used to position a certain number of parameters.

public void portal_useModules( IContext context ) {
  try {
    // retrieve the directory module
    IDirectoryModule directoryModule = VDocModules.getDirectoryModule( context );

    // retrieve the project module
    IProjectModule projectModule = VDocModules.getProjectModule( context );

    // retrieve the workflow module
    IWorkflowModule workflowModule = VDocModules.getWorkflowModule( context );

    // retrieve the library module
    ILibraryModule libraryModule = VDocModules.getLibraryModule( context );
  } catch( Exception e ) {}
}

Directory Module

Retrieve a user by its login

The following code shows you how to use the directory module to retrieve a user by its login.

public void directory_getUserByLogin( IDirectoryModule directoryModule ) {
  try {
    // retrieve a user by its login
    IUser user = directoryModule.getUserByLogin( "sboirol" );
  
    // retrieve some user's properties
    String firstName = user.getFirstName();
    String email = user.getEmail();
  } catch( Exception e ) {}
}

Retrieve the user associations

The following code shows you how to use the directory module to retrieve a user by its login.

​
public void directory_getUserAssociations( IDirectoryModule directoryModule, IUser user ) {
  try {
    // retrieve the assistant
    IUser assistant = user.getAssistant();
    
    // retrieve the manager
    IUser manager = user.getManager();
    
    // retrieve the hierarchical manager
    IUser hierarchicalManager = user.getHierarchicalManager();
  } catch( Exception e ) {}
}
public void directory_getUserAssociations( IDirectoryModule directoryModule, IUser user ) {
  try {
    // retrieve the assistant
    IUser assistant = user.getPersonalInformation().getAssistant();
    
    // retrieve the manager
    IUser manager = user.getPersonalInformation().getManager();
    
    // retrieve the hierarchical manager
    IUser hierarchicalManager = user.getPersonalInformation().getHierarchicalManager();
  } catch( Exception e ) {}
}

Retrieve the directory object by its protocol URI

The following code shows you how to retrieve an organization by its protocolURI.

public void directory_getElementByProtocolURI( IDirectoryModule directoryModule ) {
  try {
    // retrieve the default organization
    IOrganization organization = (IOrganization)directoryModule.getElementByProtocolURI( "uril://vdoc/organization/DefaultOrganization" );
  } catch( Exception e ) {}
}

Project module

Retrieve projects

The following code shows you how to retrieve available projects.

public void project_getProjects( IContext context, IProjectModule projectModule ) {
  try {
    // retrieve a project by its name
    IProject aProject = projectModule.getProjectByName( "Training" );
    
    // retrieve all available projects
    Collection<IProject> projects = projectModule.getProjects();
    for ( IProject project : projects ) {
      // ...
    }
  } catch( Exception e ) {}
}

Retrieve a project by its protocol URI

The following code shows you how to retrieve a specific project by its protocolURI.

public void project_getProjectByProtocolURI( IContext context, IProjectModule projectModule ) {
  try {
    // retrieve a project by its protocol URI
    IProject project = (IProject)projectModule.getElementByProtocolURI( "uril://vdoc/project/DefaultOrganization/Training" );
  } catch( Exception e ) {}
}

Workflow module

Retrieve the definition objects

The following code shows you how to retrieve some of the definition objects.

public void workflow_getDefinitionObjects( IContext context, IWorkflowModule workflowModule, IProject project ) {
  try {
    // retrieve a catalog
    ICatalog catalog = workflowModule.getCatalogByName( project, "Education" );
    
    // retrieve a workflow container
    IWorkflowContainer workflowContainer = workflowModule.getWorkflowContainerByName( catalog, "documentManagement" );
    
    // retrieve a workflow
    IWorkflow workflow = workflowModule.getWorkflowByName( workflowContainer, "documentManagement_1.0" );
  } catch( Exception e ) {}
}

Use a view controller to retrieve documents

The following code shows you how to retrieve documents by evaluating an existing view.

public void workflow_evaluateView( IContext context, IWorkflowModule workflowModule, IProject project, IWorkflowContainer workflowContainer ) {
  try {
    // retrieve a specific view by its name
    IView view = workflowModule.getWorkflowContainerViewByName( workflowContainer, "TODO" );
    
    // use a controller
    IViewController viewController = workflowModule.getViewControllerFromView( view );
    
    // retrieve the resources
    Collection<IResource> resources = viewController.evaluate( project );
    for ( IResource resource : resources ) {
      String creatorLogin = resource.getCreatedBy().getLogin();
      String versionNumber = (String)resource.getValue( "fldDocumentVersion" );
      String nature = (String)resource.getValue( "fldNature" );
    }
  } catch( Exception e ) {}
}

Retrieve a workflow object by its protocol URI

The following code shows you how to retrieve a specific document by its protocol URI.

public void workflow_getObjectByProtocolURI( IContext context, IWorkflowModule workflowModule ) {
  try {
    // retrieve a specific process document by its protocol URI
    IWorkflowInstance workflowInstance = (IWorkflowInstance)workflowModule.getElementByProtocolURI( "uri://vdoc/workflowInstance/1005" );
  } catch( Exception e ) {}
}

Library module

Retrieve the library structures

The following code shows you how to retrieve libraries, folders, categories.

public void library_getStructures( IContext context, ILibraryModule libraryModule ) {
  try {
    // retrieve the library
    ILibrary library = libraryModule.getLibraryByName( "Document management" );
    
    // retrieve a root folder
    IFolder rootFolder = libraryModule.getLibraryFolderByName( library, "root-folder" );
    
    // retrieve a child folder
    IFolder childFolder = libraryModule.getFolderByName( rootFolder, "child-folder" );
    
    // retrieve a root category
    ICategory rootCategory = libraryModule.getLibraryCategoryByName( library, "root-category" );
    
    // retrieve a child category
    ICategory childCategory = libraryModule.getCategoryByName( rootCategory, "child-category" );
  } catch( Exception e ) {}
}

Retrieve the files

The following code shows you how to retrieve files from either a folder or a category.

public void library_getDocuments( IContext context, ILibraryModule libraryModule, IFolder folder, ICategory category ) {
  try {
    // retrieve the files contained in a folder
    Collection<IFile> files = libraryModule.getFolderFiles( folder );
    for ( IFile file : files ) {
      // get some properties
      String fileName = file.getName();
      String fileDescription = file.getDescription();
      
      // retrieve the file attachments
      Collection<IAttachment> attachments = file.getAttachments();
      for ( IAttachment attachment : attachments ) {
        // download URL
        String uri = attachment.getUri();
      }
    }
    
    // retrieve the files associated to a category
    Collection<IFile> categoryFiles = libraryModule.getCategoryFiles( category );
    
    // ...
  } catch( Exception e ) {}
}