WebPal Resources for Editors, Admins, Collaborators and Coders

Previous: Continuous Integration: Introduction Next: Programming API

The WebPal API

Introduction

WebPal provides three different ways to access the underlying functions of the WebPal Document Manager: 

  • An XML web service API,
    • at https://MYSERVER.webpal.net/webservice/xml-service.php
  • RESTful WebDAV interface,
    • at https://MYSERVER.webpal.net/webdav
  • WebPal API PHP library classes

Requests

The input to all methods is XML text provided to the service in the body of an HTTP POST. The output is “text/xml” except for file downloads which returns the contents of a file with the appropriate mime type.

The input parameters can be passed either as attribute values of the root element, or as text or CDATA sections within elements whose tags are the parameter names.

For example, you can move and existing file with this request:

<?xml version="1.0" encoding="UTF-8"?><request command="move"
    path="/dir/test1/file1"
    dir="/dir/testb1/testc1"
    sessionID="bd7d8af5ab41407dac6666874c74c3ab"/>

Alternatively, you can upload a new file like so:

<?xml version="1.0" encoding="UTF-8"?><request command="upload"
    sessionID="bd7d8af5ab41407dac6666874c74c3ab"><dir><![CDATA[/dir/test1}}></dir><name><![CDATA[file1afddf}}></name><title><![CDATA[a document title}}></title><content><![CDATA[some text}}></content></request>

In the latter example, the command and session id are passed as attributes in the “request” element whereas the “dir”, “title”, and “content” are passed inside elements. The API method is always identified by the value of the parameter called “command”.

Responses

An example of the response XML is

<?xml version="1.0" encoding="UTF-8"?><response status="ok"><result><path>/dir/test1/file1afddf</path></result></response>

The root element is tagged with “response”. The status attribute will be “ok” on success, “fail” if an error occurs. The return values are enclosed in the element tagged with “result”.

If an error occurs, the error message will be in an “error” element in the response, for example:

<?xml version="1.0" encoding="UTF-8"?><response status="fail"><error>Bad path /dir/testb1</error></response>

Authentication

In order to provide secure access, a client must first log into the web service. This is currently done through the “login” method, which takes a username and password as parameters. The method returns a session id which must be passed in as an argument to all subsequent calls.

There are two ways you can pass the session id to the service

  1. as the sessionID attribute of the Request element in the xml of the request
  2. as a HTTP header: X_DM_SESSION_ID

Paths and IDs

The name of the XML attribute that identifies a file or folder is path. This can be either

  1. The internal id of the file or folder in the form of a large integer
  2. If the pretty attribute is true (yes, true, 1), the pretty path of the document or folder relative to the logged in user’s shares.

Booleans

Any boolean attribute is considered to be true if the value is a case insensitive match to “1”, “yes”, or “true”. It is considered false otherwise. The default value depends on the command.

Include Meta Data

Many of the file commands accept the boolean parameter “includeMetaData” which causes the result to include assorted file meta data.

Paging and Sort

Many of the commands that list WebPal items such as documents and folders or users accept parameters to control the position in the result set and number of items returned, analogous to the MySQL limit parameters:

  • n or results - the number of items to return, default all records
  • offset - the start position in the result set, default 0
  • sort - a comma separated list of attribute names; the attribute name can be followed by a ‘:asc’ or ‘:desc’ to specify sort order
  • type - if the kind of object being retrieved has a type attribute, this can be used to choose one of those types

Commands

append

Append text to a document

copy

Copy a document or folder to another folder

createFolder

Create a folder. Note that path can contain / meaning create all folders in the the path

createGroupShare

Create a share to a group without sending an email

createSystemShare

Create a system share for a user identified by either login or user id. Logged in user must be admin if the requested user is not the logged in user.

csv.appendRow

Add a row to the end of a csv file. Assumes that the csv file has column names in the first row. The row to add is specified as a set of form elements having a column name and a value attribute.

delete

Delete a document or folder.

download

Stream the contents of a document to the output. Optionally watermark or stamp a PDF.

exists

If optional name is supplied, check if that subpath exists with the object if the object is a directory

fetchUserProfile

Retrieve the user profile for the logged in user or an arbitrary user if admin.

fileCount

Compute counts of the files and directories in a subtree

fileInfo

Return file metadata for the specified file(s). May return more than one result for shares of the same name.

generateThumbnails

Regenerate thumbnail, then dump the contents of the thumbnail to the output

getPrettyName

Returns the pretty name for a path

hasThumbnail

Check if a document has a thumbnail

icon

Download the contents of the document's icon. If name is given, the content disposition has that file name

index

Add the file to the full text index.

introspect

Return all api commands with whatever documentation is available.

listActivity

Return a portion of the activity log

listDirectory

List the directory contents. If the path is "/" and pretty is true, list the user's root shares and ignore the other parameters.

listGroups

Return all groups @response

listRootContents

List the merged contents of all of the root drives

listRoots

Return the root drives for the logged in user.

listUsers

Query the WebPal users.

login

Login with a user and password supplied in the args.

logout

Log out from the session, clearing the cookie.

lookupGroup

Check if the named group exists, return information about the group if it exists.

lookupPretty

Returns the document id corresponding to the given pretty name

metaData

Return the meta data for a file or folder

move

Move a document or folder to another folder

noMatchingUser

Check if an email or login exists in WebPal. One login or email must be provided. If both are provided, the email is checked.

pdf

Download the contents of a document pdf to the output

permissions

Return the integer representing the permissions for the logged in user or the named user for a document or folder. Only an admin user can check the permission for other users.

