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.
Entity Definitions
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.
Zoom Authentication & Authorization
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 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)
Connect to Zoom Admin Server
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 MAM 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 –
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:
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.
Connecting to Zoom Preview Server
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:
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.
Get Credentials
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.
Authentication Token
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.