Share:
ClickHelp Documentation

API: Project Management

 

With the project management functions, you can make ClickHelp a part of your continuous integration process. For example, 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

POST Request Export a publication
/api/v1/projects/{publication-id}?action=export HTTP/1.1 

Exports a publication with a given URL to the specified format. Project IDs are not supported for this operation.

In the response, this operation returns a project management task key you can use to track the task status via API.

Authorization

This request is using basic authentication.

Request parameters

Path parameters

publication-id

required

stringThe ID of the publication to export.

Request body

FieldTypeDescription

format

required

String

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

  • WebHelp
  • CHM
  • PDF
  • DOC
  • DOCX
  • RTF
  • Epub
  • MHT
  • ODT

outputFileName

required

String

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

templateFileName

required

String

The full name of the export template file (applicable only for printed formats). This should be a fully qualified Storage file name that starts with Storage/. Example:

Storage/Templates/Export Template.docx

ftpInfo

required

Object

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

   required


String

The FTP hostname of your FTP server, for example:

ftp.example.com

    userName

   required

String The FTP user name.

    password

   required

String The FTP user password

    port

   optional

IntegerThe FTP server port to which the connection will be established. If the value is null or not specified, the default FTP port is used.

    isUsePassiveMode

   optional

BooleanSpecifies 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.

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

Response example

JSON
{
"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 that can be used to track the task progress.

Get a Project Management Task Status

GET Request Get a project management task status
/api/v1/tasks/{taskKey} HTTP/1.1 

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

Authorization

This request is using basic authentication.

Request parameters

Path parameters

taskKey

required

stringThe task key of the task to get the status of.

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.

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

Response example

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

Response fields

FieldTypeDescription
isSucceeded

Boolean

or

null

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

isWorkingBoolean

Indicates whether the task is still working.

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 that describes the current status of the task.
 taskNameStringThe task name.

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: Not Found

The specified task key is invalid, or the corresponding task has already been completed, the final status request has been handled, and the task object has been terminated.

Change Publication Visibility

DELETE Request Change publication visibility
/api/v1/projects/{publication-id} HTTP/1.1 

Changes the visibility of the specified publication.

Authorization

This request is using basic authentication.

Request parameters

Path parameters

publiction-id

required

string The ID of the publication to change the visibility for.

Request body

FieldTypeDescription

updatedFields

required

String

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.

visibility

required

String

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.

Code
curl -X PATCH ^
--basic ^
--user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
--header "Content-Type:application/json" ^
-d "{\"updatedFields\": \"visibility\", \"visibility\": \"Public\"}" ^
--cacert comodo.ca-bundle ^
https://kb.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. The response body is empty.

400: Bad Request

Returned if the specified URL refers to a project, not to a publication.

404: Not Found

Returned if a publication with the specified URL does not exist.