ping

Simply return 'ok', keeps session alive or fails if session expired.

recentActivity

Return recent activity display for the logged in user. This is a list of file records that have changed or been added or deleted.

rename

Rename a document or folder

resetPassword

Reset a password and send an email to the email address if the email is known and unique.

setMetaData

Change meta data fields for a document or folder

share

Share one or more documents or folders with one or more users

thumbnail

Return the contents of a thumbnail

thumbnailOrImage

Download the contents of a document thumbnail to the output or if an image and no thumbnail, the image

toPDF

Generate PDFs for HTML downloaded from the specified URLs or for uploaded files. If no destination or path are specified, download the first PDF using the optional fileName

updateUserProfile

Update the user profile for the logged in user or an arbitrary user if admin. Keys and values are specified as set elements of the request element.

upload

Upload a document to WebPal

userAddGroups

Add a user to some groups.

userExists

Check if an email or login exists in WebPal. Exactly one login or email must be provided.

userFile

Returns the path name that would be used by the named user.

userInfo

Return information about a user.

userRemoveGroups

Remove a user from some groups.

userShares

Display the shares or the shared files (if result-type is files) for a user Select the user by id or by login. If WebPal is configured with ALLOW_EMAIL_AS_ALT_LOGIN, the login may be an email address and the user is looked up by email address. Only admin can look at other users. If result_type is files also accept standard paging parameters.

viewerLink

Return file info for the identified file, including a viewer link.

append

Append text to a document

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
content optional string

The text to append
Return

The response contains a 'result" element with a single "path" element containing the meta data for the document.

Example Request
<?xml version="1.0"?>
<request command="append" pretty="yes" path="/System Drive/report2.csv" content="x,y,z&#10;q,r,s&#10;"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="report2.csv" path="695017313154591029" title="" comments="" draft="0" review="" finalDraft="0" permissions="8191" user="1" modified="1,2020-06-08 16:56:08" isdirectory="No" size="48" prettyName="/System Drive/report2.csv" iconPath="img/files/file.gif" mime-type="text/csv" version="92" parent="439541447604990017">695017313154591029</path>
  </result>
</response>

copy

Copy a document or folder to another folder

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
dir optional string

Destination folder as an id or path depending on value of pretty
overwrite optional boolean

If true, allow the move to overwrite a file of the same name in the destination
renameIfConflict optional boolean

Rename the copied file if there is a conflict
incr optional boolean

Generate a name by appending a number if there is a conflict
ifExists optional boolean

if true, don't return an error if source doesn't exist
Return

A result element containing - a count element containing the number of documents and folders copied - a path element with text content being the id of the copied object

Example Request
<?xml version="1.0"?>
<request command="copy" path="657080270669470254" dir="945653219145194140" renameIfConflict="true"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <count>1</count>
    <path>117090499569622314</path>
  </result>
</response>

createFolder

Create a folder. Note that path can contain / meaning create all folders in the the path

Parameter Type Description
sessionID optional string

Provide the session id
name optional string

The name of the folder be created
dir optional string

id or symbolic path..
pretty optional boolean

If true, interpret the dir as a symbolic path
includeMetaData optional boolean

If true, add metadata for the document or folder to the path elements
ifNotExists optional boolean

If true, do not return an error status if the folder exists
Return

A response element containing a path element for the new folder.

Example Request
<?xml version="1.0"?>
<request command="createFolder" includeMetaData="true" pretty="true" dir="/sites" name="new-folder"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="new-folder" path="724663140926469594" title="" comments="" draft="" review="" finalDraft="" permissions="8191" user="0" modified="" isdirectory="Yes" size="4096" prettyName="/sites/new-folder" iconPath="img/files/dir.gif" mime-type="" parent="124561914478016686">724663140926469594</path>
  </result>
</response>

createGroupShare

Create a share to a group without sending an email

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
group optional string

The name of the group to which the file or folder is being shared
permissions optional integer

default view and download
expiry optional date

Expiration date and time for the share YYYY-MM-DD HH:MM:SS
Return

A result element containin a share element with attributes describing the share

Example Request
<?xml version="1.0"?>
<request command="createGroupShare" pretty="true" path="/System Drive/test/test-20200616144706" group="share-test"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <share id="628" name="" from="1" to="" group="2" version="" permissions="529" path="/System Drive/test/test-20200616144706" file_id="103717787211901174" type="Email" expiry="" expiry_formatted="" date_recorded="2020-06-16 10:47:06"/>
  </result>
</response>

createSystemShare

Create a system share for a user identified by either login or user id. Logged in user must be admin if the requested user is not the logged in user.

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
name optional string

The name for the system share
login optional string

The login identifying the user
user_id optional string

The user id identifying the user.
permissions optional integer

The permissions for the share
create optional boolean

If true and the path doesn't exist, create the path
Return

The response contains a result element that contains a share element containing details of the share.

Example Request
<?xml version="1.0"?>
<request command="createSystemShare" user_id="377" path="/System Drive/test" pretty="true" name="My New Drive"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <share id="630" name="My New Drive" from="" to="377" group="" version="" permissions="8191" path="/System Drive/test" file_id="151037544713428608" type="System" expiry="" expiry_formatted="" date_recorded="2020-06-16 11:10:30"/>
  </result>
</response>

csv.appendRow

Add a row to the end of a csv file. Assumes that the csv file has column names in the first row. The row to add is specified as a set of form elements having a column name and a value attribute.

Parameter Type Description
sessionID optional string

