Overview and Installation

Modified on Mon, 08 Apr 2024 at 11:25 PM

This is a detailed topic in our support portal in the Using Hopp series and assumes that you have some prior knowledge or experience using Hopp.

Hopp delivers a PowerShell module that can be used to automate the jobs that are normally submitted manually from the Portal Operations user interface.

By far - and indeed for many years - the normal use-case has been that one or more team users (operators) access the Portal Operations and from there submit migration jobs by manually identifying Business Objects, Views, Tables, Valuesets etc and submitting job to load, export, import and so on.

While this will certainly always be the case, there are some essential benefits brought to the table by the PowerShell Automation module:

Orchestration	3rd party orchestration software like Octopus Deploy, Control-M, Automic, Tivoli and others can use the Automation module to submit the migration jobs as part of a larger flow that includes both predecessor and successor steps in the end-to-end migration project.
Interactive	In the everyday development process, developers can use PowerShell and the Automation module to script jobs together in flows that can execute unattended - avoiding the need to monitor the job list to launch jobs in the flow as predecessor jobs complete

The Hopp Automation module consists of a series of PowerShell cmdlets to list items like Business Objects, Valuesets, Views Tables etc. Other cmdlets create parameterized jobs that are ready to be submitted. Parameterized jobs can then be submitted, and finally, a cmdlet can wait for submitted jobs to finish.

Especially of interest for the interactive use-case, the user can create a schedule to combine sets of ready-to-submit, parameterized jobs. A schedule can then be submitted as one unit and if the schedule terminates due to a faulted/cancelled job it can be restarted to resume execution from the point of failure.

Installation

To install the Hopp.Automation module, simply download it from our download page for the current version. The list of versions is here.

The download is a zip file that must be unzipped to a local folder on the machine. Once unzipped, the module can be loaded into PowerShell using the Import-Module command.

By default, PowerShell will look for modules in one of the folders it knows about. You can obtain a list of these folders from the PowerShell $env variable like so:

$env:PSModulePath -split ';'

Place the unzipped Hopp.Automation folder in one of the folder listed by this command. Normally, on a Windows machine, the folder should be placed in C:\Program Files\WindowsPowerShell\Modules.

The module can then be imported into a new PowerShell session with this command:

Import-Module Hopp.Automation

OBS: It is important that the Hopp.Automation module is placed in one of the folders in the PSModulePath and imported as described. While it is possible to place the Hopp.Automation folder in another location and then use the Import-Module command to import the module by passing the path to the Hopp.Automation.psm1 file, this approach will not work.

PowerShell warnings

You may experience warnings from PowerShell the first time you import the module depending on your PowerShell settings. This is quite normal and does not signify any undue risk.

As all Hopp software, the Automation PowerShell module is signed with Hopp's trusted code signing certificate.

If you get this warning:

Security warning

Run only scripts that you trust. While scripts from the internet can be useful, this script can potentially harm your

computer. If you trust this script, use the Unblock-File cmdlet to allow the script to run without this warning

message. Do you want to run C:\Program Files\WindowsPowerShell\Modules\Hopp.Automation\Hopp.Automation.psm1?

[D] Do not run [R] Run once [S] Suspend [?] Help (default is "D"):

You can exit with "D" and then tell PowerShell to trust our signed module with this command:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

Then import the module again.

You may also experience this warning that PowerShell does not traverse up to the trusted issuer of our certificate.

Do you want to run software from this untrusted publisher?

File C:\Program Files\WindowsPowerShell\Modules\Hopp.Automation\Hopp.Automation.psm1 is published by CN=hopp tech ltd,

O=hopp tech ltd, STREET=86 to 90 Paul Street, L=London, PostalCode=EC2A 4NE, C=GB and is not trusted on your system.

Only run scripts from trusted publishers.

[V] Never run [D] Do not run [R] Run once [A] Always run [?] Help (default is "D"):

In this case, it is safe to accept with "A" for Always Run - and the module should now be imported

Add to profile

It is possible to add the Hopp.Automation module to your PowerShell profile in order to avoid doing the import every time a new PowerShell session is started:

# If this command returns true, you already have a PowerShell profile
Test-Path $PROFILE

# If you DON'T have a PowerShell profile yet, run this command
New-Item -Type File -Path $PROFILE -Force

# Edit the profile
notepad $PROFILE

# Add this line to the profile file and save it
Import-Module Hopp.Automation

Available cmdlets and help

You can obtain a list of all the available cmdlets in the Hopp.Automation module with this command:

Get-Module -ListAvailable -Name 'Hopp.Automation' | Select-Object -expandProperty ExportedFunctions

And you can get detailed help information on a specific command with like this: Get-Help (command name).

For instance, this command:

Get-Help Submit-HpJob -detailed

Will output the detailed information for the Submit-HpJob cmdlet:

NAME

Submit-HpJob

SYNOPSIS

Submits a list of parameterized jobs

SYNTAX

Submit-HpJob [-jobs] <PSObject[]> [<CommonParameters>]

DESCRIPTION

The Submit-HpJob cmdlet receives a list of jobs and for each job, it will take action

depending on the job state:

- Completed or Running: No action

- Faulted or Cancelled: The job will be restarted

- None: The job will be started

The started and restarted jobs will be output to the pipeline to enable

waiting for completion with the Wait-HpJob cmdlet

Normal usage is to pipe the output to the Wait-HpJob cmdlet

PARAMETERS

-jobs <PSObject[]>

This cmdlet supports the common parameters: Verbose, Debug,

ErrorAction, ErrorVariable, WarningAction, WarningVariable,

OutBuffer, PipelineVariable, and OutVariable. For more information, see

about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).

-------------------------- EXAMPLE 1 --------------------------

PS > Get-HpEntityList | New-HpExportEntity | Submit-HpJob | Wait-HpJob

Submits an export job for each of the entities migrating in the track and wait for all

jobs to complete

Summary

With this brief introduction we have set the scene for the Hopp Automation PowerShell module.

The following articles in this section will give you insights into using the module to orchestrate your production migrations or simply make you daily Hopp developer life a walk in the park!

Onwards and upwards!