Share:
ClickHelp Documentation

Project Management

With the project management functions, you can make ClickHelp a part of your continuous integration process. Via the API, you can change a publication's visibility (for example, to make a Private publication created previously available publicly as a part of your release process) or export a publication.

Note that when exporting a publication via the API, you can make ClickHelp upload the resulting file to an FTP server of your choice automatically (this feature is API-specific and is not available in the application's UI). This is particularly useful if you ship your documentation as a downloadable file along with your product's installation.

Project Management Functions List

Export a Publication

Exports a publication with a given URL to the specified format. In the response, this operation returns a project management task key you can use to track the task status via API.

POST /api/v1/projects/{url}?action=export HTTP/1.1

Parameters

FieldTypeDescription
formatString

One of the allowed case-sensitive export format strings, which are:

  • WebHelp
  • Chm
  • Pdf
  • Doc
  • Docx
  • Rtf
  • Epub
  • Mht
  • Odt
outputFileNameString

The full name of the output file. If the output file is written in ClickHelp File Storage (default), this should be a fully qualified Storage file name that starts with "Storage/". Example:

Storage/my-product-1.0-docs.zip


If the output is written to an FTP server, this should be an FTP file name relative to the FTP directory in which the file is written. For example:

downloads/my-product-1.0-docs.zip

ftpInfoObject

An object specifying FTP server connection settings. If the value is null, the output file will be written to your ClickHelp portal File Storage.

  hostName


String

The FTP host name of your FTP server for example:

ftp.example.com

  userNameString The FTP user name.
  passwordString The FTP user password
  portInteger(Optional) The FTP server port to which the connection will be established. If the value is null or not specified, the default FTP port is used.
  isUsePassiveModeBoolean(Optional) Specifies whether passive mode will be used for the FTP connection. Try setting this parameter to true if you are facing FTP errors when the resulting file is uploaded to the FTP server. Specifically, if you face the "425 Can't open data connection" error. The default is false.

Request Example

Below, is an example of a CURL command line you can use in a batch file to export an existing publication to a CHM file and upload this file to your FTP server.

curl -X POST ^
  --basic ^
  --user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
  --header "Content-Type:application/json" ^
  -d "{\"format\": \"Chm\", \"outputFileName\": \"Storage/my-product-v1.chm\", \"ftpInfo\": {\"hostName\": \"ftp.example.com\", \"userName\": \"admin\", \"password\": \"p@ssw0rd\", \"port\": null}}" ^
  --cacert comodo.ca-bundle ^
  https://doc.clickhelp.co/api/v1/projects/my-product-publication?action=export

Response Example

{
  "taskKey": "1c3b895c37ac42af99f64ef84c822332"
}

Response Codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:

  • 200 (OK)
    The export task has started successfully, and the response body contains a task identifier which can be used to track the task progress.

Get a Project Management Task Status

To get information on a project management status, you need to use the task key you received when starting the task.

GET /api/v1/tasks/{taskKey} HTTP/1.1

Response Fields

FieldTypeDescription
isSucceeded

Boolean

or

null

Indicates whether the task has completed successfully. If the task has not completed yet, the value is null.

isWorkingBoolean

Indicates whether the task is still working.


Note: keep track of this property value. When a task finishes its execution, the server waits until you obtain its status for the last time and after that the task object is terminated. This means that you will start getting 404 (Not Found) responses for subsequent calls once you receive a response with this field containing true.

 maxOverallProgressIntegerThe maximum value of task progress value. Use it to calculate the percentage of the task completion if necessary.
 overallProgressIngegerThe task overall progress. Use it to calculate the percentage of the task completion if necessary.
 statusTextStringA string which describes the current status of the task.
 taskNameStringThe task name.

Request Example

Below, is an example of a CURL command line you can use in a batch file to check the status of a task after getting the task key.

curl -X GET ^
  --basic ^
  --user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
  --cacert comodo.ca-bundle ^
  https://doc.clickhelp.co/api/v1/tasks/d8032d8d242a4e65b659ff8ac9c57100

Response Example

{
  "isSucceeded":null,
"isWorking":true,
"maxOverallProgress":10000,
"overallProgress":5638,
"statusText":"Extracting topics...",
"taskName":"Exporting my-product-v1.chm" }

Response Codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:

  • 200 (OK)
    The status request has succeeded, the response body contains the task progress information.
  • 404
    The specified task key is invalid; or the corresponding task has already completed, the final status request has been handled and the task object has been terminated.

Change Publication Visibility

Changes the visibility of the specified publication.

PATCH /api/v1/projects/{url} HTTP/1.1

Parameters

FieldTypeDescription
updatedFieldsString

A comma-separated list of field names that will be updated. If a field name is not in the list, it will not be updated even if the field value is specified in other request parameters.

visibilityString

The new visibility value. Can be one of the following case sensitive string values:

  • Private
  • Restricted
  • Public

Request Example

Below, is an example of a CURL command line you can use in a batch file to make an existing publication Public.

curl -X PATCH ^
  --basic ^
  --user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
  --header "Content-Type:application/json" ^
  -d "{\"updatedFields\": \"visibility\", \"visibility\": \"Public\"}" ^
  --cacert comodo.ca-bundle ^
  https://doc.clickhelp.co/api/v1/projects/my-product-v1

Response Codes

All API functions may return error codes listed in the  Error Handling  topic. Below, are the operation-specific meanings of some response codes:

  • 200 (OK)
    Returned if no publication properties were updated.
  • 204 (No Content)
    Returned if the changes have been applied successfully. Response body is empty.
  • 400
    Returned if the specified URL refers to a project, not to a publication.
  • 404
    Returned if a publication with the specified URL does not exist.