Bulk Creation of Power Readers

When you need to create a number of Power Reader accounts in your ClickHelp portal, you can automate this process using the ClickHelp API. On the Windows platform, the easiest way to do this is to use PowerShell. In this topic, you will find a sample PowerShell script and additional instructions to implement this automation.

Here is the PowerShell script code to use, you will need to save it in a text file with the .ps1 file extension:

# Before running the script, you may need to execute this command from a PowerShell console started As Administrator:
# Set-ExecutionPolicy RemoteSigned

cls

# Specify the path to the CSV file with Power Readers information
$prList = Import-Csv $Env:USERPROFILE"\Desktop\PowerReaderList.csv"

# ClickHelp portal name
$Server = '_____.clickhelp.co'

# API endpoint URL
$usersEndpointURL = "https://${server}/api/v1/users"

# User credentials to use for API calls
$uName = '__user__login__name__'
$uAPIKey = "__api__key__"

# Set API call headers 
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $uName,$uAPIKey)))
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add('Authorization', ("Basic {0}" -f $base64AuthInfo))
$headers.Add('Content-Type', 'application/json')
#$Headers =  @{Authorization=("Basic {0}" -f $base64AuthInfo), =}

# Create Power Readers based on the input list
$errCount = 0
$sucCount = 0
$prList | ForEach-Object {
    $curUserName = $_.userName
    "Creating user: $curUserName"

    $body = "{ `"userName`": `"$($_.userName)`", `"userInfo`": {`"email`": `"$($_.email)`", `"firstName`": `"$($_.firstName)`", `"middleName`": `"$($_.middleName)`", `"lastName`": `"$($_.lastName)`"}, `"userRole`": `"$($_.userRole)`", `"isDontSendEmail`": $($_.isDontSendEmail)}"
    
    try
    {
        $httpResp = Invoke-WebRequest -Headers $headers -Method Post -Uri $usersEndpointURL -Body ([System.Text.Encoding]::UTF8.GetBytes($body))

    
        switch ($httpResp.statuscode)
        { 
            201
                {
                    "Success: user created - $($curUserName)"
                    $sucCount = $sucCount + 1
                } 
            
            default
                {
                    "Unknown status code: $($httpResp.statuscode)"
                    $sucCount = $sucCount + 1
                }
        }
    }
    catch
    {
        $errCount = $errCount + 1
        "An error occurred while making the API call"
        
        $errStatusCode = $_.Exception.Response.StatusCode.Value__
        $errExceptionMessage = $_.Exception.Message
        
        
        switch ($errStatusCode)
        { 
            401
                {
                    "Error: authentication failed"
                } 
            
            409 
                {
                    "Error: user creation failed - a user with the same name already exists"
                }

            default
                {
                    "Error code: $($errStatusCode)"
                    "Error message:"
                    $errExceptionMessage
                    
                }
        }   
    }
    "`n"
}

"`n"
"---------------------------------------------------"
"Execution summary:"
"$($sucCount) user created;"
"$($errCount) errors occurred."
"---------------------------------------------------"
"`n"
"`n"
Read-Host -Prompt "Press Enter to close the window"

The script above accepts a CSV file with user data, here is an example of such file contents:

userName,email,firstName,middleName,lastName,userRole,isDontSendEmail
marcos,test@test.com,"Marcos Garcia",,Barreno,,true
marcos.garcia,test@test.com,"Marcos Garcia",,Barreno,,true

	Important
The content of a CSV file, including the keyword "true", is case-sensitive.

Here are the steps to prepare your environment and run the PowerShell script to import your Power Readers:

1. Depending on your PowerShell security settings, before you can run a script file, you may need to allow running non-signed scripts on your computer. To do this, follow the steps below:
   
   • run a new PowerShell console in the As Administrator mode;
     
   • execute this command:
     Set-ExecutionPolicy RemoteSigned
     
   • when the system asks for confirmation, type Y and press Enter.
     
2. Prepare a CSV file with user data, an example was given above. A few notes about the CSV file:
   • values of names and e-mails must contain only Latin characters, no Unicode symbols;
     
   • the latest value in each row is a boolean flag, leave it true if you don't want to send a confirmation e-mail to each Power Reader, or change it to false to allow auto-sending login credentials to each created user;
     
   • by default, the script will look for the "PowerReaderList.csv" file on the desktop of the current user, you can change this in the script code if you need to.
     
3.  Prepare your PowerShell script.
   • Open the script file in any text editor and specify your API key in line 17 inside double quotes. To learn how to generate your API Key, check this topic: Get API Key.
   • Specify your portal domain name in the Server variable declaration, and your user login name - in the uName variable declaration. The user login name and the API Key must match.
     
4. To run the PowerShell script, right-click the PS1 file you created, and select the Run with PowerShell context menu command.

Once you start the script, it will post the status for each Power Reader it is trying to create - error or success. If something goes wrong and there are errors, don't close the PowerShell console - you can copy&paste the output to a text editor and search for "error" to see which Power Readers were affected.

It is recommended that you try using this script for a couple of Power Readers first, and check how it works for you. If everything works well, you can run it for the rest of the Power Reader users.

Back
to top