VoxEngine CI

Learn how to manage Voximplant applications, rules, and scenarios from your own environment using @voximplant/apiclient-nodejs under the hood.

With Voxengine CI you can use a preferred IDE to write source code of Voximplant call scenarios (we provide type definitions for your convenience) as well as integrate application deployment into the CI/CD toolkit that is used in your environment.

To work with Voxengine CI, you need a JSON file with your credentials. Go to the Service accounts section of the control panel and generate the file there.

If the file with credentials already exists on your computer, you can use it instead of creating a new one. Learn more in the API keys and Service accounts article.

1. To install Voxengine CI, run the following command from your project folder (create the project first if you do not have it yet) in the Terminal:

npm i @voximplant/voxengine-ci

2. Create a .env file in the project root directory and add environment-specific variables to specify the name and location of the JSON file with your account credentials and the folder with files downloaded from your account:

VOX_CI_CREDENTIALS=/path/to/the/vox_ci_credentials.json
VOX_CI_ROOT_PATH=/path/to/the/voxengine_ci_source_files_directory

3. Initialize the project by running:

npx voxengine-ci init

This command downloads all files and metadata from your VoxImplant account. When all the files are downloaded, you can modify them and upload them back to the platform.

If you have an npm voxengine-ci module installed, you can use the built-in type declarations to work in your preferred IDE. Type declarations allow developers to check their code in real time and use API autocorrect.

The difference between the CDN type declarations and the built-in declarations in the CI is that in the CDN there is always the newest version, and the type declarations in the CI are always the same version as the IDE you are using, that is why the CI type declarations are recommended.

To enable CI type declarations, add a tsconfig.json file to your project's root directory and specify the path to the typings as it is shown in the example below:

{
    "include": [
        "voxfiles/scenarios/src",
        "node_modules/@voximplant/voxengine-ci/typings", "test.voxengine.ts",
    ]
}

Applications

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 (account name is your username), where /path/to/the/voxengine_ci_source_files_directory is created with the npx voxengine-ci init command. This is the default voxfiles folder or the path you specified in the VOX_CI_ROOT_PATH env variable.

Then, add the following config to the application.config.json file:

{
    "applicationName": "your-application-name.your-account-name.voximplant.com"
}

Rules and scenarios

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; and string-with-regexp is a regular expression to validate caller IDs in incoming calls (".*" by default).

Here is an example of such a file:

If your application does not have any rules yet, leave the JSON file empty {}.

You can modify existing scenarios and create new ones ONLY in the /voxfiles/scenarios/src directory. Only the scenarios with their names specified in rules.config.json will be uploaded to the platform. The scenario file names should match the *.voxengine.{js,ts} pattern.

In our case, the scenario names should be as follows: testsceanrio1.voxengine.js, testscenario2.voxengine.js. These are the files where you write the scenario code.

When everything is ready, run

npx voxengine-ci upload --application-name your-application-name

to upload a new application with all rules and scenarios to the platform.

Now you can find the newly created applications, rules, and scenarios on the platform:

When an application is uploaded to the platform, you can add/modify rules (configure them in rules.config.json) and scenarios (in /voxfiles/scenarios/src) and run the

npx voxengine-ci upload --application-name your-application-name

command again 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, but if both are specified only the ID will be taken into account:

npx voxengine-ci upload --application-id your-application-id --rule-id your-rule-id

Do not forget about the --dry-run flag if you want to test your changes before uploading them to the platform.

Initialize the project

npx voxengine-ci init

Initialize the project from scratch, deleting all existing files and configurations

npx voxengine-ci init --force

Build application scenarios (by specifying application-name/application-id) for ALL application rules without uploading them to the platform

npx voxengine-ci upload --application-name your_application_name --dry-run

Build application scenarios (by specifying application-name/application-id and rule-name/rule-id) for a specified application rule without uploading them to the platform

npx voxengine-ci upload --application-name your_application_name --rule-name your_rule_name --dry-run

Build and upload application scenarios (by specifying application-name/application-id) for ALL application rules

npx voxengine-ci upload --application-name your_application_name

Build and upload application scenarios (by specifying application-name/application-id and rule-name/rule-id) 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/application-id) 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

Build and force upload application scenarios (by specifying application-name/application-id and rule-name/rule-id) for a specified rule

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

Use templates for your repository to integrate with our CI. Let us see how to do that.

GitLab

Include a GitLab template in your CI/CD job:

  include:
  - remote: 'https://github.com/voximplant/voxengine-ci/ci-cd-templates/.gitlab.yml'

Define env variables:

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 --applicaiton-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

GitHub

Copy the .github.yml 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:

You can customize your script using the following example:

name: voxengine-ci

on: workflow_dispatch

jobs:
  your-job:
    runs-on: ununtu-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 }}" > ${{ 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 --applicaiton-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

Jenkins

Install all necessary plugins:

Creating a job via the "Freestyle project" item

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.

Using Jenkinsfile

In your project repository, add a 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.

The pipeline is ready!