Provide the session id
cvs-file optional string

id or symbolic path..
pretty optional boolean

If true, interpret the cvs-file as a symbolic path
Return

A result element containing a single path element that includes the metadata of the updated file.

Example Request
<?xml version="1.0"?>
<request command="csv.appendRow" csv-file="115393717311806343">
  <form name="co1" value="2020-07-03 18:33:08"/>
  <form name="col2" value="b"/>
  <form name="col3" value="c"/>
</request>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="file.csv" path="115393717311806343" title="" comments="" draft="0" review="" finalDraft="0" permissions="8191" user="458" modified="458,2020-07-03 14:26:05" isdirectory="No" size="57" prettyName="/user1/file.csv" iconPath="img/files/file.gif" mime-type="text/plain" version="4" parent="834318401130303479">115393717311806343</path>
  </result>
</response>

delete

Delete a document or folder.

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
ifExists optional optional

No error if the document or folder does not exist
Return

A result element containin the count of the number of documents and folders deleted.

Example Request
<?xml version="1.0"?>
<request command="delete" path="945653219145194140"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>12</result>
</response>

download

Stream the contents of a document to the output. Optionally watermark or stamp a PDF.

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
version optional integer

The desired version of the document
disposition optional string

Either inline or attachment.
resize optional string

option default none; An ImageMagick dimensions specification e.g. 30x40 as width and height.
watermark optional string

The text of the watermark
watermark-position optional string

One of top, left, bottom, right, diagonal
watermark-font-name optional string

The name of the font to use
watermark-font-size optional integer
watermark-color optional string

rgb as in a comma separated string r,g,b
watermark-mode optional string

One of stamp, watermark
Return

The contents of the document

Example Request
<?xml version="1.0"?>
<request command="download" pretty="true" path="/sites/report2.txt"/>

exists

If optional name is supplied, check if that subpath exists with the object if the object is a directory

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
name optional path

A subpath of the supplied path
Example Request
<?xml version="1.0"?>
<request command="exists" path="/System Drive" name="some-file" pretty="true"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result exists="no"/>
</response>

fetchUserProfile

Retrieve the user profile for the logged in user or an arbitrary user if admin.

Parameter Type Description
sessionID optional string

Provide the session id
user_id optional string

The user
Return

A result element containing `value` elements for each user profile key and value for the user

Example Request
<?xml version="1.0"?>
<request command="fetchUserProfile"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result user_id="340">
    <value key="Organization" value="A Company"/>
    <value key="Job Title" value="CEO"/>
  </result>
</response>

fileCount

Compute counts of the files and directories in a subtree

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
Return

response contains a result element with attributes `dirs` and `files` and which contains the total as its text content.

Example Request
<?xml version="1.0"?>
<request command="fileCount" path="151037544713428608"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result dirs="54" files="295">349</result>
</response>

fileInfo

Return file metadata for the specified file(s). May return more than one result for shares of the same name.

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
Return

A result element containin one path element per match.

Example Request
<?xml version="1.0"?>
<request command="fileInfo" path="/System Drive/directory1" pretty="true" includeMetaData="true"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="directory1" path="151037544713428608" title="" comments="" draft="0" review="" finalDraft="0" permissions="8191" user="0" modified="0,2020-02-09 13:53:29" isdirectory="Yes" size="4096" prettyName="/System Drive/directory1" iconPath="img/files/dir.gif" mime-type="" parent="439541447604990017">151037544713428608</path>
  </result>
</response>

generateThumbnails

Regenerate thumbnail, then dump the contents of the thumbnail to the output

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
Return

The contents of the thumbnail

Example Request
<?xml version="1.0"?>
<request command="generateThumbnails" pretty="true" path="/sites/report2.txt"/>

getPrettyName

Returns the pretty name for a path

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
Return

result element with a `prettyName` and `id` attribute

Example Request
<?xml version="1.0"?>
<request command="getPrettyName" path="109476079367542263"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result path="109476079367542263" prettyName="/System Drive/report1.csv"/>
</response>

hasThumbnail

Check if a document has a thumbnail

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
Return

`result` element with attribute `hasThumbnail` with value `yes` or `no`

Example Request
<?xml version="1.0"?>
<request command="hasThumbnail" pretty="true" path="/System Drive/report2.txt"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result hasThumbnail="no"/>
</response>

icon

Download the contents of the document's icon. If name is given, the content disposition has that file name

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
name optional string

The name to use in the content disposistion header
Example Request
<?xml version="1.0"?>
<request command="icon" pretty="true" path="/Documentation/report2.txt"/>

index

Add the file to the full text index.

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
Return

result element with `indexed` attribute

Example Request
<?xml version="1.0"?>
<request command="index" path="213412696680068522"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result indexed="ok"/>
</response>

introspect

Return all api commands with whatever documentation is available.

Parameter Type Description
sessionID optional string

Provide the session id
Return

The response contains an attribute called "count" with the number of methods. There is one sub element with tag name "command" for each command.

Example Request
<?xml version="1.0"?>
<request command="introspect"/>
Example Response
<?xml version="1.0"?>
<response count="87" status="ok">
  <command name="append">
    <comment> Append text to a document

</comment>
    <parameter macro="true" type="standard-path" optional="yes">
      <name>path</name>
      <comment>The document to which to append text.</comment>
    </parameter>
    <parameter type="string" optional="yes">
      <name>content</name>
      <comment>The text to append @result
 The response contains a 'result" element with a single "path" element
 containing the meta data for the document.
