Skip to content

Config Files

Jump to bottom
Michael Roddy edited this page Apr 29, 2022 · 3 revisions

Table of Contents

Overview

Configuration files serve three distinct purposes:

  • Provide settings to affect the builder
  • Provide environment variable values
  • Provide configuration for scripts to be run during the build

Types of config files

JSON or YAML

The builder supports both JSON and YAML formats. The choice of format has no effect on the configuration. The examples in this page are in JSON.

Config vs. Local Config

The primary configuration file should contain the majority of the settings. The local config file should typically be used to override settings or to house sensitive information that shouldn't be in the primary config file.

Config File Processing

When loaded, the config file will undergo the following transformations:

  • Overrides in the local config file will be applied to the primary config file
  • Both config files will be dereferenced (resolve JSON $ref references)
  • The primary config file will be validated for required configuration
  • Environment variables will be loaded from the primary config file, then the local config file
  • Environment variables references will be resolved in the config files

Primary Config File Schema Documentation

The primary config file for a SDK build. Note that the properties documented are the ones used by the builder itself. Additional properties may be added anywhere in the file to be used as references; they will be ignored by the builder.

name

This is a string property. The value is arbitrary.

envVars

This section should contain key/value pair properties. On initialization, the builder will use the property name as the environment variable name and the property value as the environment variable value.

Schema

"envVars: {
  "key": "value"
}

Known Environment Variables

The following environment variables are used by the builder script:

Env var Required Description
WORKSPACE true Set by Jenkins, the path where the common repo is found
BUILD_NUMBER true Set by Jenkins, the build number
PURECLOUD_CLIENT_ID false Client ID for a client-credentials OAuth client. Required if adding notification classes.
PURECLOUD_CLIENT_SECRET false Client secret for a client-credentials OAuth client. Required if adding notification classes.
PURECLOUD_ENVIRONMENT false Defaults to mypurecloud.com. Set to a different URL to access other PureCloud environments (e.g. mypurecloud.ie)
EXCLUDE_NOTIFICATIONS false true to skip adding notification schemas. Client ID, secret, and environment are not needed if this setting is enabled.

The following environment variables are set by the script and should not be overwritten:

Env var Description
COMMON_ROOT The path to the common repo directory
SDK_REPO The path to the output directory for the SDK build. The SDK's repo is cloned to this directory.
SDK_TEMP A temp directory for temporal things

settings

This section contains general configuration settings for the builder.

sdkRepo

Properties

  • repo The HTTPS url to the repository. Example: https://github.com/MyPureCloud/purecloud_api_sdk_common.git
  • branch The branch name to use

Schema

"sdkRepo": {
  "repo": "",
  "branch": ""
}

versionFile

A string. The path to the version file.

Schema

"versionFile": ""

logLevel

A string. The logging level to set. Defaults to silly. Log levels, in increasing order of verbosity: error, warn, info, verbose, debug, silly

Schema

"logLevel": ""

extensionsDestination

A string. The path to copy the extensions for the SDK language.

Schema

"extensionsDestination": ""

swagger

Configuration settings for swagger files

Properties

  • oldSwaggerPath The file path or URL to the "old" swagger definition
  • newSwaggerPath The file path or URL to the "new" swagger definition
  • saveOldSwaggerPath optional The file path to save the old swagger file
  • saveNewSwaggerPath optional The file path to save the new swagger file

Schema

"swagger": {
  "oldSwaggerPath": "",
  "newSwaggerPath": "",
  "saveNewSwaggerPath": ""
}

openapi-generator

Configuration for the openapi-generator project

Properties

  • resourceLanguage The language to find resources for the build. Used to resolve ${COMMON_ROOT}/resources/sdk/<resourceLanguage>
  • codegenLanguage The codegen language passed to openapi-generator. Typically the same as resourceLanguage
  • jarPath The path to the openapi-generator-cli.jar file, including the filename
  • configFile The path to the openapi-generator config file
  • extraGeneratorOptions An array of strings of extra options to specify when executing openapi-generator-cli.jar

Schema

"swaggerCodegen": {
  "resourceLanguage": "",
  "codegenLanguage": "",
  "jarPath": "",
  "configFile": "",
  "extraGeneratorOptions": [
    ""
  ]
}

releaseNoteTemplatePath

A string. The path to the template for the release notes included in the SDK repo.

Schema

"releaseNoteTemplatePath": ""

releaseNoteSummaryTemplatePath

A string. The path to the template for the release notes included in the github release.

Schema

"releaseNoteSummaryTemplatePath": ""

debugConfig

A boolean. true to print the processed config to the console. Default: false

Schema

"debugConfig": true|false

enableLoggerColor

A boolean. true to enable log level colors in the console. Default: false

Schema

"enableLoggerColor": ""

stageSettings

prebuild

preRunScripts

An array of script configurations that will be run at the beginning of the phase.

Schema
"preRunScripts": []

postRunScripts

An array of script configurations that will be run at the end of the phase.

Schema
"postRunScripts": []

build

preRunScripts

An array of script configurations that will be run at the beginning of the phase.

Schema
"preRunScripts": []

compileScripts

An array of script configurations that will be run after generating the SDK source (executing openapi-generator) and copying extensions to the configured directory.

Schema
"compileScripts": []

postRunScripts

An array of script configurations that will be run at the end of the phase.

Schema
"postRunScripts": []

postbuild

gitCommit

A boolean. true to commit changes to the SDK repo.

Schema
"gitCommit": true|false

publishRelease

A boolean. true to publish a release to the SDK repo. Requires gitCommit=true.

Schema
"publishRelease": true|false

preRunScripts

An array of script configurations that will be run at the beginning of the phase.

Schema
"preRunScripts": []

postRunScripts

An array of script configurations that will be run at the end of the phase.

Schema
"postRunScripts": []

Script Configurations

There are 3 types of scripts that can be invoked: node, shell, and command. The scripts will be invoked with the configured values and will optionally fail the build if they return a non-zero status code.

Properties

  • type (string) The type of script to run. Valid values are node, shell, and command
  • command (string) The command to execute. Only valid with type=command. E.g. npm
  • path (string) The path to the script to execute. Only valid with type=node or type=shell. Relative paths are relative to ${COMMON_ROOT}/resources/sdk/<resourceLanguage>/scripts/
  • args (array[string]) An array of arguments to pass to the script
  • appendIsNewReleaseArg (boolean) true to append a boolean value indicating if the build is a new version. Added after configured args. Default: false
  • appendVersionArg (boolean) true to append a string value with the full display version number. Added after appendIsNewReleaseArg value. Default: false
  • cwd (string) Sets the current working directory context for executing the script
  • failOnError (boolean) true to fail the script if the script returns a non-zero return code

Schema

{
  "type": "",
  "command": "",
  "path": "",
  "args": [
    ""
  ],
  "appendIsNewReleaseArg": true|false,
  "appendVersionArg": true|false,
  "cwd": "",
  "failOnError": true|false
}
Clone this wiki locally