SCP adapter request and response for a put action

To configure an adapter request to communicate with a host that is not defined in the adapter configuration, you can designate a dynamic target by assigning values for the required configuration elements. These elements work as a set. You cannot retrieve partial information from the configuration node.

You can omit the <targets> block from the adapter request. In the absence of a <targets> block, the default target from the adapter configuration is used.

When you use a context item as an input for an adapter request, you must enclose the adapter request in the <request-data> elements. However, when you create a static request, <request-data> is not required and the adapter request starts with the <adapterName-adapter-request> element.

BMC recommends that you do not include unused elements in the adapter request because they might cause errors. The following table describes the elements of an SCP adapter request with a put action.

Elements of an SCP adapter request with a put action

Element	Description	Required
`<targets>`	Contains the `<target>` elements	Conditional; required if a target is referenced or defined in the request
`<target>`	Contains a `name` attribute that references a configuration node from the adapter configuration or contains the elements that define a dynamic target If not provided, the default target in the adapter configuration is used.	Conditional; required if a target is referenced or defined in the request
`<host>`	Specifies the host name or the IP address of the remote host	Conditional; required when defining a dynamic target
`<port>`	Specifies the port on which the remote host listens This element applies to a dynamic target. Default value: 22	Conditional
`<user-name>`	Specifies the user name to be used for remote host authentication This element applies to a dynamic.	Conditional; required when defining a dynamic target
`<password>`	Specifies the password that corresponds to the `<user-name>` specified The `<private-key-file>` element is used if you do not provide the `<password>` element. The `<password>` element can contain an `encryption-type` attribute.	No
`<encryption-type>`	Indicates whether the password specified is encrypted; is an attribute of the `<password>` element, not an element itself Valid values: Base64, Plain (default)	No
`<private-key-file>`	Identifies the path and the file name for the local SSH key file This file is used when performing public key authentication. The path and file must exist on the peer servicing the adapter request	Conditional; can be used in the absence of a `<password>` element
`<pass-phrase>`	Identifies the passphrase that is used to protect the private key file This element can contain an `encryption-type` attribute.	Conditional; can be used in the absence of a `<password>` element
`<encryption-type>`	Indicates whether the passphrase specified is encrypted; is an attribute of the `<pass-phrase>` element, not an element itself Valid values: Base64, Plain (default)	No
`<timeout-secs>`	Specifies the time, in seconds, to wait for the expected prompt to return If the expected prompt is not returned before the specified period has elapsed, an error message is returned Default value: 60 seconds	No
`<known-hosts-config>`	Identifies the path to the local known_hosts file This file is used when performing key verification. This element applies to a dynamic target Default path: homeDir/.ssh/known_hosts	Conditional
`<allow-unknown-hosts>`	Determines whether a connection must continue if the key verification fails This element applies to a dynamic target. Valid values: true (default), false With a value of true, the connection is maintained when connecting to an unknown or mismatched system. With a value of false, the connection is dropped and the adapter response returns an error	Conditional
`<preferred-pk-algorithm>`	Specifies the preference of the algorithm used to encrypt the public key This element applies to a dynamic target Valid values: ssh-dss, ssh-rsa (default)	Conditional
`<establish-connection-timeout-secs>`	Specifies the time, in seconds, to wait for user authentication on the target server If authentication is not successful within this time, an error message is returned Default value: 60 seconds	No
`<network-environment>`	Creates an extra channel session for use with Sun Solaris 9 This value must be false when connecting to network appliances. Valid values: true, false (default)	No
`<local-file>`	Specifies the local file path This is the file source for the put action	Yes
`<remote-file>`	Specifies the remote file path This is the destination file for the put action	Yes

The following figure shows an XML template of the adapter request for the SCP adapter with a put action.

XML template of the SCP adapter request with a put action