</comment>
    </parameter>
    <example>
      <comment> &lt;request command="append" pretty="yes"
   path="/System Drive/report2.csv" content="x,y,z&amp;#10;q,r,s&amp;#10;" /&gt;
   </comment>
    </example>
  </command>
  <!-- ... -->
</response>

listActivity

Return a portion of the activity log

Parameter Type Description
sessionID optional string

Provide the session id
n optional int

Number of rows to return
results optional int

Same as n
offset optional int

Number of the first record to return
sort optional csv

Each csv element is a pair: column:desc or column:asc
type optional string

Type of object to return
dirs optional boolean

If true return only folders
files optional boolean

If true return only documents
Example Request
<?xml version="1.0"?>
<request command="listActivity" rows="2" page="2"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result totalResultsAvailable="67537" totalResultsReturned="2" firstResultPosition="2">
    <Result id="3" user_id="1" time_inserted="2019-01-27 01:46:28" action="Uploaded" from="/System Drive/2s.txt" to="/System Drive" description="" program_mode="ui" real_user_id="" session_id="" full_name="bryan (George Hoover)" login="bryan" firstname="George" lastname="Hoover" pretty_action="Uploaded Document"/>
    <Result id="4" user_id="1" time_inserted="2019-01-27 01:47:30" action="Logout" from="bryan" to="" description="" program_mode="ui" real_user_id="" session_id="" full_name="bryan (George Hoover)" login="bryan" firstname="George" lastname="Hoover" pretty_action="Logged Out"/>
  </result>
</response>

listDirectory

List the directory contents. If the path is "/" and pretty is true, list the user's root shares and ignore the other parameters.

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
includeMetaData optional boolean

If true, add metadata for the document or folder to the path elements
n optional int

Number of rows to return
results optional int

Same as n
offset optional int

Number of the first record to return
sort optional csv

Each csv element is a pair: column:desc or column:asc
type optional string

Type of object to return
dirs optional boolean

If true return only folders
files optional boolean

If true return only documents
files-only optional boolean

Return only files @params directories-only boolean Return only directories
pattern optional string

A full text query string
filter optional string

A string that is a substring of the names of all of the retrieved files
glob-pattern optional string

A linux-like glob pattern for filtering file names
Return

A result element containing a path element for each matching file or directory

Example Request
<?xml version="1.0"?>
<request command="listDirectory" includeMetaData="true" pretty="true" path="/System Drive/directory" files-only="true"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="image1.jpg" path="125220292151938759" title="" comments="" draft="0" review="" finalDraft="0" permissions="8191" user="1" modified="1,2020-02-08 14:32:58" isdirectory="No" size="13178" prettyName="/System Drive/pretty-test/image1.jpg" iconPath="img/files/image.gif" mime-type="image/jpeg" version="1" parent="187618080297490937">125220292151938759</path>
  </result>
</response>

listGroups

Return all groups @response

Parameter Type Description
sessionID optional string

Provide the session id
Example Request
<?xml version="1.0"?>
<request command="listGroups"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result totalResultsAvailable="2" totalResultsReturned="2" firstResultPosition="0">
    <Result id="1" name="palomino" description="Super users" lastmodified="2019-01-27 01:39:55" numofusers="34"/>
    <Result id="2" name="share-test" description="Testing shares" lastmodified="2019-12-27 19:51:33" numofusers="2"/>
  </result>
</response>

listRootContents

List the merged contents of all of the root drives

Parameter Type Description
sessionID optional string

Provide the session id
n optional int

Number of rows to return
results optional int

Same as n
offset optional int

Number of the first record to return
sort optional csv

Each csv element is a pair: column:desc or column:asc
type optional string

Type of object to return
dirs optional boolean

If true return only folders
files optional boolean

If true return only documents
includeMetaData optional boolean

If true, add metadata for the document or folder to the path elements
restrict optional string

When listing files,restrict the result to files, dirs, both
Return

result element containing path elements

Example Request
<?xml version="1.0"?>
<request command="listRootContents"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result><path>107948987516620055</path><path>109476079367542263</path><path>116943545315178810</path><path>117563592511736668</path>
    ...
  </result>
</response>

listRoots

Return the root drives for the logged in user.

Parameter Type Description
sessionID optional string

Provide the session id
n optional int

Number of rows to return
results optional int

Same as n
offset optional int

Number of the first record to return
sort optional csv

Each csv element is a pair: column:desc or column:asc
type optional string

Type of object to return
dirs optional boolean

If true return only folders
files optional boolean

If true return only documents
includeMetaData optional boolean

If true, add metadata for the document or folder to the path elements
Return

A response containing path elements

Example Request
<?xml version="1.0"?>
<request command="listRoots" includeMetaData="true"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="sites" path="124561914478016686" title="" comments="" draft="0" review="" finalDraft="0" permissions="8191" user="0" modified="1,2020-06-15 16:32:20" isdirectory="Yes" size="4096" prettyName="/sites" iconPath="img/files/dir.gif" mime-type="" share-name="sites" parent="439541447604990017">124561914478016686</path>
    <path name="/" path="439541447604990017" title="" comments="" draft="0" review="" finalDraft="0" permissions="8191" user="0" modified="" isdirectory="Yes" size="" prettyName="/System Drive" iconPath="img/files/dir.gif" mime-type="" share-name="System Drive" parent="">439541447604990017</path>
  </result>
</response>

listUsers

Query the WebPal users.

Parameter Type Description
sessionID optional string

Provide the session id
n optional int

Number of rows to return
results optional int

