Skip to Content

Jitterbit Command Line Interface

Introduction

The Jitterbit Command Line Interface (jbcli) is a command-line tool for interacting with Citizen Integrator recipes. Once logged in to Harmony through the jbcli, you can manage your own recipe repository by downloading, validating, uploading, updating, generating, deploying, or deleting recipe metadata and Design Studio Jitterpaks.

Note

Citizen Integrator recipes are created from Design Studio projects. For Cloud Studio, instead use Cloud Studio Integration Recipes or Cloud Studio Process Templates, available through Jitterbit Marketplace.

The sections on this page describe how to install and use the jbcli.

Tip

Many administrative options provided through jbcli are now also available from within the Citizen Integrator web interface. See Citizen Integrator - My Recipes for details.

Installing the Jitterbit Command Line Interface

Download and install the Node.js JavaScript runtime environment v6.x or greater from nodejs.

  1. Enter this command at a command prompt to install jbcli using the Node.js Node Package Manager (NPM):

    $ npm install -g jbcli
    

  2. Use this command to check that jbcli was installed and is running correctly:

    $ jbcli version
    1.4.1
    

Using jbcli Commands

To use jbcli, run its commands from a command prompt. This is the general command format, with text between angle brackets being replaced by values, and text within square brackets being optional, and the command prompt represented by $:

$ jbcli <entity> <action> [options]

Check Version

Checks which version of jbcli you are running. The version number will be returned, with the current jbcli version being 1.4.1.

$ jbcli version
<version>

Log In

Logs in to jbcli with your Harmony credentials. The host option required depends on the region (one of NA, EMEA, or APAC) that your organization is associated with (see Finding My Region). A message will confirm successful authentication.

Use the option --password <myHarmonyPassword> to pass your password on the command line:

$ jbcli login --email <username> --password <password> --host <host>
User <username> authenticated successfully into <host>.

NA

$ jbcli login --email <username> --host https://citizen.jitterbit.net
Password:
User <username> authenticated successfully into https://citizen.jitterbit.net.

EMEA

$ jbcli login --email <username> --host https://citizen.jitterbit.eu
Password:
User <username> authenticated successfully into https://citizen.jitterbit.eu.

APAC

$ jbcli login --email <username> --host https://citizen.jitterbit.cc
Password:
User <username> authenticated successfully into https://citizen.jitterbit.cc.

Log Out

Logs you out of jbcli. A message will confirm successful logout.

$ jbcli logout
User <myHarmonyUsername> logged out.

List User Organizations

Lists the organizations of which you are a member. The IDs and names of the organizations available to you will be returned.

$ jbcli org list
[orgId1] orgName1
[orgId2] orgName2
...

List User Environments

Lists the Environments in the current organization. The IDs and names of the environments available to you will be returned.

$ jbcli env list
[envId1] envName1
[envId2] envName2
...

Get Properties

Gets the value assigned to a specific key. The key and its value will be returned.

$ jbcli config get <key>
<key>: <assignment>

This command can be used see which organization or environment is the default.

  • Use the key defaultOrgId to see which organization is default. The ID of the default organization will be returned.

    $ jbcli config get defaultOrgId
    defaultOrgId: orgId
    

  • Use the key defaultEnvId to see which environment is default. The ID of the default environment will be returned.

    $ jbcli config get defaultEnvId
    defaultEnvId: envId
    

Tip

To see the name of the organization or environment that an ID is associated with, use either List User Organizations or List User Environments.

Set Properties

Sets keys and values. The keys and their values will be returned.

jbcli config set <key1>=<assignment1> <key2>=<assignment2> ...
<key1>=<assignment1> set
<key2>=<assignment2> set
...

For example, this command can be used to override the default organization or environment. Note that the keys defaultOrgId and defaultEnvId are read-only and cannot be changed, as they are defined by a user’s Jitterbit account. However, you can set the organization or environment used by the jcli commands and override the defaultOrgId and defaultEnvId used when interacting with Citizen Integrator recipes through the jbcli.

  • To set an organization, use the key orgId with the ID for the desired organization obtained from List User Organizations. The set organization ID will be returned.

    $ jbcli config set orgId=<orgId>
    orgId:<orgId> set
    

  • To set an environment, use the key envId with the ID for the desired environment obtained from List User Environments. The set environment ID will be returned.

    $ jbcli config set envId=<envId>
    envId:<envId> set
    

If the organization and/or environment are not set via this command, the orgId and/or envId will default to the defaultOrgId and defaultEnvId.

List All Recipes

List all Citizen Integrator recipes that are available for you to use. Optionally, you can limit the list to only those recipes private to your organization (shown in brackets). The ID, name, and author for each recipe will be returned.

A recipe consists of two parts: a Design Studio Jitterpak (JPK) and a JSON metadata file that provides the steps a user will need to go through to configure the recipe using Citizen Integrator. (See Citizen Integrator - Configure Recipe.)

$ jbcli recipe list [--private]
[id1] name1 by author1 (organization1)
* [id2] name2 by author2 (organization2)
...

In the list of recipes that is returned, recipes that are public and available to all users will be preceded by an asterisk (*). Recipes that are private and available only to those within your organization will not have an asterisk.

Get a Specific Recipe and Save the Jitterpak Locally

