Developer Toolkit Set Up

Administration

ClosedCertified and Supported Environments

  • Certified Versions - The following application versions are certified for the CPQ Developer Toolkit.

    Environment

    Operation System

    File System

    JDK

    Client/Terminal

    Windows

    10.0.18363 N/A Build 18363

    NTFS

    LTS Java 11.x

    Windows PowerShell

    Windows Command prompt

    Linux

    Oracle Linux Server 7.4

    ext4

    LTS Java 11.x

    Linux Terminal

    Mac

    macOS Mojave 10.14.6

    APFS(Encrypted)

    java 11.0.4

    Mac Terminal Version 2.9.5 (421.2)
  • System Requirement - JDK 11 or higher must be installed to use this tool.

  • Supported - Oracle CPQ supports the following clients for the Developer Toolkit.

    1. MacOS 10.14.* with Z Shell and Mac Terminal
    2. Windows 10.0*
    3. Oracle Linux Server 7.4*

  • Code Editor and Version Control System

    Developers can use any IDE or code editor to work on their BML code.

  • Version Control System

    Developers can use any version control system of their choice. We recommend that you commit to source control from the beginning to help avoid conflicts and to drive your development process efficiently.

ClosedDownload and Install Developer Toolkit

Complete the following steps to download and install the CPQ Toolkit CLI.

  1. Download the Developer Toolkit CLI:

  1. Extract the zip or tar files to your local working directory (e.g. C:\Users\jsmith\cpq-dev)
  2. Add the CPQToolkit "bin" directory to your PATH variable.

  3. Run the following command to verify the CLI installation:

    cpq-toolkit --help

ClosedInitialize and Register the Developer Toolkit CLI

This section explains how to configure the Developer Toolkit Command Line Interface (CLI) to interact with your CPQ environment and other relevant settings available.

Note: If you are using a proxy, refer to Use the Developer Toolkit Behind a Company Firewall or Web Proxy to set your proxy server parameters.

For enabling secure authentication and authorization, the CPQ Developer Toolkit allows developers to dynamically register the CLI client with a CPQ Authentication Server. The Auth server will generate client ID/secret and will provide other metadata to be used to complete the authorization access token exchange in 3-legged OAuth Flow.

The init command initializes the OAuth properties configuration file under \CPQToolkit-x.x.x-SNAPSHOT\bin\conf\ for 3-legged OAuth flow. Once the client is registered, the developer can authorize cpq-toolkit actions using their CPQ user credentials with 3-legged OAuth Flow. For initial authentication, users will be prompted for their credentials to log in to CPQ Site. With a successful login, the CPQ server will generate an access token that will be used to authorize any further CLI actions.

Perform the following steps to initialize and register your developer toolkit CLI client:

  1. Open your Terminal or Command Prompt.

  2. Use the init command to dynamically register your CLI client:

    cpq-toolkit init --register --host=<sitename>.com -f

    You can also provide the following command-line options with the init command.

    ClosedInit Command Options

ClosedUsing the CPQ Init Tool

  • To print command option for CPQ init tool use --help option as shown below

    cpq-toolkit init --help

  • To initialize OAuth config settings by passing values on CLI use the following command. The user will be prompted for all the details.

    cpq-toolkit init

  • To force update port and host config property values use the following command.

    cpq-toolkit init [--port=<port>] [--host=<hostName>] [-f]

  • To initialize OAuth config settings by passing the property values in a file, use the following command. 

    cpq-toolkit init <configFilePath>

    • <configFilePath>: The path of file containing the OAuth configuration properties.

    • The configuration file should be a text file with following format

      client.id=<your_client_id>
client.secret=<your_client_secret>
endpoint.redirection.port=<port>
host.name=<your_host_name>
scope=<scopes separated by spaces>

      Notes

      • The host name value should not include protocol.(e.g. --host=abcd.com)
      • Each property should be on a new line.
      OAuth Configuration Properties

      The OAuth configuration file has the following properties:

      Property Name

      CLI Required?

      Default Value

      registration.client.uri

      No

      -

      endpoint.redirection.listen.timeout

      No

      60000

      software_version

      No

      21.1.0

      registration.access.token

      No

      -

      scope

      Scopes allow API endpoints to be restricted to clients. Only two scopes are allowed: adminMeta.read and adminMeta.write

      Refer to the init Command --scopes option to update or override this option.

      adminMeta.read adminMeta.write

      remote.protocol

      The client-server protocol for connecting to the remote host. The default is HTTPS.

      Refer to the init Command --remote-protocol option to update or override this option.

      HTTPS

      endpoint.redirection.port

      No

      Refer to the init Command -p option to update or override this option.

      8099

      grant.type

      No

      AUTHORIZATION_CODE

      host.name

      Yes

      Required

      client.secret

      No

      -

      client.id

      No

      -

