Related articles

• External Commands

• Windows Schedules Tasks

• Task Management

• Advanced Task Configuration

• Custom notifications

Introduction

The ExternalCommandRunner (ESI.Octopus.ExternalCommandRunnerApp.exe) program allows executing external command tasks in the workflow of a service or a change request. The program must be automated in the Windows Task Manager to ensure the prompt execution of the tasks. 

This article will explain how to use the ExternalCommandRunner to create automated workflows in service requests available on the Web Portal. 

How it works

The following steps are performed when the ExternalCommandRunner program is executed:

1. Connection to the Octopus server.
2. Validation that there are external command tasks ready to be executed.
3. Execution of a task.
4. Recording of the results.
5. Modification of the task status.
6. Return to the validation step to see if there is another task ready to be executed.
7. End of the command when there are no more tasks to be executed.
    

Prerequisites

• Create an Octopus system account that will be used to run the task. See the System Account section of the User Management Wiki.
• Context Windows with enough rights to access the various software used by the external commands.

Examples of use

Entirely automated workflow examples:

• Automatically adding a user to an AD group. Membership in this group could lead to:
  • Adding parameters to the PC via a pre-set GPO.
  • Remotely installing software via SCCM or a similar deployment platform.
• The triggering of a technical workflow. The triggering could lead to:
  • Preparation of a new virtual machine for testing.
  • Automatically migrate an application to workstations at the time the client needs it.
• A modification trigger within Octopus. The triggering could lead to:
  • Injecting data into Octopus via a DataImporter to make corrections or additions.

Using the ExternalCommandRunner program

ExternalCommandRunner is a command-line program (DOS). It is so designed to be easy to automate.

• The complete name of the ExternalCommandRunner program is: ESI.Octopus.ExternalCommandRunnerApp.exe.
• It is located in the local Octopus folder (C:\Program Files\Octopus) or in (\%LocalAppData\Octopus).
• Example of a folder where Octopus can be found:
  • For Windows 7: C:\Users\SLevesque\AppData\Local\Octopus
  • For Windows XP: C:\Documents and Settings\SLevesque\Local Settings\Application Data\Octopus

Executing External Commands from a Command Line

To launch the ExternalCommandRunner executable, you must first open a command prompt window (DOS) and position yourself in the Octopus directory. Then, you must enter the following command line:

ESI.Octopus.ExternalCommandRunnerApp.exe /login:system /password:octo /team:1

Example of the DOS command prompt

Before running the command, it is recommended to validate the required parameters.

Parameters

There are 7 parameters available, 3 of which are mandatory to run ExternalCommandRunner:

Mandatory Parameters

• /Login
  • Octopus Username.
• /Password
  • Octopus Password.
• /Team
  • ​The number of the team to be updated.

  • By default, IT is team number 1.

  • How to find the team number?

Optional Parameters

• /Timeout:DurationInMinutes
  • Allows specifying in minutes the maximum duration during which the ExternalCommandRunner will run for each command.
  • By default, the system is set to 5 minutes.
  • If the task is finished before, the program continues running normally.
  • If the task is not finished when the delay is expired, the task is set to an Error status and the program continues running normally.
• /LogFilePath:FileName.log
  • Replaces the location of the log file.
  • By default, the file is named ExternalCommandRunnerApp_AAAAMMJJ_HHMMSS.log  and will be located in the same folder as the ExternalCommandRunner executable.
  • If you move the file to a folder other then Octopus, make sure this folder exists (the system will not create the folder).
  • Ex. : /LogFilePath:C:\LogFiles\ExternalCommandLogFile.log.

• /Help

  • ​Show the command parameters in the command prompt.

• ​/WaitForKeyPress

  • ​The application will wait for a key to be pressed before completing the execution.

• /PurgeLogs
  • Can automatically erase old log files
  • The parameter is used to determine how many days of log files that you want to keep.
  • For more information, see the Octopus Tools | Maintenance of log files.

Workflow automation with Octopus

Benefits of automation

The automation of workflows with Octopus allows to obtain several gains in an organization:

• Accelerate delivery time and the quality of services to users.
• Reducing the amount of manual interventions carried out by the various Octopus users, freeing them for tasks with greater added value.
• Contributes to increasing the level of maturity of the IT organization.

Implementation

To automate a workflow in Octopus, use the following general procedure:

1. Create a script or command line application that achieves the desired goal of the external command.
   • The script must be able to receive variables in parameters (Windows user name, email address, machine name, etc.).
   • The script must handle errorlevels and make sure to return 0 at the end of the command if the execution is completed successfully.
2. Create an External command in the Reference Data Management. 
   • The external command must apply to incidents/SR.
   • You must specify the parameters that will be transferred from the request to the script. You can use the F3 key to retrieve the parameters associated with the request or to copy/paste variables that would come from the request form.
   • The command does not have to be visible from the Tools or Actions menus.
3. Create or modify a service request task to run the external command at the appropriate time.
   • In the task of the service request, change the task type for External command.
   • In the Command menu, select the external command to execute.
   • Complete task configuration, such as activation mode, conditions, etc.
4. Use the previously configured SR type to create a request. 
5. Run the ExternalCommandRunner program.
   • The program will determine the number of external command tasks to be executed (active, not started).
   • The program will execute each task sequentially.

   • During the execution of the external command, the task status of the SR will be In progress.

   • When the external command is successfully completed, ExternalCommandRunner completes the task and writes the result of the external command into the completion activity.
   • If the task is in error or its execution timed out, ExternalCommandRunner will create an event with the details of the failure. It will also add the details of the failure directly into an activity in the task and change the task status to Error.
   • The system will continue executing all other command tasks, including newly activated tasks.
6. Review the results of the tasks with the Error status.
   • Refer to the troubleshooting section of this guide to help with your external command tasks.
   • Once the script corrected, use the Relaunch button in the task to run it again.
7. Once everything is working properly, add to a Windows scheduled task to run ExternalCommandRunner automatically.

Troubleshooting

To simplify troubleshooting, we suggest the following practices:

• Use a fairly high level of verbosity in your external commands.
• Start your external commands by writing all the parameters received by Octopus.
• Adjust the execution of the scheduled task in Windows to be slightly longer than the configured timeout (5 minutes by default).
• Prevent the Windows scheduled task from running if an instance is already running to prevent two competing executions.
• Configure a list to review tasks in error and use a custom notification to send a notification to the Service Desk when an error occurs.
• Configure a list of tasks waiting for execution older than a certain time to quickly find a problem with task execution.
• Monitor the Event Management module to find execution problems.

Running PowerShell / VisualBasic Interpreted Script

• If you use scripts that use an interpreter, you should specify the interpreter (cscript.exe, powershell.exe) as the program to invoke and specify the script name in the parameters to be used.
• If you are using PowerShell, you will probably have to adjust the execution policies on the server running ExternalCommandRunner.