Write remote file

Creates a file on a target node from text you type into the op. The contents are written to a temporary file on the Clarive server, then transferred to the node over the server resource's agent connection. The temporary copy is cleaned up when the job process exits.

Reach for it when the file only exists inside the rule: a batch script, a single SQL statement, a small config that changes per environment. When the file already sits on disk, or when you are sending a whole directory, use Ship File Remotely instead. Everything this op does locally is described on Write local file.

The form has two tabs. Settings holds what you need every time; Advanced holds the backup, rollback and encoding choices.

Settings

Server

The node to write to. Required; the rule will not save without it.

The list offers server resources that can take an agent connection, plus entries shown as variable: ${name}. Picking a variable defers the choice to run time: whatever resource the variable holds when the job reaches this op is the one written to. A variable holding several resource ids separated by commas writes the same file to each of them in turn.

An inactive server resource is skipped with a warning in the log and the op still reports success. When every selected server is inactive, the op does nothing at all and the job carries on. A variable that resolves to nothing at run time is a different case: the op stops the job with a server-not-configured error.

User

Account to connect as, overriding the user configured on the agent. Leave it blank to use the agent's own setting, which is the normal case.

Backups are filed under the account name paired with the server, so changing User between the forward run and the rollback points the rollback at a backup directory that was never filled.

Remote path

Full path of the file on the node, including the file name. Required.

The directory part is created on the node when it does not exist. The file name part is what the file is called once it lands. A trailing slash does not mark it as a directory: the last segment is taken as the file name either way, so /opt/foo/ writes a file called foo under /opt.

This field is expanded twice. First against the job stash, so ${deploy_path}/app.cfg works. Then against the attributes of each server being written to, which gives you ${hostname}, ${os} and any custom parameter defined on that server resource. That second pass is what lets one op write to a per-machine path across several nodes.

Use forward slashes even for Windows targets. Backslashes inside the path confuse the agent's quoting on some platforms.

Line Endings

original, LF (Unix) or CRLF (Windows), applied to the contents before the transfer. Defaults to original.

The rule editor saves what you type with Unix line endings, so a .bat or .cmd file written to a Windows node needs CRLF (Windows) to run correctly. This is the single most common cause of a remote script that fails with an unreadable error.

Template Use

No Template or Template Toolkit. Defaults to No Template.

${var} placeholders in the contents are expanded whichever you pick. Template Toolkit adds [% %] directives on top. A template error stops the job before anything is sent.

Template Var

Appears only when Template Use is Template Toolkit. Names a stash variable holding a hash whose keys become the template variables. Blank exposes the whole stash.

Contents

The body of the file, typed into a code editor. ${var} and ${nested.path} are replaced from the stash. Write $${something} to put a literal ${something} into the file, which matters for shell and batch scripts that use similar syntax of their own.

Advanced

Backup Mode

Choice	Effect
No Backup	nothing is copied back before the write
Backup Existing Files	the current remote file is pulled to the job's backup area first
Backup Existing Files or Fail	no backup is taken

Backup Existing Files is the default, so an op you never opened the Advanced tab on is already taking backups.

The backup is fetched once per remote path, only on a forward run, and only under Backup Existing Files. If the remote file does not exist yet, the log notes that there was nothing to back up and the write proceeds.

Backup Existing Files or Fail reads like a stricter version of the middle option, but no backup is taken under it, which means a later rollback has nothing to restore. Use Backup Existing Files when you intend to roll back.

A backup that cannot be read logs a warning and the write continues.

Rollback Mode

Only consulted when the job is running its rollback pass.

Choice	Effect on rollback
No Rollback	the op writes the same contents again
Rollback from local files if exist	restore the backup; if there is no backup, delete the remote file
Must Rollback from local files	restore the backup; if there is no backup, fail the job

The middle choice is the default and the one that surprises people. No backup means the file did not exist before the job touched it, so rolling back removes it from the node. That is usually what you want, and it is destructive if the file was actually created by something other than this job.

Must Rollback from local files turns the same situation into a job failure instead, which is the safer choice when the file must always exist on the node.

Exist Mode Local

Skip if no files were found or Fail if no files were found. Defaults to skip.

This guards the local side of the transfer. Since this op writes its own temporary file immediately beforehand, there is always exactly one file to send, so neither choice changes anything in practice. The setting matters on Ship File Remotely, where the local side is a path you supply.

Exist Mode Remote

Skip, if file already sent by any task in job chain or Reship, even file has already been shipped to node. Defaults to skip.

The skip check matches on the exact local file that is being sent. This op creates a fresh temporary file on every run, so the check almost never matches and the file is transferred each time. Treat this op as always sending.

File Encoding

Encoding used when the temporary file is written, before transfer. Defaults to utf-8. Set it to cp1252, latin1 or a mainframe code page when the node expects those bytes.

Content Encoding

Describes the text you typed. Defaults to utf-8. Conversion happens only when it differs from File Encoding, and mixing the two is the usual cause of mangled accented characters on the target. Leave both alike unless you have checked the result on the node.

Log Body

Don't print body to log or Print body in log. Defaults to not printing.

Printing attaches the full contents to the job log, after substitution. Useful while building the rule, risky afterwards: anything secret in Contents becomes readable by everyone who can open the job.

Transfer behaviour

Files of 1 MB or more going to a Clarive agent are split into parts, sent one at a time and joined back together on the node. The log says Sending files by parts followed by the command used to rejoin them. Nothing about this is configurable from this form.

The log records Sending file ... to ... and a Shipped N files to server ... summary per server, with the per-file detail attached as data. A transfer error names the server and stops the job.

Every file sent marks the step as needing rollback unless you go to the op's Options tab and set Needs Rollback? to No Rollback Necessary. That mark is what pulls the step into the rollback pass when something later in the job fails, and it is on for an op whose Options tab you never touched. Rollback Mode then decides what the rollback does to the file.

Combining with other ops

Write the script, then execute it with Run a Remote Script pointed at the same node and path. That pairing is the standard way to run something on a node that has no Clarive tooling of its own.

To read a file back off the node afterwards, use Retrieve a remote file. To create the target directory ahead of time when you need specific permissions on it, the agent-based ops in the palette can do that before this op runs.

To write across a set of nodes held in the stash, put this op inside FOREACH CI and point Server at the loop variable, or select a variable resource that resolves to the whole list.

Guard the whole thing with IF ROLLBACK when the rollback pass needs to do something other than restore the file.

Examples

A cleanup batch file written to a Windows node and then run by a following op.

Server           win_node_bar
Remote path      d:/foo/cleanup.bat
Line Endings     CRLF (Windows)
Backup Mode      No Backup
Rollback Mode    No Rollback
Contents         @ECHO OFF
                 for /f "delims=" %%i in ('dir /b ${deploy_path}') do del /q "%%i"

A config file replaced in place, with the previous version kept so the job can put it back.

Server           ${app_nodes}
User             (blank)
Remote path      /opt/myapp/conf/app.properties
Line Endings     LF (Unix)
Backup Mode      Backup Existing Files
Rollback Mode    Must Rollback from local files
File Encoding    utf-8
Contents         app.env=${env}
                 app.db=${db_url}

A SQL statement built earlier in the rule and dropped on a database host.

Server           db_host_foo
Remote path      /home/baz/tmp.sql
Backup Mode      No Backup
Log Body         Print body in log
Contents         ${final_sql}