HipChat

HipChat Command Line Interface (CLI)

Get the data

 Estimated Time: 2-3 min

For each new employee, two HipChat CLI actions must be executed to accomplish this purpose: createUser and addRoomMembers. Both commands will need to know the full name, email address, and title of the new employee along with the name that others can use when @mentioning that person in HipChat.

The @mention name and email address must be unique across all groups in the HipChat instance.

You need to create a comma-separated values file (.CSV) similar to the one shown on the right, as this provides an easy way to feed data to the CLI client without worrying about getting it into the correct syntax:

• Line 1 defines the headings for each column (aka field). The column names must match the HipChat CLI parameter names to avoid having to use properties file to indicate the column-to-parameter mapping.

• Lines 2 and 4 are for a new employee named Hank Johnson:

  • The first field in each row is the action: createUser on the first of Hank's rows to add him as a new HipChat user, then addRoomMembers to add him to the desired room.

  • The remaining fields on each of these rows appear in the order specified by the headings in Line 1:  the full name, email address, title, @mention name, and room name.

• Lines 3 and 5 for Jim Robertson are very similar to Lines 2 and 4, just reflecting a different employee's information.

You can create this file manually, from an Excel spreadsheet, or by saving the output from a database query. The value should be enclosed within double quotes if any field contains a line break, double-quote or comma.

The resulting file should be in plain text format, named newhires.csv.

newhires.csv

action,name,email,title,mentionName,room
createUser,Hank Johnson,hank@examplegear.com,Engineer,hjohnson,"Examplegearinc-engineering"
createUser,Jim Robertson,jim@examplegear.com,Engineer,jrobertson,"Examplegearinc-engineering"
addRoomMembers,Hank Johnson,,,,"Examplegearinc-engineering"
addRoomMembers,Jim Robertson,,,,"Examplegearinc-engineering"

Create CLI command

Estimated Time: 1 min

Use the command shown on the right to invoke the HipChat CLI client to process the data from your CSV file.

• hipchat indicates to invoke the HipChat CLI client.

• The runFromCSV /wiki/spaces/HCLI/pages/70353430 indicates to get the actual actions to run from a CSV file.

• The --file /wiki/spaces/HCLI/pages/70353430 provides the name of the CSV file, which is assumed to be in the same folder to which you installed the HipChat CLI client. If this is not what you want, you can specify a full path to the file, enclosing it within double quotes:

  --file "../yourfolder/newhires.csv"

• The --continue /wiki/spaces/HCLI/pages/70353430 indicates to keep processing the remaining actions even if an error is encountered.

Example command:

hipchat --action runFromCsv --file newhires.csv --continue

Execute CLI command

 Estimated Time: 1 min 

In your command window, type the command from the previous step and press Enter.

The command will run, showing the result of executing each action in newhires.csv.

Example output:

Run: --mentionName "hjohnson" --name "Hank Johnson" --action "createUser" --title "Engineer" --email "hank@examplegear.com" --room "Examplegearinc-engineering"
User created with id: 1928057
Run: --mentionName "jrobertson" --name "Jim Robertson" --action "createUser" --title "Engineer" --email "jim@examplegear.com" --room "Examplegearinc-engineering"
User created with id: 1928058
Run: --mentionName "" --name "Hank Johnson" --action "addRoomMembers" --title "" --email "" --room "Examplegearinc-engineering"
1 members added to room. 
Run: --mentionName "" --name "Jim Robertson" --action "addRoomMembers" --title "" --email "" --room "Examplegearinc-engineering"
1 members added to room. 
Run completed successfully. 4 actions were successful from file: /Users/jasmine/Documents/CLI/newhires.csv

Tell the new employees

Estimated Time: 3 min

Users added to HipChat via the HipChat CLI client will receive no notification email from HipChat. Therefore, you need to do the following:

1. Tell them the URL to your HipChat instance and ask them to click the Forgot your password? link on the login screen.

2. They will need to supply their email address and click the Reset password button.

3. They will receive an email with a link to reset their password.

4. After clicking that link within the email, they must choose a new password.

From that point on, they can go into the room and start chatting!

Create a reusable CLI script

OPTIONAL Estimated Time: 2 min

If you'd like to save your CLI command for later reuse, you can save it as a CLI script file.

Using an editor capable of producing a plain text file, such as Notepad (Windows) or TextEdit (Mac), create a script file named:

• For Windows: add2room.bat

• For OS X/Linux: add2room

Save it in the same folder to which you installed the HipChat CLI client and make sure it has permissions so that you can read, write and execute it.

Follow these steps in your command window to execute the script file you just created:

1. Navigate to the folder to which you installed the HipChat CLI client.

2. Type the name of the script file as shown on the right and press Enter.

The script will run, showing the result of executing each action in newhires.csv.

Contents of example CLI script file:

hipchat --action runFromCsv --file newhires.csv --continue

Command to execute reusable script file:

add2room