The bfx-ext-helpdesk-js is a Grenache worker that allows interaction with the internal helpdesk system over a Grape network. Basically, the bfx-ext-helpdesk-js worker acts as a proxy for the internal helpdesk's RESTful API, making it available over the DHT.
The scaffolding of the bfx-ext-helpdesk-js worker has been created using svc-js-cli with bfx-ext-js as service base.
The bfx-ext-helpdesk-js is free software. See the files whose names start with LICENSE (case-insensitive) for copying permission. The manuals, and some of the runtime libraries, are under different terms; see the individual source files for details.
Copyright years on bfx-ext-helpdesk-js source files may be listed using range notation, e.g., 2017-2023, indicating that every year in the range, inclusive, is a copyrightable year that could otherwise be listed individually.
The bfx-ext-helpdesk-js is a Grenache worker, hence it is essential that the machine on which it is launched is a member of a Grape network. The bfx-ext-helpdesk-js worker is developed in Javascript and requires a Node.js® runtime environment to be run, version greater than or equal to v14.18.0. Also, a package manager, such as npm, yarn or pnpm, is required in order to install all the dependencies.
In a nutshell, the shell command:
npm install --include='dev' --no-saveexecuted within the worker's main directory, will install all the required dependencies, suitable for all environments. You can also use yarn or pnpm.
Besides standard worker files, such as common.json where to set some general options and grc.config.json where to put the Grape address (see bfx-facs-grc for more information), the main configuration file is helpdesk.ext.json.
Below are some details of the several sections that compose this configuration file; a look at the helpdesk.ext.json.example file, within the worker’s config directory, is also possible to get a good overview of its structure.
This is the standard worker array for declaring Grenache service names. The service name root assigned to this worker is rest:ext:helpdesk, however, a service for every single helpdesk has to be declared; most importantly, the fourth key of the service name has to match a property of the helpdesk object (see next section). This means that if two services are declared, such as rest:ext:helpdesk:foo and rest:ext:helpdesk:bar:private, the object in the next section needs to have at least the foo and bar properties set.
In this section, details for every single helpdesk can be declared; as mentioned above, each key of the helpdesk object has to match the fourth key of the service name, while each item is an object with the following properties:
revision <string>API revision to be used; one of v1 or v2publicKey <string>API public keyprivateKey <string>API private keybaseUrl <string>API base URL, without any path
With the exception of API revision, all of the above properties are to be considered mandatory; in case the API revision is invalid or missing, the worker will fallback to v2.
To get started quickly, the shell command:
node worker.js --env=<environment> --wtype=wrk-ext-helpdesk-api --apiPort <port>executed within the worker's main directory will bring it up and running. As a handy alternative, when a POSIX-like compliant shell is being used, a script, defined in the package's manifest file, can be invoked using, for example, the following command:
npm run workerwhich, by default, runs the worker under the development environment, listening on port 7777. These arguments can be customized using a .npmrc file in the project root (ie a sibling of node_modules and package.json). If the version of npm currently in use supports it, this command:
npm config --location 'project' set 'port=8888'can be run to customize the port number, while this other one:
npm config --location 'project' set 'env=production'to set the environment.
Although all of this is convenient and quick, it is not advisable to use it in a production environment; in that case, the use of a proper process manager (eg systemd, pm2, etc.) is recommended.
The bfx-ext-helpdesk-js worker handles several signals for different purposes; refer to the documentation of the operating system on which this worker is being executed to figure out how to send signals to a running process.
Only major signals are covered in this section; it is possible that a signal not listed here is handled by one of the Grenache framework components used as dependency by the bfx-ext-helpdesk-js worker; refer to the documentation of the single components for a more in-depth view.
Send this signal to the bfx-ext-helpdesk-js worker to initiate a graceful shutdown. As a handy shortcut, when using a POSIX-like compliant shell and a compatible pkill command-line utility, a script, defined in the package's manifest file, can be invoked using, for example, the following command:
npm run worker:stopSend this signal to the bfx-ext-helpdesk-js worker to pause the scheduler; all incoming requests will be rejected. As a handy shortcut, when using a POSIX-like compliant shell and a compatible pkill command-line utility, a script, defined in the package's manifest file, can be invoked using, for example, the following command:
npm run worker:pauseSend this signal to the bfx-ext-helpdesk-js worker to resume the scheduler; all incoming requests will be accepted. As a handy shortcut, when using a POSIX-like compliant shell and a compatible pkill command-line utility, a script, defined in the package's manifest file, can be invoked using, for example, the following command:
npm run worker:resumeAll available actions are documented in this section; to better describe every action and assist the reader, the following type conventions will be used:
uint_ta positive, non-decimal numberstring_ta non-empty, trimmed stringint_ta non-negative, non-decimal numbersort_ta trimmed, case-insensitve string whose only possible values are ASC and DESCbool_ta boolean where1,"true","1","on"andtruewill be evaluated as true, while0,"false","0","off"andfalsewill be treated as false
Get departments list ordered by name in ascending order. All of the following arguments and properties are to be considered optional.
args <Array>0 <Object>limit <uint_t>maximum number of resultsoffset <uint_t>offset of the first result to returnsort <sort_t>sort directionpid <uint_t>department parent identifiername <string_t>a single-line, case-insensitve string that has to be contained in the department name (no more than 128 characters)
Response:
<Array>The departments list. Each list item will have the following properties:id <uint_t>department identifiername <string_t>department name
Example Response:
[
{
"id": 31337,
"name": "foobar"
}
]Get topics list ordered by name in ascending order. All of the following arguments and properties are to be considered optional.
args <Array>0 <Object>limit <uint_t>maximum number of resultsoffset <uint_t>offset of the first result to returnsort <sort_t>sort directionis_active <bool_t>whether or not topic is activename <string_t>a single-line, case-insensitve string that has to be contained in the topic name (no more than 32 characters)
Response:
<Array>The topics list. Each list item will have the following properties:name <string_t>topic nameid <uint_t>topic identifierpid <int_t>topic parent identifier if it exists, 0 otherwise
Example Response:
[
{
"name": "foobar",
"id": 31337,
"pid": 1337
}
]Get tags list ordered as configured on the helpdesk backend in ascending order. All of the following arguments and properties are to be considered optional.
Note: tags can be quite a lot; whenever possible, make use of the filters below to minimize the number of REST requests (and thereby decrease the overall response time).
args <Array>0 <Object>limit <uint_t>maximum number of resultsoffset <uint_t>offset of the first result to returnsort <sort_t>sort directionis_active <bool_t>whether or not tag is activename <string_t>a single-line, case-insensitve string that has to be contained in the tag name (no more than 255 characters)
Response:
<Array>The tags list. Each list item will have the following properties:id <uint_t>tag identifiername <string_t>tag name
Example Response:
[
{
"id": 31337,
"name": "foobar"
}
]Get agents list ordered by username in ascending order. All of the following arguments and properties are to be considered optional.
args <Array>0 <Object>limit <uint_t>maximum number of resultsoffset <uint_t>offset of the first result to returnsort <sort_t>sort directionis_locked <bool_t>whether or not agent is lockedon_vacation <bool_t>whether or not agent is on vacationdepartment_id <uint_t>department identifier associated with the agentname <string_t>a single-line, case-insensitve string that has to be contained in the agent name (no more than 64 characters)
Response:
<Array>The agents list. Each list item will have the following properties:username <string_t>agent usernameemail <string_t>agent e-mail addressid <uint_t>agent identifier
Example Response:
[
{
"username": "foobar",
"email": "foobar@example.com",
"id": 31337
}
]Get teams list ordered by name in ascending order. All of the following arguments and properties are to be considered optional.
args <Array>0 <Object>limit <uint_t>maximum number of resultsoffset <uint_t>offset of the first result to returnsort <sort_t>sort directionis_empty <bool_t>whether or not team is emptyis_active <bool_t>whether or not team is activename <string_t>a single-line, case-insensitve string that has to be contained in the team name (no more than 125 characters)
Response:
<Array>The teams list. Each list item will have the following properties:name <string_t>team nameid <uint_t>team identifieractive_members <int_t>number of active team members
Example Response:
[
{
"name": "foobar",
"id": 31337,
"active_members": 1337
}
]Refer to the example.js file within the project main directory for an example of using the API provided by the bfx-ext-helpdesk-js worker.
Current maintainers: