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.

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

Install the Jitterbit Command Line Interface¶

Download and install the Node.js JavaScript runtime environment v6.x or greater from https://nodejs.org/en/download/.

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
   

Use 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 Find 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
  

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.

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.

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.

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

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

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.