<scp-request>
   <targets>
     <target name=""/>
     <target>
       <host></host>
       <port></port>
       <user-name></user-name>
       <password encryption-type=""></password>
       <timeout-secs></timeout-secs>
       <known-hosts-config></known-hosts-config>
       <allow-unknown-hosts></allow-unknown-hosts>
       <preferred-pk-algorithm></preferred-pk-algorithm>
       <establish-connection-timeout-secs></establish-connection-timeout-secs>
       <network-environment></network-environment>
     </target>
     <target>
       <host></host>
       <port></port>
       <user-name></user-name>
       <private-key-file></private-key-file>
       <pass-phrase encryption-type=""></pass-phrase>
       <timeout-secs></timeout-secs>
       <known-hosts-config></known-hosts-config>
       <allow-unknown-hosts></allow-unknown-hosts>
       <preferred-pk-algorithm></preferred-pk-algorithm>
       <establish-connection-timeout-secs></establish-connection-timeout-secs>
       <network-environment></network-environment>
     </target>
   <targets>
   <local-file></local-file>
   <remote-file></remote-file>
</scp-request>

The following figure shows an XML sample of the adapter request for the SCP adapter with a put action. In this sample, the first target references the adapter configuration and the second target is a dynamic target.

XML sample of the SCP adapter request with a put action


<scp-request>
   <targets>
     <target name="host1"/>
     <target>
       <host>server2</host>
       <port>2200</port>
       <user-name>user</user-name>
       <password encryption-type="Plain">test</password>
       <timeout-secs>90</timeout-secs>
       <known-hosts-config>/path/to/known_hosts</known-hosts-config>
       <allow-unknown-hosts>false</allow-unknown-hosts>
       <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm>
       <establish-connection-timeout-secs>90</establish-connection-timeout-secs>
       <network-environment>true</network-environment>
     </target>
     <target>
      <host>server3</host>
      <port>2200</port>
      <user-name>user1</user-name>
      <private-key-file>/path/to/SSH key file</private-key-file>
      <pass-phrase encryption-type="Base64">cGFzczE=</pass-phrase>
      <timeout-secs>90</timeout-secs>
      <known-hosts-config>/path/to/known_hosts</known-hosts-config>
      <allow-unknown-hosts>false</allow-unknown-hosts>
      <preferred-pk-algorithm>ssh-dss</preferred-pk-algorithm>
      <establish-connection-timeout-secs>90</establish-connection-timeout-secs >
      <network-environment>true</network-environment>
   </target>
   </targets>
   <local-file>/path/to/file/filename</local-file>
   <remote-file>/path/to/file/filename</remote-file>
</scp-request>

The put action request for a SCP adapter returns an adapter response containing the summary information for the action.

The following table describes the elements of an SCP adapter response to a request with a put action.

Elements of an SCP adapter response to a request with a put action

Element	Description
`<request-metadata>`	Contains the request level summary information
`<status>`	Indicates the status of the request Valid values: success, error
`<error>`	Indicates the error message returned when the value of the `<status>` element is error When the value of the `<status>` value is success, this element is absent.
`<targets-output>`	Contains the command output for all the targets
`<target-output>`	Contains the command output for a specific target The `host` attribute provides the host name or the IP address of the target computer.
`<target-metadata>`	Contains the target level summary information
`<request-action>`	Indicates the action performed by the request
`<execution-milliseconds>`	Specifies the duration of the execution, in milliseconds
`<local-file>`	Specifies the source file for the put command
`remote-file>`	Specifies the destination file for the put command
`<status>`	Indicates the status of the target connection Valid values: success, error
`<error>`	Contains the error message if a target level error When the value of the `<status>` element is success, this element is absent. Note: If the transfer is interrupted, a partial file might exist in the destination location.
`<output>`	Contains lines that result from the command This command does not return a detailed response.

The following figure illustrates an XML sample of the adapter response for the SCP adapter with a put action.

XML sample of the SCP adapter response with a put action


<scp-command-output>
   <request-metadata>
     <status>success</status>
     <error>Present only with status of 'error'</error>
   </request-metadata>
   <targets-output>		
     <target-output host="server1">
     <target-metadata>
       <request-action>put</request-action>
       <execution-milliseconds>4000</execution-seconds>
       <local-file>/path/to/file/filename</local-file>
       <remote-file>/path/to/file/filename</remote-file>
       <status>success</status>
       <error>Present only with status of 'error'</error>
     </target-metadata>
     <output/>
     </target-output>
   <targets-output>		
</scp-command-output>

SCP adapter request and response for a put action

Comments