Same as n
offset optional int

Number of the first record to return
sort optional csv

Each csv element is a pair: column:desc or column:asc
type optional string

Type of object to return
dirs optional boolean

If true return only folders
files optional boolean

If true return only documents
search optional string

A string that is matched as a substring of the login, lastname, firstname, email, or groups.
key<n> optional string

Any number of keys that might be stored in the user_profile table. Installation specific.
Example Request
<?xml version="1.0"?>
<request command="listUsers" rows="10" page="1"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result totalResultsAvailable="121" totalResultsReturned="10" firstResultPosition="0">
    <Result id="356" login="30-DayFreeTrial@palominosys.com" name="Free Trial" email="30-DayFreeTrial@palominosys.com" role="user" lastName="Trial" firstName="Free" groups="palomino, Breakfast with Dave, Weekly Buffet with Dave, Deep Dives and Market Movers, Early Morning with Dave, Technicals with Dave, Dave's Chart Deck, Special or Thematic Reports, test, test2" date_created="2020-06-11 08:53:00"/>
    <Result id="279" login="aa-test-share-user00031178b2285e903cf0e37f" name="" email="aa-test-share-user00031178b2285e903cf0e37f@palominosys.com" role="user" lastName="" firstName="" groups="regular-share-test-group" date_created="2020-05-27 16:08:00"/>
    <Result id="106" login="aa-test-share-user072638841aca6dd10881812d" name="" email="aa-test-share-user072638841aca6dd10881812d@palominosys.com" role="user" lastName="" firstName="" groups="" date_created="2020-05-05 10:09:00"/>
    <Result id="205" login="aa-test-share-user0c5aba284a615d92fc589bf6" name="" email="aa-test-share-user0c5aba284a615d92fc589bf6@palominosys.com" role="user" lastName="" firstName="" groups="" date_created="2020-05-24 13:36:00"/>
    <Result id="100" login="aa-test-share-user0e6011d9eb0145bd610a90a9" name="A Test" email="aa-test-share-user0e6011d9eb0145bd610a90a9@palominosys.com" role="user" lastName="Test" firstName="A" groups="" date_created="2020-04-24 13:34:00"/>
    <Result id="60" login="aa-test-share-user10fae99b5422" name="" email="aa-test-share-user10fae99b5422@palominosys.com" role="user" lastName="" firstName="" groups="share-test-group" date_created="2020-04-14 12:25:00"/>
    <Result id="198" login="aa-test-share-user17916e941e5457c8990bede6" name="" email="aa-test-share-user17916e941e5457c8990bede6@palominosys.com" role="user" lastName="" firstName="" groups="" date_created="2020-05-18 12:06:00"/>
    <Result id="292" login="aa-test-share-user1d8fbeabf023de0ebe194354" name="" email="aa-test-share-user1d8fbeabf023de0ebe194354@palominosys.com" role="user" lastName="" firstName="" groups="regular-share-test-group" date_created="2020-05-27 19:13:00"/>
    <Result id="168" login="aa-test-share-user21504c07c36e3b8abc9a290d" name="" email="aa-test-share-user21504c07c36e3b8abc9a290d@palominosys.com" role="user" lastName="" firstName="" groups="" date_created="2020-05-14 10:08:00"/>
    <Result id="294" login="aa-test-share-user2ded025c6e7a788e0cfadb1e" name="" email="aa-test-share-user2ded025c6e7a788e0cfadb1e@palominosys.com" role="user" lastName="" firstName="" groups="regular-share-test-group" date_created="2020-05-27 19:14:00"/>
  </result>
</response>

login

Login with a user and password supplied in the args.

Parameter Type Description
sessionID optional string

Provide the session id
login optional string

The user name of the user logging in
password optional string

The user's password
Return

The response contains an element of name "sessionID" that has the session id as text content. Note that the response headers contain a session cookie for the session as well.

Example Request
<?xml version="1.0"?>
<request command="login" user="user1" password="password"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <sessionID>eyJpdiI6Im5kRWpuOVdBZGVYZUFOUFE1Vk9JcGc9PSIsInZhbHVlIjoiVFdUZUpsaGxkc0RuNVQ1NHlDbXFBekh0c3Fob3hBNkZFNWMxWUZYbEZtYk1YeldFb1VmV29CN0cyaGE4UFQ4VmJPak5ZV3lqY2NON3ZzT093Q2dcLzloTTNzdUc0dEUzUmx4QjJOZk42UDBnPSIsIm1hYyI6IjE3MzVkNjlhZWMxOTQ5YzA2MDUyNzdkYzMyMGJhNjA5MWQ4MjhlNTNjNGRhYzViZTgzY2YyNzAwOTBmMjQ2Y2EifQ==</sessionID>
  <version-string>3.6.9.- build 68 Thu, 21 Jul 2016 14:49:11 -0400</version-string>
  <build-number>68</build-number>
</response>

logout

Log out from the session, clearing the cookie.

Parameter Type Description
sessionID optional string

Provide the session id
Return

A response with no sub elements and status "ok"

Example Request
<?xml version="1.0"?>
<request command="logout"/>
Example Response
<?xml version="1.0"?>
<response status="ok"/>

lookupGroup

Check if the named group exists, return information about the group if it exists.

Parameter Type Description
sessionID optional string

Provide the session id
name optional string

The name of the group
Return

A result element with attributes: __exists is `yes` or `no`, id, description, name, shareCount.

