## User Attribute Importer

This tool allows you as a system administrator to add custom attributes to a systemuser. The attributes are defined in a file and mapped
to users through the user's email. Existing attributes that are not defined in the file will be retained. However, existing attributes that 
exist in the file will be overwritten.


### To Install

##### I do not have the Go toolchain installed
> Most users will want to follow these instructions

1. Go to the "Releases" tab of this github project
	- https://github.com/TheJumpCloud/jcapi/releases
2. We have provided `.zip` files for most operating systems
	- Note that macOS users will want to use the `darwin` binaries
3. Download the zip file of your choice 
	- We always recommend downloading from the latest release if possible
	- Most Windows users will want the `386` zip
4. Extract the files from the zip
	- Right click on the zip file and click `Extract All` on Windows
	- Double click on the zip file on macOS/Linux
5. `importUserAttributes_myos_myarch` is the relevant binary
	- Some may find this is an unwieldy name to type every time. Feel free to rename to your liking, in fact if this is a tool you plan on running 
    frequently we encourage this for ease of use.

> If you'd like to be able to call this binary from an arbitrary directory you can move it to `/usr/local/bin` on Linux and macOS
>> On macOS the keyboard shortcut `⌘ + Shift + G` with an open Finder window will allow you to directly type in the directory you'd like to access. 
To move the binary to `/usr/local/bin` with Finder simply use that shortcut and copy/paste `/usr/local/bin` into the dialog box. You can now drag and 
drop the binary onto the Finder window to easily make it accessible without having to navigate to a specific folder to run it. If you do this we also 
recommend renaming the binary before moving it to a more memorable name.

##### I have the Go toolchain installed
> If you don't know what "Go" or "Golang" is we have provided pre-made binaries for your convenience. Installation instructions for these 
binaries is provided in the previous section

1. Clone the `jcapi` repository (it doesn't matter where)
	- `git clone https://github.com/TheJumpCloud/jcapi`
2. Navigate to the `jcapi/examples/importUserAttributes` directory
	- `cd jcapi/examples/importUserAttributes`
3. Run go install
	- `go install .`

This will install a binary called `importUserAttributes` to your `$GOBIN`

> If you'd like to be able to call this binary from an arbitrary directory make sure your `$GOBIN` is in your `$PATH` (linux) or `%PATH%` (windows)

### To Run

To run this tool you will need to use the command line. On Windows you can use PowerShell and on OSX you can use Terminal. 

> While running this tool requires no previous experience with either of those programs some might feel wary or nervous working with a tool 
they don't understand. The following instructions in this section should provide you with all you need to get up and running, but if you would 
like to learn about the how and why of the command line we highly recommend the excellent (and free!) 
[Command Line Crash Course by Zed Shaw](http://cli.learncodethehardway.org/). Zed even provides a direct email hotline for users that get stuck. 
If problems persist, or you are unsure of where to begin contact JumpCloud support for assistance running this tool.

The input file must be in comma-separated value format as follows:
- First row (header) defines all attributes to be imported starting in the second column (first column of header row is ignored)
- The values in the header row will become the attribute name 
- Attribute names cannot exceed 32 characters, cannot contain spaces and must be alphanumeric
- Subsequent rows define attribute values for individual users 
- The first column of the user rows must contain the user's email 
- The remaining columns contain the attribute values for the user

Input File Example:
```
email,Location,Role
john.smith@example.org,Boulder,Manager
jane.doe@example.org,Denver,Developer
```
This tool takes two required arguments and two optional arguments:
- `api-key` is your JumpCloud API key (required)
- `input` is the path to the input file (required)
- `output` is the path to the output results file (optional, defaults to results.log in the current directory)
- `url` is the JumpCloud API URL (optional)

For example:

`./importUserAttributes -api-key=82105124f2979e28273d4e8dd32b2355c5012837 -input=userattributes.csv -output=test_results.log`

> If you have renamed your binary simply replace `importUserAttributes` with the new name

> If you installed the binary with the Go toolchain and your `$GOBIN` is in your `$PATH` or `%PATH%`, or if you moved the binary to `/usr/local/bin` you 
can run the above command at any time on your command line excluding the "./"

##### Windows Instructions
1. Open `PowerShell`
2. Using the `cd` (stands for "Change Directory") command navigate to where you downloaded your binaries
	- For example, if we downloaded and unzipped the binaries in our `Download` folder we just have to run: `cd Downloads\JumpCloudAPI_Examples_windows_386`. 
    If we downloaded to our desktop the command will probably look something like: `cd Desktop\JumpCloudAPI_Examples_windows_386`
	- If you used the Go install instructions and your `$GOBIN` is in your `%PATH%` you can skip step 2 and go right to 3
3. Grab your API key from the JumpCloud Admin console
	- Click on your email on the top right hand corner to access the API Settings
4. Run the command
	- `./importUserAttributes.exe -api-key=YOUR_API_KEY_GOES_HERE -input=INPUT_FILE_GOES_HERE`

> To run a command simply type it into the PowerShell window and hit `Enter` or `Return` when finished 

##### macOS/Linux Instructions
1. Open `Terminal` (this can be found in `Applications/Utilities`)
2. Using the `cd` (stands for "Change Directory") command navigate to where you downloaded your binaries
	- For example, if we downloaded and unzipped the binaries in our `Download` folder we just have to run: `cd Downloads/JumpCloudAPI_Examples_darwin_amd64`. 
    If we downloaded to our desktop the command will probably look something like: `cd Desktop/JumpCloudAPI_Examples_darwin_amd64`
	- If you used the Go install instructions and your `$GOBIN` is in your `$PATH`, or if you manually moved the binary to `/usr/local/bin` you can skip step 2 
    and go right to 3
3. Grab your API key from the JumpCloud Admin console
	- Click on your email on the top right hand corner to access the API Settings
4. Run the command
	- `./importUserAttributes.exe -api-key=YOUR_API_KEY_GOES_HERE -input=INPUT_FILE_GOES_HERE`

> To run a command simply type it into the Terminal window and hit `Enter` or `Return` when finished