Manage Voximplant Platform applications
, rules
, and scenarios
from your own environment using @voximplant/apiclient-nodejs under the hood.
npm i @voximplant/voxengine-ci
Go to the Service accounts section of the control panel and generate a file with your account credentials. Learn more about service accounts here
Create a .env
file in the root directory of your project and add environment-specific variables:
VOX_CI_CREDENTIALS=/path/to/the/vox_ci_credentials.json
VOX_CI_ROOT_PATH=/path/to/the/voxengine_ci_source_files_directory
- VOX_CI_CREDENTIALS - path to your
JSON
credentials file (vox_ci_credentials.json
by default) - VOX_CI_ROOT_PATH - path to the directory where the
vox
files will be located (voxfiles
by default)
Creating a .env file is not necessary if you move the file with credentials to your project folder, and it has a default name – vox_ci_credentials.json
.
The folder with the files created after initialization will be placed in your project folder as well and will be named voxfiles
unless you decide to create a .env variable and specify something different there.
First, initialize the project (download all files and metadata from your VoxImplant account). When all the files have been successfully downloaded from the platform, you can modify them and upload them back to the platform. Read the scripts paragraph to learn more.
Read the full Voxengine CI guide for more details.
Create an application.config.json
file in the /path/to/the/voxengine_ci_source_files_directory/applications/your-application-name.your-account-name.voximplant.com/
directory, where /path/to/the/voxengine_ci_source_files_directory
is created with the npx voxengine-ci init
command (you specified this path in the VOX_CI_ROOT_PATH
env variable). Then, add the following config to this file:
{"applicationName":"your-application-name.your-account-name.voximplant.com"}
In the same directory, create a rules.config.json
file with this config:
[
{ "ruleName":"first-rule","scenarios":["first-scenario"],"rulePattern":"string-with-regexp" },
{ "ruleName":"second-rule","scenarios":["second-scenario"],"rulePattern":"string-with-regexp" }
]
where first-rule
and second-rule
are the names of your rules, first-scenario
and second-scenario
are the names of your scenarios (you can change them in the /scenarios/src
directory), string-with-regexp
is a regular expression to validate caller IDs in inbound calls (".*" by default).
You can modify existing scenarios and create new ones ONLY in the /voxfiles/scenarios/src
directory. Only the scenarios having their names specified in rules.config.json
will be uploaded to the platform. The scenario file names should match the *.voxengine.{js,ts} pattern. These are the files where you write the scenarios code.
When configs and scenarios are ready, run
npx voxengine-ci upload --application-name your-application-name
to upload this new application with all rules and scenarios to the platform.
You can also use the --dry-run
flag in this and the following command to build the project locally without uploading changes to the platform.
When an application is uploaded to the platform, you can add/modify rules (configure them in rules.config.json
) and scenarios (in /scenarios/src) and run the previous command to upload the changes. If you specify a rule name or rule id in the command, only the scenarios attached to this rule will be uploaded to the platform:
npx voxengine-ci upload --application-name your-application-name --rule-name your-rule-name
It works either when you upload a new rule or when you modify an existing one.
If you modify an existing application or existing rule, you can specify --application-id
and --rule-id
instead of -application-name
and --rule-name
:
npx voxengine-ci upload --application-id your-application-id --rule-id your-rule-id
When you change the name of an application, scenario, or rule using Voxengine CI, a new app, scenario, and rule with the same content is created on the platform. The old one is not deleted or changed due to the Voxengine CI inner logic.
You can modify these old apps, scenarios, and rules only from the platform without sharing the changes with Voxengine CI (NOT RECOMMENDED) unless you run npx voxengine-ci init --force
to make your local and remote versions consistent.
npx voxengine-ci init
npx voxengine-ci init --force
Build application scenarios (by specifying application-name) for ALL application rules without uploading to the platform
npx voxengine-ci upload --application-name your_application_name --dry-run
Build application scenarios (by specifying rule-name) for a specified application rule without uploading to the platform
npx voxengine-ci upload --application-name your_application_name --rule-name your_rule_name --dry-run
npx voxengine-ci upload --application-name your_application_name
Build and upload application scenarios (by specifying application-name and rule-name) for a specified application rule
npx voxengine-ci upload --application-name your_application_name --rule-name your_rule_name
Build and force upload application scenarios (by specifying application-name) for ALL application rules
This command is useful if scenarios have been modified on the platform without using voxengine-ci and you are going to overwrite those changes.
npx voxengine-ci upload --application-name your_application_name --force
This command is useful if scenarios have been modified on the platform without using voxengine-ci and you are going to overwrite those changes.
npx voxengine-ci upload --application-name your_application_name --rule-name your_rule-name --force
--application-id
and --rule-id
flags can be used instead of --application-name
and --rule-name
for the npx voxengine-ci upload
command when you modify an existing application and rules.
Include a template in your CI/CD job:
include:
- remote: 'https://raw.githubusercontent.com/voximplant/voxengine-ci/main/ci-cd-templates/.gitlab.yml'
Define env variables:
VOX_CI_CREDENTIALS
– path to yourJSON
credentials file (vox_ci_credentials.json
by default)VOX_CI_CREDENTIALS_CONTENT
–vox_ci_credentials.json
file contents in theJSON
format
Use the extends
keyword to reuse the .voxengine-ci
configuration sections from the template:
your-job:
extends:
- .voxengine-ci
script:
- your-script-part-one
- your-script-part-two
- etc.
You can customize your script using the following example:
your-job:
extends:
- .voxengine-ci
variables:
VOX_CI_CREDENTIALS: $SECRET_FILE_PATH
VOX_CI_CREDENTIALS_CONTENT: $SECRET_FILE_CONTENT
dependencies:
- build
when: manual
only:
- master
tags:
- docker
script:
- npx voxengine-ci upload --application-id 123456
- npx voxengine-ci upload --application-name my_first_application
- npx voxengine-ci upload --application-name my_first_application --rule-name my_second_rule --dry-run
Copy the https://github.com/voximplant/voxengine-ci/blob/main/ci-cd-templates/.github.yml
YAML file contents to your repository at .github/workflows/any_file_name.yml
.
Define the GitHub Actions secrets in the settings/secrets/actions
section of your GitHub project:
VOX_CI_CREDENTIALS
– path to yourJSON
credentials file (vox_ci_credentials.json
by default)VOX_CI_CREDENTIALS_CONTENT
-vox_ci_credentials.json
file contents in thebase64
format
NOTE: since GitHub has restrictions on passing Actions secrets in the
JSON
format, you need to base64-encode the value before assigning it to theVOX_CI_CREDENTIALS_CONTENT
variable
You can customize your script using the following example:
name: voxengine-ci
on: workflow_dispatch
jobs:
your-job:
runs-on: ubuntu-latest
needs: [ build ]
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '16'
check-latest: true
- name: Install voxengine-ci
run: npm ci
- name: Prepare credentials
run: echo "${{ env.VOX_CI_CREDENTIALS_CONTENT }}" | base64 --decode > ${{ env.VOX_CI_CREDENTIALS }}
env:
VOX_CI_CREDENTIALS: ${{ secrets.SECRET_FILE_PATH }}
VOX_CI_CREDENTIALS_CONTENT: ${{ secrets.SECRET_FILE_CONTENT }}
- name: Run voxengine-ci scripts
run: |
npx voxengine-ci upload --application-id 123456
npx voxengine-ci upload --application-name my_first_application
npx voxengine-ci upload --application-name my_first_application --rule-name my_second_rule --dry-run
First, install all necessary plugins:
-
NodeJS plugin. After the plugin has been installed, click Add NodeJS in the NodeJS installations section (in Global Tool Configuration) and specify a name (e.g. "nodejsinstallation" - this name will be used in the Build environment section).
-
Git plugin
-
Credentials Binding plugin
-
Pipeline plugin (for using Jenkinsfile)
Create a new Item and select Freestyle project.
In Source code management, choose the Git option and specify the repository URL and credentials. If there are no SSH credentials in Jenkins yet, generate them and add a private key of the SSH Username with private key type (choose the Enter directly option in the Private key section), and add a public key in your git account (SSH keys section).
In Build environment, choose the Use secret text(s) or file(s) option, specify the "VOX_CI_CREDENTIALS" name for the corresponding variable and add the "vox_ci_credentials.json" file of the Secret file type with credentials of your vox account.
Check Provide Node & npm bin/ folder to PATH in the Build environment section and specify the name of the NodeJS installation ("nodejsinstallation" in our example).
In the Build section, select Execute shell in the Build step dropdown list and add the following script:
npm ci
npx voxengine-ci upload --application-name my-application
The job is ready to run.
In your project repository, add Jenkinsfile:
pipeline {
agent any
tools {nodejs "nodejsinstallation"} // name of your NodeJS installation
stages {
stage('Before-publish') {
steps {
sh "npm ci"
}
}
stage('Publish') {
steps {
sh "npx voxengine-ci upload --application-name test" // your voxengine-ci script
}
}
}
}
Create the Pipeline Item.
Select Pipeline script from SCM in the Pipeline section.
Select Git from the SCM dropdown list, set your repository URL using SSH, and choose credentials. If you do not have credentials yet, click Add and select the SSH Username with private key type. Then add a private key (in the Private key section, choose Enter directly) and a public key in your git account (SSH keys).
Specify Jenkinsfile in Script Path.
Pipeline is ready!