ID: 1773

Pre-requisites for Zoom APIs

Zoom exposes a rich set of APIs both in the form of command-line client or as JSON-based Web APIs. Before venturing into these APIs, there are a few basics that one would have to understand. This post covers the basic key parameters that are part of the Zoom APIs and some common initialization and connection mechanisms.

Through out the API documentation you will see several identifiers being referred to. Below is a definition of the commonly used entity identifiers by our APIs:

Entity Code  Entity name Type Description
fuid File Unique Id Integer Unique integer assigned to each asset independent of its name
bid Branch Id Integer Unique integer assigned to a branch. Reserved for future use.
repoId Repository Id String Unique string assigned to a Zoom repository.
pid Path Id Integer Unique integer assigned to each element of a file or folder path
rrn Repository revision number Long Unique long assigned to each write transaction in the Zoom server.  Often used to refer to an asset change set.
frn Asset Revision Number Long File or Folder Version Number is a monotonically increasing number
project Project Name String A project within a repository is a collection of assets, security ACLs, users & roles.
projectRoot  Project Root Folder String The parent folder of a project.
taskId Workflow task Id Integer Unique integer assigned to a task in a specific workflow
workId Workflow Job Id Integer Unique integer assigned to each job instantiated within the Zoom Workflow system

 

The most common entity identifiers that you will typically deal with are the tuple<fuid,bid>.  This tuple uniquely identifies an asset in the Zoom repository. Even if the asset is renamed or moved, the tuple stays the same, allowing you to track the version history of an asset.

Connecting to the Zoom Server

 

Zoom server on a successful authentication with the client, stores a cookie either on a hidden folder on the user’s home directory or in-memory. Depending upon the option, the cookie can be persistent (stored on disk) or transient (in-memory). After a command completes the transient cookie stored in-memory is wiped out.  If you intend to execute multiple commands use a persistent cookie. However if you are running commands in script on behalf of a user, you might want to use a transient cookie to avoid resetting any ongoing session of another user who may also be logged in on the same machine.

Persistent Session

 

By default Zoom creates a persistent session on authentication.  To authenticate using the command line, specify the user name & password on the command line to silently login. If the credentials are invalid the command will return an error and a non-zero process status:

zm –username <uid>  –password <pass>  <zoom-command>

For example –

zm –username joe –password joe getcredentials
zm –username joe –password joe version –all

 

Authentication using the Java API

Using the dialog launcher API, the Zoom Java based login form will automatically popup to authenticate the user. No additional code is needed for e.g.:

ProcessLauncher.launchDialog(ScreensEnum.IMPORT, server, project,                                                        branch, remoteDestFolder, localFilesToImport);

For a more low-level API, you can use the methods in the class com.zoom.admin.client.ProjectOptions to set the user name and password prior to invoking the low-level command APIs:

ProjectOptions po = com.zoom.admin.client.ProjectOption.getInstance();
po. setUsername(“joe”);
po. setPassword(“joe”);

// Invoke the check-in command directly without any GUI

CommitCommand c = new CommitCommand(app,nonrecursive,depth,
                                               logmsg,logmsgfile,addcommit,
                                              changelist,keeplock,taskid,
                                              thumbnailfile,metainfo,infiles);

Transient Session

(Will be updated shortly)

 

Zoom supports sending JSON requests via AJAX to the following URL on the Zoom Admin Server:

<wbm_server:wbm_port>/internal?zm_username=<zm_username>&zm_cookie=<zm_cookie>

wbm_server|port refer to the Zoom Web Admin Server (webmin) host name and TCP port (defaults to 8443).

In order for the webmin server to authenticate & authorize the user the following parameters must be passed via the URL query parameters or in the body of the Http POST requests:

zm_cookie
zm_username

For example –

POST /internal?zm_username=rahul&zm_cookie=21-750c34331b591bffee5ee7a2d5759f0d93bb157b

 

The user-name and cookie can be obtained by pulling the information using the “zm getcredentials” scriptable command or using the Java class GetcredentialsCommand.

The output of “zm getcredentials” command looks like this:

[joe@green ~]$zm –username joe –password joe -s http://localhost:8880 getcredentials
zm_server: http://192.168.0.4:8880
zm_repo_id: zoom-server-fe706ca57180507d76d3d98c3e1223340f50b314
zm_cookie: 2-01b027d78a2e3c099eff14fdf83fba166d6d5efa
zm_username: joe
wbm_server: http://192.168.0.4:6443
…………..

 

We can obtain URL from “wbm_server” and the cookie from “zm_cookie”. The Zoom server performs the authorization based on the roles associated with the user’s credentials.

 

Use HTTP POST to submit login credentials to the Preview Server login URL. After a successful authentication, Preview Server will set a session cookie (name: JSESSIONID) that needs to be sent with subsequent http request to the Preview Server. In addition a JSON response will be returned to indicate if authentication succeeded.

POST url:

http://<preview-server-host>:8873/review/jsp/login/login.jsp

Form Data to POST:

zm_password:”<password>”
zm_username:”<user-login-id>”
zm_server:”http://<host>:8880″
zm_repo_id:”<repoId>”

On success expect to receive the following:

{
 “authSuccess”:true,
 “role”:”webclient”,
 “zm_username”:”rahul”
}

Now you are ready to use the Preview Server API.

 

As mentioned earlier the “zm getcredentials” can fetch the current logged in user’s credentials including the persistent cookie set by the Zoom authentication module.

 

The “zm_cookie”  can be passed to any Zoom command or the Webmin APIs to authenticate a user. The cookie is stored in an authentication database on the user’s “.zm” folder under the home directory.