From 4dd6d5fd1e9bfb26f3cd433c88481be1c18c5292 Mon Sep 17 00:00:00 2001 From: serfreeman1337 Date: Fri, 14 Jul 2023 12:57:28 +0300 Subject: [PATCH] docs: update README.md --- README.md | 44 ++-- README_bitrix24.md | 30 +-- README_suitecrm.md | 197 +++++++++++++++--- conf.example.yml | 34 +-- .../suitecrm-asterlink-module/manifest.php | 4 +- 5 files changed, 223 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index a341204..af167b6 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,13 @@ Supports FreePBX v14 integration with [Bitrix24](https://github.com/serfreeman13 # Asterisk You need Asterisk 13+. -To monitor how call is going this connector listens for AMI events. +To monitor calls this connector listens for AMI events. There should be 4 **different** contexts to distinguish calls: -* `incoming_context` - context for incoming calls from voip trunk. inbound calls will be registred there -* `outgoing_context` - context for outgoing calls. outbound calls will be registred there -* `ext_context` - extensions dials from queue, ring group, etc. use this context to route incoming calls to your extensions -* `dial_context` - context for originating (click2dial) calls +* `incoming_context` - context for incoming calls from voip trunk. inbound calls will be registred there. +* `outgoing_context` - context for outgoing calls. outbound calls will be registred there. +* `ext_context` - extensions dials from queue, ring group, etc. use this context to route incoming calls to your extensions. +* `dial_context` - context for originating (click2dial) calls. Default configuration is tested to work with FreePBX v14 and Asterisk v13. @@ -32,50 +32,50 @@ You see `DCS-Incoming` in `ext_context` because we are dialing **queue** extensi ## CallerID Format Connector can format CallerID using regexp. This useful when your VoIP provider doesn't send desired format. -* `cid_format` - from PBX to CRM -* `dial_format` - from CRM to PBX - * `expr` - regual expression (use double blackslashes) - * `repl` - replace pattern +* `cid_format` - from PBX to CRM. +* `dial_format` - from CRM to PBX. + * `expr` - regual expression (use double blackslashes). + * `repl` - replace pattern. If config is set and callerid doesn't matched any of regexp, then call will be ignored. # CRM Integration See instructions in the following files: -* [README_bitrix24.md](https://github.com/serfreeman1337/asterlink/blob/master/README_bitrix24.md) - For [Bitrix24](https://www.bitrix24.com/) Integration -* [README_suitecrm.md](https://github.com/serfreeman1337/asterlink/blob/master/README_suitecrm.md) - For [SuiteCRM](https://suitecrm.com/) Integration +* [README_bitrix24.md](https://github.com/serfreeman1337/asterlink/blob/master/README_bitrix24.md) - For [Bitrix24](https://www.bitrix24.com/) Integration. +* [README_suitecrm.md](https://github.com/serfreeman1337/asterlink/blob/master/README_suitecrm.md) - For [SuiteCRM](https://suitecrm.com/) Integration. # Install Install asterlink under **/opt/asterlink** folder. -* Create folder /opt/asterlink +* Create folder /opt/asterlink: ```bash mkdir /opt/asterlink; cd /opt/asterlink ``` -* Download binary from releases page +* Download binary from releases page: ```bash wget https://github.com/serfreeman1337/asterlink/releases/latest/download/asterlink_x86_64.tar.gz tar xvf asterlink_x86_64.tar.gz && rm asterlink_x86_64.tar.gz chmod +x asterlink ``` - * Or build it from source (assume you have go installed) - ```bash - go get github.com/serfreeman1337/asterlink - go build github.com/serfreeman1337/asterlink - ``` -* Create configuration file. Use conf.example.yml as example. + * Or build it from source (assume you have [go installed](https://go.dev/doc/install)): + ```bash + go get github.com/serfreeman1337/asterlink + go build github.com/serfreeman1337/asterlink + ``` +* Create configuration file. Use `conf.example.yml` as an example. ```bash wget https://raw.githubusercontent.com/serfreeman1337/asterlink/master/conf.example.yml mv conf.example.yml conf.yml nano conf.yml ``` - Note: config file is using YAML format and it requires to have proper indentation. + **Note:** config file is using YAML format and it requires to have proper indentation. Use online yaml validator to check your file for errors. -* Test run +* Test run: ```bash ./asterlink ``` ## Startup script example -Create **/etc/systemd/system/asterlink.service** file with following contents: +Create `/etc/systemd/system/asterlink.service` file with following contents: ``` [Unit] Description=AsterLink Connector diff --git a/README_bitrix24.md b/README_bitrix24.md index 8b2be63..75a6eb2 100644 --- a/README_bitrix24.md +++ b/README_bitrix24.md @@ -1,19 +1,21 @@ -# Asterlink Bitrix24 Integration +# Asterisk Bitrix24 Integration ## Basic setup -* Bitrix24 -> Applications -> Webhooks -> Add inbound webhook - * Access permissions - check **crm**, **telephony**, **user** - * Copy "**REST call example URL**" ***without*** "*profile/*" to **webhook_url** in config -* Bitrix24 -> Telephony -> Configure telephony -> Telephony users - * Configure extensions for users -## Call originations from Bitrix24 -* Configure **webhook_endpoint_addr** in config +* [Install and configure asterlink service](https://github.com/serfreeman1337/asterlink/blob/master/README.md) first. +* Uncomment `b24` entry in `conf.yml` file. +* Bitrix24 -> Applications -> Developer resources -> Other -> Add inbound webhook: + * Access permissions - check **crm**, **telephony**, **user**. + * Copy "**REST call example URL**" ***without*** "*profile/*" to **webhook_url** in config. +* Bitrix24 -> Telephony (open /telephony address) -> Configure telephony -> Telephony users: + * Configure extensions for users. +## Call originations from Bitrix24 +* Configure **webhook_endpoint_addr** in `conf.yml`. * Bitrix24 -> Applications -> Webhooks -> Add outbound webhook - * Handler address - **http://my_endpoint_addr/originate/** - * Event type - **ONEXTERNALCALLSTART** - * Copy "**Authentication code**" to **webhook_originate_token** in config -* Bitrix24 -> Telephony -> Configure telephony -> Telephony settings - * Default number for outgoing calls - Select your outbound hook + * Handler address - **http://my_endpoint_addr/originate/**. + * Event type - **ONEXTERNALCALLSTART**. + * Copy "**Authentication code**" to **webhook_originate_token** in `conf.yml`. +* Bitrix24 -> Telephony -> Configure telephony -> Telephony settings. + * Default number for outgoing calls - Select your outbound hook. ## Forwarding calls to assigned user Dialplan example: ``` @@ -29,7 +31,7 @@ Bitrix24 can download and store call recording. ``` ln -s /var/spool/asterisk/monitor /var/www/html/recfiles ``` -* Set **rec_upload** url in config +* Set **rec_upload** url in config: ``` http://my_pbx_addr/recfiles/ ``` \ No newline at end of file diff --git a/README_suitecrm.md b/README_suitecrm.md index 5cdcf8f..6c7b577 100644 --- a/README_suitecrm.md +++ b/README_suitecrm.md @@ -1,42 +1,173 @@ -# AsterLink SuiteCRM Integration +# Asterisk SuiteCRM Integration Features: * Calls logging. -* Dialing for "tel" fields. +* Click-2-Call for phone fields. * Pop up card for incoming and outgoing calls. * Forwarding calls to assigned user. -## Basic setup -* Download [suitecrm-asterlink-module.zip](https://github.com/serfreeman1337/asterlink/releases/latest/download/suitecrm-asterlink-module.zip) archive from the releases page. - Or create this archive by your own from the contents of the [connect/suitecrm/suitecrm-asterlink-module](https://github.com/serfreeman1337/asterlink/tree/master/connect/suitecrm/suitecrm-asterlink-module) folder. -* Upload and install this module on the **Module Loader** SuiteCRM Administrator page. -* Configure `Token` on the **AsterLink Settings** SuiteCRM Administrator page. - Token must be equal with the one in **conf.yml** file. +## Install +**For SuiteCRM 8 minimum working version is 8.2.0!** +* [Install and configure asterlink service](https://github.com/serfreeman1337/asterlink/blob/master/README.md) first. +* Uncomment `suitecrm` entry in `conf.yml` file and set: + * `url` - SuiteCRM site address. + * `endpoint_token` - any reasonable value. + * `endpoint_addr` - listen address of the asterlink service. + **Note:** config file is using YAML format and it requires to have proper indentation. + Use online yaml validator to check your file for errors. +* Download [suitecrm-asterlink-module.zip](https://github.com/serfreeman1337/asterlink/releases/latest/download/suitecrm-asterlink-module.zip) archive from the [releases page](https://github.com/serfreeman1337/asterlink/releases). + **SuiteCRM 8:** Extension in the module archive was built with the `8.2.0` version and tested to work with the `8.3.1`. +* Upload and install this module using **Module Loader** on the SuiteCRM Admin page. +* On the SuiteCRM Admin page open **AsterLink Connector** module settings and set: + * `Token` - to `endpoint_token` value in the `conf.yml` file. + * `Endpoint URL` - AsterLink service address (AsterLink uses http protocol, so it must start with `http://`). + **Note:** AsterLink service address must be reachable for users browsers or if you `Enable proxy`, for SuiteCRM site only. * Optional: display seconds for call duration in detail view: - Click `Add seconds to call duration view field` on the **AsterLink Settings** SuiteCRM Administrator page. -* Update layouts as you want. -* Set `Asterisk Extensions` in users profiles. -* Do a test run of asterlink app. You should see userids from suitecrm in console. + Click `Add seconds to call duration view field`. +* Set `Asterisk Extensions` for users (edit user profile). +* Do a test run of asterlink service. You should see userids from suitecrm in the console. + **Note:** You need to restart the asterlink app evertime you change asterisk extensions for users. -Note: You need to restart asterlink app evertime you change asterisk extensions for users. +**SuiteCRM 8:** If anything go wrong, simply delete `/extensions/asterlink` and `/cache` folders. -## Click-to-Call and Pop up card -* Configure `endpoint_addr` in the **conf.yml** file. -* Configure `Endpoint URL` for Click-to-Call function and `WebSocket URL` for pop up card on the **AsterLink Settings** SuiteCRM Administrator page. -* Check `Enable click-to-call for phone numbers Information` on the SuiteCRM System Settings page. - Note: SuiteCRM will only enable this for CallerID with begining plus sign. - -### Apache2 endpoint proxy -* Enable mod_proxy, mod_proxy_http and mod_proxy_wstunnel. -* Config: - ``` - ProxyPass "/asterlink/ws/" "ws://my_endpoint_addr:my_endpoint_port/ws/" - ProxyPass "/asterlink/" "http://my_endpoint_addr:my_endpoint_port/" - ``` -* Update AsterLink module settings: - ``` - Endpoint URL: http://my_endpoint_addr:my_endpoint_port/ - WebSocket URL: ws://my_endpoint_addr:my_endpoint_port/ws/ - ``` +
+ + SuiteCRM 8 extension build + + + * Append following to `projects` entry in `angular.json` configuration: + ``` + "asterlink": { + "projectType": "application", + "schematics": { + "@schematics/angular:component": { + "style": "css" + }, + "@schematics/angular:application": { + "strict": true + } + }, + "root": "extensions/asterlink/app", + "sourceRoot": "extensions/asterlink/app/src", + "prefix": "app", + "architect": { + "build": { + "builder": "ngx-build-plus:browser", + "options": { + "outputPath": "extensions/asterlink/Resources/public", + "index": "extensions/asterlink/app/src/index.html", + "main": "extensions/asterlink/app/src/main.ts", + "polyfills": "extensions/asterlink/app/src/polyfills.ts", + "tsConfig": "extensions/asterlink/app/tsconfig.app.json", + "inlineStyleLanguage": "css", + "assets": [ + "extensions/asterlink/app/src/favicon.ico", + "extensions/asterlink/app/src/assets" + ], + "styles": [ + "extensions/asterlink/app/src/styles.css" + ], + "scripts": [], + "extraWebpackConfig": "extensions/asterlink/app/webpack.config.js", + "commonChunk": false, + "namedChunks": true, + "sourceMap": true, + "aot": true + }, + "configurations": { + "production": { + "budgets": [ + { + "type": "initial", + "maximumWarning": "2mb", + "maximumError": "5mb" + }, + { + "type": "anyComponentStyle", + "maximumWarning": "6kb", + "maximumError": "10kb" + } + ], + "fileReplacements": [ + { + "replace": "extensions/asterlink/app/src/environments/environment.ts", + "with": "extensions/asterlink/app/src/environments/environment.prod.ts" + } + ], + "outputHashing": "all", + "extraWebpackConfig": "extensions/asterlink/app/webpack.prod.config.js", + "optimization": true, + "sourceMap": false, + "namedChunks": true, + "extractLicenses": true, + "vendorChunk": false, + "buildOptimizer": true + }, + "dev": { + "buildOptimizer": false, + "optimization": false, + "vendorChunk": false, + "extractLicenses": false, + "sourceMap": true, + "outputPath": "public/extensions/asterlink" + } + }, + "defaultConfiguration": "production" + }, + "serve": { + "builder": "ngx-build-plus:dev-server", + "configurations": { + "production": { + "browserTarget": "asterlink:build:production", + "extraWebpackConfig": "extensions/asterlink/app/webpack.prod.config.js" + }, + "development": { + "browserTarget": "asterlink:build:development" + } + }, + "defaultConfiguration": "development", + "options": { + "port": 34000, + "extraWebpackConfig": "extensions/asterlink/app/webpack.config.js" + } + }, + "extract-i18n": { + "builder": "ngx-build-plus:extract-i18n", + "options": { + "browserTarget": "asterlink:build", + "extraWebpackConfig": "extensions/asterlink/app/webpack.config.js" + } + }, + "test": { + "builder": "@angular-devkit/build-angular:karma", + "options": { + "main": "extensions/asterlink/app/src/test.ts", + "polyfills": "extensions/asterlink/app/src/polyfills.ts", + "tsConfig": "extensions/asterlink/app/tsconfig.spec.json", + "karmaConfig": "extensions/asterlink/app/karma.conf.js", + "inlineStyleLanguage": "css", + "assets": [ + "extensions/asterlink/app/src/favicon.ico", + "extensions/asterlink/app/src/assets" + ], + "styles": [ + "extensions/asterlink/app/src/styles.css" + ], + "scripts": [] + } + } + } + } + ``` + * Append following to `scripts` in `package.json` configuration: + ``` + "run:all": "node node_modules/@angular-architects/module-federation/src/server/mf-dev-server.js", + "build-dev:asterlink": "ng build asterlink --configuration dev", + "build:asterlink": "ng build asterlink --configuration production" + ``` + * Follow [Front-end Developer Install Guide](https://docs.suitecrm.com/8.x/developer/installation-guide/front-end-installation-guide/). + * Run `yarn run build:asterlink` to build extension. + * More info: [Setting Up a Front-End Extension Module](https://docs.suitecrm.com/8.x/developer/extensions/frontend/fe-extensions-setup/) +
## Forwarding calls to assigned user Dialplan example: @@ -48,6 +179,10 @@ same => n,Goto(ext-queues,400,1) same => n,Hangup ``` +## Upgrade from 0.4 version +* Just upload new module. SuiteCRM should handle upgrading. +* You might need to run "Quick Repair and Rebuild". + ## Upgrade from 0.3 version * Its highly recomended to backup DB before upgrading. * Remove logic hook from **custom/modules/logic_hooks.php** by removing a line with the `asterlink javascript`. diff --git a/conf.example.yml b/conf.example.yml index e8bd1ae..c2424c7 100644 --- a/conf.example.yml +++ b/conf.example.yml @@ -24,23 +24,23 @@ dialplan: # - {expr: "^\\d{7}$", repl: "+99878$0"} # dial_format: # - {expr: "^(\\+|)998(\\d{9})$", repl: "$2"} -bitrix24: - default_user: 1 - webhook_url: https://mycrm.bitrix24.eu/rest/1/mytoken/ - webhook_originate_token: my_originate_token - webhook_endpoint_addr: "0.0.0.0:5678" - # rec_upload: "http://mypbx.example.org/recfiles/" - # create_leads: true - # search_format: - # - {expr: ".*", repl: "$0"} - # - {expr: "^\\+(\\d{5})(\\d{7})$", repl: "+$1 $2"} # +XXXXX XXXXXXX - # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "+$1 $2 $3 $4"} # +XXXXX XXX XX XXX - # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "+$1 $2-$3-$4"} # +XXXXX XXX-XX-XXX - # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "$1 $2-$3-$4"} # XXXXX XXX XX XX - # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "$2 $3 $4"} # XXX XX XX - # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "$2-$3-$4"} # XXX-XX-XX - # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "(+$1) $2-$3-$4"} # (+XXXXX) XXX-XX-XX +# bitrix24: +# default_user: 1 +# webhook_url: https://mycrm.bitrix24.eu/rest/1/mytoken/ +# webhook_originate_token: my_originate_token +# webhook_endpoint_addr: "0.0.0.0:5678" +# # rec_upload: "http://mypbx.example.org/recfiles/" +# # create_leads: true +# # search_format: +# # - {expr: ".*", repl: "$0"} +# # - {expr: "^\\+(\\d{5})(\\d{7})$", repl: "+$1 $2"} # +XXXXX XXXXXXX +# # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "+$1 $2 $3 $4"} # +XXXXX XXX XX XXX +# # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "+$1 $2-$3-$4"} # +XXXXX XXX-XX-XXX +# # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "$1 $2-$3-$4"} # XXXXX XXX XX XX +# # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "$2 $3 $4"} # XXX XX XX +# # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "$2-$3-$4"} # XXX-XX-XX +# # - {expr: "^\\+(\\d{5})(\\d{3})(\\d{2})(\\d{2})$", repl: "(+$1) $2-$3-$4"} # (+XXXXX) XXX-XX-XX # suitecrm: -# url: http://my.suitecrm/ +# url: http://localhost/suitecrm/ # endpoint_token: my_endpoint_token # endpoint_addr: "0.0.0.0:5678" \ No newline at end of file diff --git a/connect/suitecrm/suitecrm-asterlink-module/manifest.php b/connect/suitecrm/suitecrm-asterlink-module/manifest.php index cd34ec5..ebbff51 100644 --- a/connect/suitecrm/suitecrm-asterlink-module/manifest.php +++ b/connect/suitecrm/suitecrm-asterlink-module/manifest.php @@ -1,4 +1,4 @@ - 'AsterLink', @@ -11,7 +11,7 @@ ], 'icon' => '', 'is_uninstallable' => true, - 'published_date' => '2023-07-13', + 'published_date' => '2023-07-14', 'type' => 'module', 'remove_tables' => 'prompt', ];