Overview and Installation

Modified on Thu, 21 Dec 2023 at 01:11 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 important benefits brought to the table by the PowerShell Automation module:


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


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[]>


    <CommonParameters>

        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!



Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article