Example Request
<?xml version="1.0"?>
<request command="lookupGroup" name="regular-share-test-group"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result __exists="yes" id="105" description="For testing" name="regular-share-test-group" shareCount="110" shareGroup="no"/>
</response>

lookupPretty

Returns the document id corresponding to the given pretty name

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

The pretty path to lookup up
Return

A result element with an id attribute

Example Request
<?xml version="1.0"?>
<request command="lookupPretty" path="/System Drive"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result path="439541447604990017"/>
</response>

metaData

Return the meta data for a file or folder

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
Return

A result element containing elements for each of the file properties

Example Request
<?xml version="1.0"?>
<request command="setMetaData" path="822767450189213657" title="2020-06-15 18:37:55 new title" comments="2020-06-15 18:37:55 new comments" finalDraft="yes"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <name>zzz.wdoc</name>
    <path>822767450189213657</path>
    <title>2020-06-15 18:37:55 new title</title>
    <comments>2020-06-15 18:37:55 new comments</comments>
    <draft>no</draft>
    <review>no</review>
    <finalDraft>yes</finalDraft>
    <permissions>1975</permissions>
    <user>5</user>
    <modified>5,2020-06-08 19:28:16</modified>
    <isdirectory>No</isdirectory>
    <size>12</size>
    <prettyName>/Documents/zzz.wdoc</prettyName>
  </result>
  <iconPath>img/files/webpal-icon-word-small.png</iconPath>
</response>

move

Move a document or folder to another folder

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
dest optional string

Destination folder as an id or path depending on value of pretty
overwrite optional boolean

If true, allow the move to overwrite a file of the same name in the destination
ifExists optional boolean

if true, don't return an error if source doesn't exist
Return

A result element containing - a count element containing the number of documents and folders moved - a path element with text content being the id of the moved object

Example Request
<?xml version="1.0"?>
<request command="move" path="901554464601974166" dir="478761745102601515" overwrite="true" ifExists="true"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <count>1</count>
    <path>901554464601974166</path>
  </result>
</response>

noMatchingUser

Check if an email or login exists in WebPal. One login or email must be provided. If both are provided, the email is checked.

Parameter Type Description
sessionID optional string

Provide the session id
login optional string

A login to check
email optional string

A email to check
Return

A result element with attributes `match` having values `yes` or `no` and `email` or `login` showing the requested email or login.

Example Request
<?xml version="1.0"?>
<request command="noMatchingUser" email="newUser1Test.b28923770f2f95aaca@palominosys.com"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result requestEmail="newUser1Test.b28923770f2f95aaca@palominosys.com" match="yes"/>
</response>

pdf

Download the contents of a document pdf to the output

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
watermark optional string

The text of the watermark
watermark-position optional string

One of top, left, bottom, right, diagonal
watermark-font-name optional string

The name of the font to use
watermark-font-size optional integer
watermark-color optional string

rgb as in a comma separated string r,g,b
watermark-mode optional string

One of stamp, watermark
Example Request
<?xml version="1.0"?>
<request command="download" pretty="true" path="/System Drive/Report.pdf" watermark="Downloaded on 2020-06-12 18:54" watermark-mode="stamp" watermark-position="diagonal" watermark-font-size="30"/>

permissions

Return the integer representing the permissions for the logged in user or the named user for a document or folder. Only an admin user can check the permission for other users.

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
login optional string

The login for the user for which to get the permissions.
Return

A result element containinng the permissions as a permissions attribute

Example Request
<?xml version="1.0"?>
<request command="permissions" path="/System Drive" pretty="true"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result permissions="8191" path="439541447604990017"/>
</response>

ping

Simply return 'ok', keeps session alive or fails if session expired.

Parameter Type Description
sessionID optional string

Provide the session id
Example Request
<?xml version="1.0"?>
<request command="ping"/>
Example Response
<?xml version="1.0"?>
<response status="Error">
  <error>NOT LOGGED IN</error>
</response>

recentActivity

Return recent activity display for the logged in user. This is a list of file records that have changed or been added or deleted.

Parameter Type Description
sessionID optional string

Provide the session id
max-records optional int

default 6 The maxium number of records to return
max-days optional int

default 18 The maxium number of days to go back
Return

A result element containing path elements with file information.

Example Request
<?xml version="1.0"?>
<request command="recentActivity" max-records="5"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <path file_id="122941992367239941" user="1" action="uploaded" from_dir="" to_dir="151037544713428608" to_user="" description="" real_user_id="" date_recorded="2020-06-16 15:14:43" sort_value="2020-06-16 11:14:43"/>
    <path file_id="188285191553735703" user="1" action="uploaded" from_dir="" to_dir="151037544713428608" to_user="" description="" real_user_id="" date_recorded="2020-06-16 15:14:43" sort_value="2020-06-16 11:14:43"/>
    <path file_id="847267011145829814" user="1" action="uploaded" from_dir="" to_dir="151037544713428608" to_user="" description="" real_user_id="" date_recorded="2020-06-16 15:14:42" sort_value="2020-06-16 11:14:42"/>
    <path file_id="142756522281075081" user="1" action="uploaded" from_dir="" to_dir="151037544713428608" to_user="" description="" real_user_id="" date_recorded="2020-06-16 15:14:42" sort_value="2020-06-16 11:14:42"/>
    <path file_id="151037544713428608" user="1" action="Create Folder" from_dir="" to_dir="103717787211901174" to_user="" description="" real_user_id="" date_recorded="2020-06-16 14:47:06" sort_value="2020-06-16 10:47:06"/>
  </result>
</response>

rename

Rename a document or folder

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
name optional string

