{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":21971,"path":"integrate-applications/orchestration/t_CreateAnSSHActivity.md","title":"Create an SSH activity","bundle":null,"doc_type":null,"release":"australia","body":"\n# Create an SSH activity\n\nCreate an activity that extracts data from a target host that uses the SSH network protocol.\n\n## Before you begin\n\nRole required: activity\\_creator or workflow\\_admin\n\n## About this task\n\nFor instructions on using the activity template process flow, see [create custom activities](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/orchestration/create-custom-activities.md).\n\n## Procedure\n\n1.  Create a [custom activity](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/orchestration/create-custom-activities.md).\n\n    This action creates a custom activity using a template.\n\n2.  After setting up [general properties](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/orchestration/General-Flds-Templates.md) and [creating input variables](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/orchestration/CreateInputVariables.md), configure the SSH Execution Command.\n\n<table id=\"choicetable_j2l_k2s_d1b\"><tbody><tr><td id=\"d393562e120\">\n\n**[Map the input variables](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/orchestration/CreateInputVariables.md)**\n\n</td><td>\n\nUse the variables you created to configure the command that Orchestration executes.\n\n</td></tr><tr><td id=\"d393562e136\">\n\n**Target host**\n\n</td><td>\n\nHost name or IP address of the target server for this activity.\n\n</td></tr><tr><td id=\"d393562e145\">\n\n**Command**\n\n</td><td>\n\nCommand this activity runs on the target host. You can invoke a MID Server script from this field using any script type that the SSH command line supports. For more information, see **Advanced SSH script options** below the table.\n\n</td></tr><tr><td id=\"d393562e157\">\n\n**Directory**\n\n</td><td>\n\nDirectory on the target host where the command is run.\n\n</td></tr><tr><td id=\"d393562e166\">\n\n**Credential tag**\n\n</td><td>\n\nThe Orchestration credential tag to use when running the command.\n\n</td></tr><tr><td id=\"d393562e176\">\n\n**Required MID Server capabilities**\n\n</td><td>\n\nMID Server with the appropriate capabilities for connecting to the host. By default, the system selects a MID Server with SSH capabilities.\n\n</td></tr><tr><td id=\"d393562e185\">\n\n**Long running**\n\n</td><td>\n\nIf checked, disables the SSH connection timeout for commands that might take longer to run than the default 60 seconds. Orchestration periodically checks the running process to determine its status until it is finished.\n\n</td></tr><tr><td id=\"d393562e194\">\n\n**Must Sudo**\n\n</td><td>\n\nIf checked, enables the use of [sudo](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/r_SSHCredentialsForm.md) to run commands.\n\n</td></tr></tbody>\n</table>    **Note:** You can map parameter values in a test payload to variables in the **Outputs** tab automatically. See [automap output variables](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/orchestration/automap-output-variable-inputs.md).\n\n\n## Advanced SSH script options\n\nTo run a MID Server script on the target host, specify the script type and pass the name of the script into the `${syncFile()}` parameter. The system uses this parameter to locate the named script in the MID Server Script File \\[ecc\\_agent\\_script\\_file\\] table and run it on the target host. For example, a bash script can be expressed as:\n\n```\nbash ${syncFile(\"<MID script name>\")} argument1 argument2 argument3\n```\n\nA base script \\(`main_script.bash`\\) can reference another script \\(`my_include.bash`\\) as well as a separate file \\(`.my_profile`\\) located on the target host. Both scripts and the file referenced must be synced to the MID Server, using the `${syncFile()}` parameter, to execute properly.\n\n```\nsource ${syncFile(\".my_profile\")}\ncp ${syncFile(\"my_include.bash\")} /usr/ssmith/my_include.bash\nbash ${syncFile(\"main_script.bash\")} one two three four five six \nrm /usr/ssmith/my_include.bash\n```\n\nA Python example with inline comments might look like this:\n\n```\nset $LIB_DIR=/usr/bin;. \n# Sync a file that is referenced inside myF5CreateLBPool.py \ncp ${syncFile(\"specialFunctions.py\")} ~/specialFunctions.py \n# set up environment variables \nsource ${syncFile(\".python_profile\")} \n# call script that sets up dependencies on the box from remote package repos \npython ${syncFile(\"setupPythonDependencies.py\")} pycontrol \n# call a script that requires functions from the package as well as a function from myIncludedFile \npython ${syncFile(\"myF5CreateLBPool.py\")} snow_pool myActualValue \n# user is responsible for their own cleanup \nrm ~/specialFunctions.py \n```\n\n## What to do next\n\n-   Use [auto-mapping](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/orchestration/automap-output-variable-inputs.md) to generate outputs and parsing rules\n-   If you do not use auto-mapping, you can manually [create output variables](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/orchestration/t_CreateAnOutputVariable.md) and [create parsing rules](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/orchestration/t_CreateAParsingRule.md)\n\n**Parent Topic:**[Orchestration custom activity templates](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/orchestration/c_ActivityDesignerComponents.md)\n\n## SSH template execution parameters\n\nUse execution parameters to create the input process script in the **Pre Processing** form of the activity designer.\n\nFor descriptions of the command fields, see [Configure the SSH execution command](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/orchestration/t_CreateAnSSHActivity.md).\n\n**Note:** You must use the `executionParam.` prefix with all variables in this table.\n\n<table id=\"table_wl1_yxc_dr\"><thead><tr><th>\n\nName\n\n</th><th>\n\nVariable\n\n</th><th>\n\nType\n\n</th><th>\n\nUsage\n\n</th></tr></thead><tbody><tr><td>\n\nSource\n\n</td><td>\n\nsource\n\n</td><td>\n\nString\n\n</td><td>\n\nIntended target or host.\n\n</td></tr><tr><td>\n\nCommand\n\n</td><td>\n\ncommand\n\n</td><td>\n\nString\n\n</td><td>\n\nComment to run on the host.\n\n</td></tr><tr><td>\n\nDirectory\n\n</td><td>\n\ndirectory\n\n</td><td>\n\nString\n\n</td><td>\n\nDirectory on the host in which to run the command.\n\n</td></tr><tr><td>\n\nCredential tag\n\n</td><td>\n\ncredential\\_tag\n\n</td><td>\n\nString\n\n</td><td>\n\nOrchestration credential tag to use when running the command.\n\n</td></tr><tr><td>\n\nMidCapabilities\n\n</td><td>\n\nmidCapabilities\n\n</td><td>\n\nString \\(comma separated\\)\n\n</td><td>\n\nList of required MID Server capabilities.\n\n</td></tr><tr><td>\n\nValueCapabilities\n\n</td><td>\n\nvalueCapabilities\n\n</td><td>\n\nArray of hashmap\n\n</td><td>\n\nCapability values used to select the MID Server. For more information, see [MID Server capabilities](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/servicenow-platform/t_ConfigureCapabilities.md). If there are additional capabilities that are assigned by value, use this example to customize the MID Server selection:```\nvar valueCapability = {'NEW_MID_CAPABIILTY':'NEW_MID_CAPABILITY_VALUE'};\nexecutionParam.valueCapabilities.push(valueCapability);\n```\n\n</td></tr><tr><td>\n\nLong running\n\n</td><td>\n\nlong\\_running\n\n</td><td>\n\nBoolean\n\n</td><td>\n\nIndicates whether or not the command is long running. A value of true indicates that the command is long running.\n\n</td></tr><tr><td>\n\nMust sudo\n\n</td><td>\n\nmust\\_sudo\n\n</td><td>\n\nBoolean\n\n</td><td>\n\nIndicates whether or not this activity must use sudo to run root commands. A value of true indicates that [sudo](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/r_SSHCredentialsForm.md) [SSH credentials](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/r_SSHCredentialsForm.md) must be used.\n\n</td></tr></tbody>\n</table>## SSH post-processing parameters and payload parsing\n\nUse these parameters to create a post-processing script, payload parsing, and tagging.\n\n<table id=\"table_nzv_q1d_dr\"><thead><tr><th>\n\nName\n\n</th><th>\n\nVariable\n\n</th><th>\n\nType\n\n</th><th>\n\nUsage\n\n</th></tr></thead><tbody><tr><td>\n\nOutput\n\n</td><td>\n\noutput\n\n</td><td>\n\nString\n\n</td><td>\n\nContains the output returned from the SSH command.\n\n</td></tr><tr><td>\n\nEccSysID\n\n</td><td>\n\neccSysID\n\n</td><td>\n\nString\n\n</td><td>\n\nContains the reference ID associated with the ECC Queue input message returned by the activity.\n\n</td></tr><tr><td>\n\nErrorMessages\n\n</td><td>\n\nerrorMessages\n\n</td><td>\n\nString\n\n</td><td>\n\nContains the error messages retrieved from the SSH command. This value is **null** if there are no error messages.\n\n</td></tr><tr><td>\n\nTags\n\n</td><td>\n\ntags\n\n</td><td>\n\nHashmap of tag values returned from the SSH command\n\n</td><td>\n\nContains the tags used to extract output using the SSH commands. The tag output is delimited by double percentage signs, as in `%%tagname%% … %%`. Set up the command using the following format:```\n%%tagname1%%\noutput1 line 1\noutput1 line 2\n…\n%%\n\n%%tagname2%%\noutput2 line 1\noutput2 line 2\n…\n%%\n```\n\nThe tags returned are JavaScript hashmap objects in which each key is prefixed with `tag` appended with the tagname.```\n{\"__text__\": \"\", \n\"tagtagname1\":\"output1 line1\\noutput1 line2\\n\", \n\"tagtagname2\":\"output2 line1\\noutput2 line2\\n\"}\n```\n\n</td></tr></tbody>\n</table>## Configure the SSH execution command\n\nUse the input variables you created to configure the command that Orchestration executes on the host target.\n\n### Before you begin\n\nCreate the input variables you need in the **Inputs** form before you advance to the **Execution Command** stage.\n\nRole required: activity\\_creator, admin\n\n**Note:** You can test the SSH connection between the MID Server and the target without having to run the acvitity in a workflow context. For details, see test template outputs.\n\n### Procedure\n\n1.  Drag variables from the list of inputs and drop them into command fields.\n\n    The system formats the variable in the proper syntax for the command.\n\n    \\[Omitted image \"SSHExecutionCommand.png\"\\] Alt text: SSH execution command\n\n2.  Complete the fields shown in the table.\n\n<table id=\"table_xf4_kvc_dr\"><thead><tr><th>\n\nField\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nInput\n\n</td><td>\n\nInput variable builder. [Create input variables](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/integrate-applications/orchestration/CreateInputVariables.md) to map to available fields.\n\n</td></tr><tr><td>\n\nTarget host\n\n</td><td>\n\nHost name or IP address of the target server for this activity.\n\n</td></tr><tr><td>\n\nCommand\n\n</td><td>\n\nCommand this activity runs on the target host. You can invoke a MID Server script from this field using any script type that is supported by the SSH command line. For more information, see **Advanced SSH script options** below the table.\n\n</td></tr><tr><td>\n\nDirectory\n\n</td><td>\n\nDirectory on the target host where the command is run.\n\n</td></tr><tr><td>\n\nCredential tag\n\n</td><td>\n\nThe [Credential aliases for Orchestration activities](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/c_AssignCredsOrchActivities.md) to use when running the command.\n\n</td></tr><tr><td>\n\nSelect MID Server by capabilities\n\n</td><td>\n\nMID Server with the appropriate capabilities for connecting to the host. By default, the system selects a MID Server with SSH capabilities\n\n</td></tr><tr><td>\n\nLong running\n\n</td><td>\n\nCheck box to disable the SSH connection timeout for commands that might take longer to run than the default 60 seconds. Orchestration periodically checks the running process to determine its status until it is finished.\n\n</td></tr><tr><td>\n\nMust Sudo\n\n</td><td>\n\nCheck box to allow the use of [SSH credentials](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/r_SSHCredentialsForm.md) to run commands.\n\n</td></tr></tbody>\n</table>3.  Click **Save**.\n\n4.  Click **Continue** to advance to the **Outputs** stage.\n\n\n"}}