Introduction

Users may require to create workflows and jobs automatically from individual sources such as a database.

The JS7 - REST Web Service API allows the same store and deploy workflow operations to be performed as can be carried out from the JOC Cockpit GUI.
- See the Technical Documentation of the REST Web Service API
The JS7 - PowerShell Module provides simplified access to the REST Web Service API for scripting purposes.
- The PowerShell examples might prove to be instructive for logging REST API calls when executed and used with the -debug option.

Building Blocks

There are two building blocks to the solution:

Create the JSON representation of a workflow that includes a number of jobs.
- We suggest first creating the sample workflow with the JOC Cockpit and then either using the Show JSON workflow action menu item to display the JSON format or using the download button.
- Find the JSON Schema for workflows in the JS7 - Inventory Storage Format article.

Add the REST Web Service API calls in your preferred language or use the PowerShell cmdlets:

REST API	PowerShell cmdlet	Explanation
/authentication/login	Connect-JS7	connect to JOC Cockpit
/inventory/store	Set-JS7InventoryItem	store the workflow to the inventory
/inventory/deployment/deploy	Publish-JS7DeployableItem	deploy the workflow
/authentication/logout	Disconnect-JS7	disconnect from JOC Cockpit

Example

The following example uses of four lines of code to connect to JS7 and to store and deploy a workflow. The remaining code is used to create the workflow.

Download sample workflow created by the PowerShell Script (.json upload): sampleWorkflow.workflow.json
Download PowerShell Script: create-workflow.ps1

Example of a PowerShell script to store and to deploy a workflow

#!/usr/bin/env pwsh

# Parameterization

$url = "http://localhost:4446"
$controllerId = "controller"
$workflowName = "sampleWorkflow"
$workflowPath = "/Samples/$workflowName"

# Connection

Import-Module JS7
$credential = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'root', ( 'root' | ConvertTo-SecureString -AsPlainText -Force) )
Connect-JS7 -url $url -id $controllerId -credentials $credential | Out-Null

# Create JSON document

$workflow = New-Object PSObject

Add-Member -Membertype NoteProperty -Name 'version' -value '1.1.0' -InputObject $workflow
Add-Member -Membertype NoteProperty -Name 'timeZone' -value 'Europe/Berlin' -InputObject $workflow

$wfInstructions = @()

    $instruction = New-Object PSObject
    Add-Member -Membertype NoteProperty -Name 'TYPE' -value 'Execute.Named' -InputObject $instruction
    Add-Member -Membertype NoteProperty -Name 'jobName' -value 'job1' -InputObject $instruction
    Add-Member -Membertype NoteProperty -Name 'label' -value 'job1' -InputObject $instruction
    $wfInstructions += $instruction

    $instruction = New-Object PSObject
    Add-Member -Membertype NoteProperty -Name 'TYPE' -value 'Execute.Named' -InputObject $instruction
    Add-Member -Membertype NoteProperty -Name 'jobName' -value 'job2' -InputObject $instruction
    Add-Member -Membertype NoteProperty -Name 'label' -value 'job2' -InputObject $instruction
    $wfInstructions += $instruction

Add-Member -Membertype NoteProperty -Name 'instructions' -value $wfInstructions -InputObject $workflow

$wfJobs = New-Object @{}

    # First Job
    $wfJob = New-Object PSObject
    Add-Member -Membertype NoteProperty -Name 'agentName' -value 'primaryAgent' -InputObject $wfJob
        $executable = New-Object PSObject
        Add-Member -Membertype NoteProperty -Name 'TYPE' -value 'ShellScriptExecutable' -InputObject $executable
        Add-Member -Membertype NoteProperty -Name 'script' -value 'echo "hello world"' -InputObject $executable
    Add-Member -Membertype NoteProperty -Name 'executable' -value $executable -InputObject $wfJob
    Add-Member -Membertype NoteProperty -Name 'parallelism' -value 1 -InputObject $wfJob
    Add-Member -Membertype NoteProperty -Name 'graceTimeout' -value 30 -InputObject $wfJob
    Add-Member -Membertype NoteProperty -Name 'failOnErrWritten' -value $False -InputObject $wfJob

    $wfJobs.Add( 'job1', $wfJob )
    
    # Second Job
    $wfJob = New-Object PSObject
    Add-Member -Membertype NoteProperty -Name 'agentName' -value 'primaryAgent' -InputObject $wfJob
        $executable = New-Object PSObject
        Add-Member -Membertype NoteProperty -Name 'TYPE' -value 'ShellScriptExecutable' -InputObject $executable
        Add-Member -Membertype NoteProperty -Name 'script' -value 'echo "hello world"' -InputObject $executable
    Add-Member -Membertype NoteProperty -Name 'executable' -value $executable -InputObject $wfJob    
    Add-Member -Membertype NoteProperty -Name 'parallelism' -value 1 -InputObject $wfJob
    Add-Member -Membertype NoteProperty -Name 'graceTimeout' -value 15 -InputObject $wfJob
    Add-Member -Membertype NoteProperty -Name 'failOnErrWritten' -value $False -InputObject $wfJob
    
    $wfJobs.Add( 'job2', $wfJob )

    Add-Member -Membertype NoteProperty -Name 'jobs' -value $wfJobs -InputObject $workflow

    # Just to see the object from a file
    # $workflow | ConvertTo-Json -Depth 100 | Out-File -FilePath "$($workflowName).json"

# Inventory Management

Set-JS7InventoryItem -Path $workflowPath -Type WORKFLOW -Object $workflow
Publish-JS7DeployableItem -Path $workflowPath -Type WORKFLOW -ControllerId $controllerId 

# Connection

Disconnect-JS7

Explanation:

Line 1: A shebang is used to invoke PowerShell on Unix platforms. For Windows platforms replace this line with:
- @@findstr/v "^@@f.*&" "%~f0"|pwsh.exe -&goto:eof
- Optionally modify pwsh.exe with powershell.exe or similar to locate the PowerShell interpreter.
Line 5: The URL to JOC Cockpit is specified. This is the same URL as used from a user browser to access JOC Cockpit.
Line 6: The Controller ID is specified during setup of a Controller. Find the Controller ID in the upper right-hand corner of any JOC Cockpit page.
Line 7.8: The name of the workflow to be crated and its full path.
Line 12-14: Load the PowerShell Module and connect.
- For details see JS7 - How to connect to JOC Cockpit using the PowerShell Module.
Line 18-74: The code creates the PowerShell object of a workflow that is converted to JSON. There are many ways how to do this and different approaches - e.g. use of template files.
Line 78: The workflow object is stored to JS7.
Line 79: The workflow is deployed.
Line: 83: The connection to JOC Cockpit is closed.

Space shortcuts

Page tree

Introduction

Building Blocks

Example

Space shortcuts

Page tree

JS7 - How to create a job from the REST Web Service API using the PowerShell Module

Introduction

Building Blocks

Example