The new name
ifExists optional boolean

If true, do not report an error if the document or folder does not exists
Return

A response containing a result containing a path element that contains the id of the document or folder.

Example Request
<?xml version="1.0"?>
<request command="rename" path="116071415415952886" name="the-new-name.txt"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>renamed<path>116071415415952886</path></result>
</response>

resetPassword

Reset a password and send an email to the email address if the email is known and unique.

Parameter Type Description
sessionID optional string

Provide the session id
email optional string

The email for which to reset the password
Return

`result` element containing the supplied email address

Example Request
<?xml version="1.0"?>
<request command="resetPassword" email="newUser1Test.3206992c7262a8a180@palominosys.com"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result email="newUser1Test.3206992c7262a8a180@palominosys.com"/>
</response>

setMetaData

Change meta data fields for a document or folder

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
title optional string

A new title
comments optional string

New comments
review optional boolean

A new needs review status
draft optional boolean

A new draft status
finalDraft optional boolean

A new finalDraft status
Return

A result element containing elements for each of the file properties

Example Request
<?xml version="1.0"?>
<request command="setMetaData" path="822767450189213657" title="2020-06-15 18:37:55 new title" comments="2020-06-15 18:37:55 new comments" finalDraft="yes"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <name>zzz.wdoc</name>
    <path>822767450189213657</path>
    <title>2020-06-15 18:37:55 new title</title>
    <comments>2020-06-15 18:37:55 new comments</comments>
    <draft>no</draft>
    <review>no</review>
    <finalDraft>yes</finalDraft>
    <permissions>1975</permissions>
    <user>5</user>
    <modified>5,2020-06-08 19:28:16</modified>
    <isdirectory>No</isdirectory>
    <size>12</size>
    <prettyName>/Documents/zzz.wdoc</prettyName>
  </result>
  <iconPath>img/files/webpal-icon-word-small.png</iconPath>
</response>

share

Share one or more documents or folders with one or more users

Parameter Type Description
sessionID optional string

Provide the session id
subject optional string

email message subject
message optional string

email message body
other_emails optional csv

list of email addresses
access optional integer

access permissions
end_date optional date

expiry date for access
ids optional csv

DM user IDs
groups optional csv

group names to share with
attachments optional csv

'pdf', 'thumbnail', 'original'
paths optional csv

list of DM paths (relative to current user) to share
pretty optional boolean

Interpret paths as symbolic paths
Return

The response contains an empty result elemtn.

Example Request
<?xml version="1.0"?>
<request command="share" ids="5,80" access="529" message="test" subject="test" paths="186039282571318132"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result/>
</response>

thumbnail

Return the contents of a thumbnail

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
Return

The contents of the thumbnail

Example Request
<?xml version="1.0"?>
<request command="thumbnail" pretty="true" path="/sites/report2.txt"/>

thumbnailOrImage

Download the contents of a document thumbnail to the output or if an image and no thumbnail, the image

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
Return

The thumbnail or image

Example Request
<?xml version="1.0"?>
<request command="thumbnailOrImage" pretty="true" path="/sites/report2.txt"/>

toPDF

Generate PDFs for HTML downloaded from the specified URLs or for uploaded files. If no destination or path are specified, download the first PDF using the optional fileName

Parameter Type Description
sessionID optional string

Provide the session id
path optional string

If pretty and create are true and no dest is specified, this is the full path to a WebPal folder into which the generated files are stored.
pretty optional boolean

If true, a webpal folder can be created for path
create optional boolean

If true, a webpal folder can be created for path
dest optional file-argument

If specified, the folder into which the PDFs are stored. Overrides path. Use a symbolic path if pretty is true, an id otherwise.
subdirectory optional string

Name of a folder to be created in dest to store the PDFs
fileName optional string

Name to use on download
urls optional csv

Comma separated list of URLs
paper optional string

e.g. Letter
margins optional csv

e.g. 1cm,1cm,1cm,1cm
concatenate optional boolean

If true, concatenate the PDFs generated from the URLs
title optional string

WebPal title for the newly created PDF documents
comments optional string

WebPal comments for the newly created PDF documents
Return

Either a downloaded PDF application/pdf or a result element containing the paths of the newly created documents

Example Request
<?xml version="1.0"?>
<request command="toPDF" urls="https://google.ca"/>

updateUserProfile

Update the user profile for the logged in user or an arbitrary user if admin. Keys and values are specified as set elements of the request element.

Parameter Type Description
sessionID optional string

Provide the session id
user_id optional string

The user
Return

A result element containing `value` elements for each user profile key and value for the user

Example Request
<?xml version="1.0"?>
<request command="updateUserProfile">
  <set key="Organization" value="A Company"/>
  <set key="Job Title" value="CEO"/>
</request>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result user_id="340">
    <value key="Organization" value="A Company"/>
    <value key="Job Title" value="CEO"/>
  </result>
</response>

upload

Upload a document to WebPal

Parameter Type Description
sessionID optional string

Provide the session id
dir optional string

id or symbolic path..
pretty optional boolean

If true, interpret the dir as a symbolic path
includeMetaData optional boolean

If true, add metadata for the document or folder to the path elements
name optional string

The name of the new file
fullPath optional string

A subpath in dir into which to upload the file. Folders in the path are created if they do not exists.
addVersion optional boolean

If true, add a new version to existing document; if false modify the name of the uploaded document if a document of that name exists.
title optional string

A title for the document
comments optional string

Comments for the document
replaceComments optional boolean

Replace existing comments with the new comments.
content optional string