ClosedUse the Developer Toolkit Behind a Company Firewall or Web Proxy

Perform the following steps to set your web proxy, if you receive errors when you install the Developer Toolkit on a system behind a company firewall or web proxy.

  1. Navigate to: <your local working directory>/CPQToolkit-x.x.x-SNAPSHOT/bin.

    • <your local working directory> is the directory where you installed the Developer Toolkit (e.g. C:/Users/jsmith/cpq-dev).

    • x.x.x represents the current CPQ Toolkit version.

  2. Open the cpq-toolkit.bat file.

  3. Replace "yourproxy.company.com" with the URL and port of your company proxy.

    For example, replace the following statement:

    JAVA_ARGS="-Xms8m -Xmx64m -Dcpqtoolkit.home=$CPQTOOLKIT_HOME"

    with the following statement:

    JAVA_ARGS=-Xms8m -Xmx64m -Dhttp.proxyHost=yourproxy.company.com  Dhttp.proxyPort=80
    Dhttps.proxyHost=yourproxy.company.com -Dhttps.proxyPort=80
    "-Dcpqtoolkit.home=%CPQTOOLKIT_HOME%"

ClosedSet Up Workspace and Source Directories

The CPQ Developer Toolkit environment contains workspace and source directories.

  • The Workspace Directory is a folder where Developer Toolkit stores history, logs, and workspace settings.

  • The Source Directory is a folder where your CPQ Util and Commerce BML Libraries reside. This folder on the local file system contains a child folder with the special name ".cpqtoolkit".

Note: These directories can be set up at the time of your first pull from the CPQ server. The CLI tool will create target directories if they don't exist.
This includes the source and workspace directories in all supported operating systems.

Perform the following steps to set up these directories:

  1. Open your Terminal or Command Prompt.

  2. Enter the following command: cpq-toolkit pull <target_dir>

    • <target_dir>: The directory into which the downloaded metadata will be copied.

    • The CLI will mark this folder as a source directory by creating a special folder with ".cpqtoolkit" name.

    • After the successful completion of the pull command, you will be able to see downloaded Commerce and BML Libraries in your source directory.

    Example Command

    Example Pull command

  3. When prompted, enter your workspace directory.

    • The workspace directory should not overlap with your source directory.
    • If needed, this directory can be modified from the "/CPQToolkit-x.x.x-SNAPSHOT/conf/bootstrap.properties" file.

    Example Command

    Enter workspace directory example

  4. The Developer Toolkit CLI will launch a browser window to authenticate your identity. Enter your credentials and navigate back to the CLI client. The set up is complete. To understand the folder structure for your workspace and source directory, refer to Developer Toolkit Directory Structure.

    Setup complete

ClosedDeveloper Toolkit Directory Structure

ClosedWorkspace Directory Structure

ClosedSource Directory Structure

ClosedHistory Logs

History logs for each command execution are saved under the "history" folder in your workspace directory (e.g. /users/jsmith/cpq-toolkit-settings/history/). The CLI will create a new log folder and inform the user of a folder location as shown below:

History Logs

The log folder will be named using the following syntax: YYYY-MM-dd-HH-mm-ss-SSS_commandname. Below is the folder structure for history logs:

Folder structure for history logs

ClosedPull Log

ClosedPush Log

ClosedTest Results JSON File

ClosedTasks JSON File

Notes

  • Limit the number of developers that can perform pull, save, or deploy commands directly to CPQ.
  • Use your source control system to manage a master version of the site contents.
  • Push specs should only include BML Library functions that the developer is currently working on.
  • At a given time, only one developer should be working on a specific BML function or test.

Related Topics

Related Topics Link IconSee Also