Returns the JSON metadata for a specific Citizen Integrator recipe and (optionally) saves the accompanying Jitterpak to a specified location.

$ jbcli recipe get <id> [--savejpk <location>]
-- recipe JSON --
Jitterpak saved to <location>.

You can save a recipe’s accompanying Jitterpak locally if you want to reference or use a Jitterpak from an existing recipe. If you have already started a recipe and Jitterpak, but decide you want to perform advanced customization within Design Studio, use this to download the Jitterpak.

To save the metadata for the recipe locally, you can copy it from the command prompt and save as a JSON file. If you are authoring a new recipe and want to start with a similar recipe as an example, you can use this command to save a recipe’s JSON metadata.

Tip

Recipe IDs can be found using the List All Recipes command.

Validate a Recipe

Validates the JSON metadata for a local Citizen Integrator recipe. You should use this command prior to uploading a recipe to make sure it is valid.

jbcli recipe validate --recipe <recipeLocation>
Recipe is valid.

Upload a New Recipe and Jitterpak

Uploads a new Citizen Integrator recipe.

You can choose to upload a new Jitterpak and optionally the JSON metadata (using the --recipe option). For a specific recipe to work, you need to have both the Jitterpak and JSON metadata uploaded, but they do not need to be uploaded at the same time. By default, an uploaded recipe is private to your organization.

jbcli recipe upload --jpk <jpkLocation> [--recipe <recipeLocation>]
Recipe uploaded, assigned ID <id>, and can be found at <location>

Update an Existing Recipe and Jitterpak

Updates an existing Citizen Integrator recipe.

jbcli recipe update <id> --jpk <jpkLocation> [--recipe <recipeLocation>]
Recipe with ID <id> updated.

You can choose to update an existing Jitterpak and optionally the JSON metadata (using the --recipe option). For a specific recipe to work, you need to have both the Jitterpak and JSON metadata uploaded, but they do not need to be uploaded at the same time. By default, an uploaded recipe is private to your organization.

Recipes provided by Jitterbit and made available to the public cannot be updated or edited except by Jitterbit. If you wish to edit an existing public recipe, retrieve the JSON and Jitterpak, edit the files locally, and re-upload them as your own new recipe using the command Upload a New Recipe and Jitterpak.

Tip

Specific Recipe IDs can be found using the List All Recipes command.

Delete an Existing Recipe and Jitterpak

Deletes an existing Citizen Integrator recipe that has not yet been deployed. To delete multiple recipes, add additional Recipe IDs separated by spaces. Both the Jitterpak and the JSON metadata will be deleted.

jbcli recipe delete <id> [<id> ...]
Recipe with ID <id> [<id> ...] deleted.

Recipes provided by Jitterbit and made available to the public can only be deleted by Jitterbit. You can delete only those recipes that you have created. If you are the administrator of an organization, you can delete any recipes that belong to your organization.

Tip

Specific Recipe IDs can be found using the List All Recipes command.

Generate a Recipe and/or a Configure File

Used with a provided Jitterpak to generate a skeleton Citizen Integrator recipe that can be used as a recipe template.

jbcli recipe generate --jpk <location> [--recipeonly | --cfgonly]
[Recipe saved to <location>.]
[Configure file saved to <location>.]

The command results in two files being created: <project-name>-recipe.json and <project-name>-configure.json. To generate only one of these files, add the appropriate option (--recipeonly or --cfgonly).

The recipe file is a template of a recipe that you can then open in a text editor in order to fill in fields such as the description.

The configure file is a template of the file that the command Deploy a Recipe expects, which contains the actual values of the fields that are normally exposed within the Citizen Integrator web interface. You are expected to fill in the configure file with values and then use the Deploy a Recipe command to deploy the recipe.

Deploy a Recipe

Deploys a Citizen Integrator recipe. You must provide a recipe and a configure file (see Generate a Recipe and/or a Configure File). The deployed Recipe ID will be returned.

Upon deploying a recipe, each action step of the recipe will be run, similar to the deployment process from the Citizen Integrator web interface.

jbcli recipe deploy <ID> --cfg <location>
Recipe deployed, ID <id>.

Tip

The configure file can be generated as described in Generate a Recipe and/or a Configure File. The specific Recipe ID can be found using the List All Recipes command above.

List Deployed Recipes

Lists deployed Citizen Integrator recipes. You can show either all deployed recipes or (optionally) limit the list to a specific environment by passing the environment ID. The ID, name, and author for each deployed recipe will be returned.

jbcli deployed-recipe list [--environment <envID>]
[id1] name1 by author1
[id2] name2 by author2
...

List User Environments

Tip

To see the IDs of environments that are available, use List User Environments.

Un-deploy and Delete a Deployed Recipe

Un-deploys and deletes a deployed Citizen Integrator recipe. To un-deploy and delete multiple recipes, add additional Recipe IDs separated by spaces. Both the Jitterpak and the JSON metadata will be deleted.

jbcli deployed-recipe delete <id> [<id>...]
Deployed recipe with ID <id> [<id>...] deleted.

Recipes provided by Jitterbit and made available to the public can only be deleted by Jitterbit. You can delete only those recipes that you have created. If you are the administrator of an organization, you can delete any recipes that belong to your organization.

Tip

Specific Recipe IDs can be found using the List All Recipes command.