The contents of the file if no file contained in the POST body
base64 optional boolean

Indicates that the content is base64 encoded
Return

A response element containing a path element for the uploaded file.

Example Request
<?xml version="1.0"?>
<request command="upload" pretty="true" name="report2.txt" dir="/sites/20200615174055" includeMetaData="true"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="report2.txt" path="555442058122671091" title="" comments="" draft="" review="" finalDraft="" permissions="8191" user="1" modified="" isdirectory="No" size="8" prettyName="/sites/20200615174055/report2.txt" iconPath="img/files/txt.gif" mime-type="text/plain" version="1" parent="724663140926469594">555442058122671091</path>
  </result>
</response>

userAddGroups

Add a user to some groups.

Parameter Type Description
sessionID optional string

Provide the session id
user-id optional string

The internal id of the user
groupNames optional string

A comma separated list of the group names
Return

A result element with information about the user containing one group element for each group to which the user belongs.

Example Request
<?xml version="1.0"?>
<request command="userAddGroups" user-id="5" groupNames="share-test, test-group, ShareTest, John&#x2019;s Documents"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result id="5" login="test-user" name="Test User" email="test.user@palominosys.com" role="user" lastName="User" firstName="Test" groups="share-test, test-group, ShareTest, John&#x2019;s Documents" date_created="2019-12-27 13:58:00" displayName="Test User">
    <group name="share-test"/>
    <group name="test-group"/>
    <group name="ShareTest"/>
    <group name="John&#x2019;s Documents"/>
  </result>
</response>

userExists

Check if an email or login exists in WebPal. Exactly one login or email must be provided.

Parameter Type Description
sessionID optional string

Provide the session id
login optional string

A login to check
email optional string

A email to check
Return

A result element with attributes `exists` having values `yes` or `no` and `email` or `login` showing the requested email or login.

Example Request
<?xml version="1.0"?>
<request command="userExists" email="someone@palominosys.com"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result requestEmail="someone@palominosys.com" exists="yes"/>
</response>

userFile

Returns the path name that would be used by the named user.

Parameter Type Description
sessionID optional string

Provide the session id
user optional string

Login for the user
path optional string

id or symbolic path..
pretty optional boolean

If true, interpret the path as a symbolic path
Return

A result element with the pretty name for the file

Example Request
<?xml version="1.0"?>
<request command="userFile" path="109476079367542263" user="user1"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result prettyName="/System Drive/report1.csv">
    <path>109476079367542263</path>
  </result>
</response>

userInfo

Return information about a user.

Parameter Type Description
sessionID optional string

Provide the session id
user_id optional string

A user id
login optional string

A user login (or email address if ALLOW_EMAIL_AS_ALT_LOGIN)
Return

A result element with attributes: __exists is `yes` or `no`, user attributes if the user exists.

Example Request
<?xml version="1.0"?>
<request command="userInfo" user_id="380"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result __exists="yes" id="380" login="aa-test-share-user45bb5bbb6521dfb98200ffe5" name="" email="aa-test-share-user45bb5bbb6521dfb98200ffe5@palominosys.com" role="user" lastName="" firstName="" groups="" date_created="2020-06-16 11:14:00" displayName="aa-test-share-user45bb5bbb6521dfb98200ffe5"/>
</response>

userRemoveGroups

Remove a user from some groups.

Parameter Type Description
sessionID optional string

Provide the session id
user-id optional string

The internal id of the user
groupNames optional string

A comma separated list of the group names
Return

A result element with information about the user containing one group element for each group to which the user belongs.

Example Request
<?xml version="1.0"?>
<request command="userRemoveGroups" user-id="5" groupNames="share-test, test-group, ShareTest, John's Documents"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result id="5" login="test-user" name="Test User" email="test.user@palominosys.com" role="user" lastName="User" firstName="Test" groups="" date_created="2019-12-27 13:58:00" displayName="Test User"/>
</response>

userShares

Display the shares or the shared files (if result-type is files) for a user Select the user by id or by login. If WebPal is configured with ALLOW_EMAIL_AS_ALT_LOGIN, the login may be an email address and the user is looked up by email address. Only admin can look at other users. If result_type is files also accept standard paging parameters.

Parameter Type Description
sessionID optional string

Provide the session id
user_id optional string

A user id
login optional string

A user login (or email address if ALLOW_EMAIL_AS_ALT_LOGIN)
result_type optional string

If equal to files show shared files instead of shares
type optional string

If equal to system show system shares only, if equal to user show shared files only, otherwise show both.
Return

A result element containing either file or share elements

Example Request
<?xml version="1.0"?>
<request command="userShares" login="permissions-user-1" type="user"/>
Example Response
<?xml version="1.0"?>
<response status="ok">
  <result __exists="yes">
    <share id="100" name="" from="34" to="33" group="" version="1" permissions="16" path="/System Drive/share-root/report.txt" file_id="113032034015986555" type="Email" expiry="" expiry_formatted="" date_recorded="2020-04-14 20:22:48"/>
    <share id="101" name="" from="34" to="33" group="" version="1" permissions="16" path="/System Drive/share-root/share-folder" file_id="119553414615187262" type="Email" expiry="" expiry_formatted="" date_recorded="2020-04-14 20:23:23"/>
    <share id="102" name="" from="35" to="33" group="" version="1" permissions="17" path="/System Drive/share-root/report.txt" file_id="113032034015986555" type="Email" expiry="" expiry_formatted="" date_recorded="2020-04-14 20:23:58"/>
  </result>
</response>