Skip to main content

Sync to IBM i

After a task is approved, Sync to IBM i writes the changed source files directly to a target IBM i library as native source members. The same flow can also deploy Profound UI htdocs files to the IBM i IFS. Use it to push agent-produced code into traditional source-member-based change management on IBM i.

This page covers what sync does, how to invoke it, and the rules it uses to map files into source members. For the prior step (approving the task) see Approval & Deployment. For configuring the IBM i connection that enables sync, see IBM i Connections.

Prerequisites​

  • The environment has an IBM i connection with the Sync feature, the Profound UI htdocs Files feature, or the Agentic Display Files feature enabled. See IBM i Connections.
  • The task has been approved. Sync is unavailable on running, queued, or unapproved tasks.
  • The task container is running. Sync executes inside the task's container, which holds the changed files.
  • The task is not an Import IBM i Sources or Generate IBM i Build Rules task. Sync is hidden on those because their work product is files in Git, not edits to push back to IBM i.

Sync / Deploy Credentials​

Both source-member sync and Profound UI htdocs deploy share the connection's Sync / deploy credentials setting:

  • Prompt (default for new connections) — You enter a user profile and password in the dialog every time. The password is used once to open the SSH connection and is never stored.
  • Connection — Sync and deploy reuse the SSH user and key already configured on the connection. No additional credentials are needed at runtime. This mode requires the connection to also have the SSH feature enabled.

The mode is set under Environments → Connections on the IBM i connection.

Syncing from the Approval Dialog​

Sync can run as part of the approval step:

  1. Click Approve on a completed task.
  2. Check Sync to IBM i. The section appears when source-member sync, Profound UI htdocs deploy, or Agentic Display Files is configured.
  3. Enter a library name if syncing source members. Library names are 1–10 characters, letters/digits and @, #, $, or _. The name is uppercased automatically.
  4. If the connection is in Prompt mode, enter your user profile and password.
  5. Select files to sync from the file tree.
  6. Click Commit Changes. Approval runs first; sync starts automatically once the commit succeeds.
  7. A live log streams the sync progress.

The library is created on the IBM i system if it doesn't already exist. Source physical files are created as needed inside the library.

Syncing After Approval​

If you approved without syncing, want to sync to a different library, or completed a follow-up turn that introduced new changes, you can run sync from the task detail page.

  1. Click the Sync to IBM i / Deploy htdocs button (top-right actions). The button label depends on which kinds of files are in scope:
    • Sync to IBM i — source members only.
    • Deploy htdocs — Profound UI htdocs files only.
    • Sync to IBM i & Deploy htdocs — both.
  2. Enter the library name when syncing source members.
  3. If the connection requires prompted credentials, enter your user profile and password.
  4. Select files from the file tree. The deploy htdocs target IFS path is shown in the dialog when applicable.
  5. Click Sync, Deploy, or Sync & Deploy to start.

When both source sync and htdocs deploy run together, source sync runs first, then htdocs deploy.

The button appears when:

  • The task is approved.
  • The environment has an IBM i connection with Sync, Profound UI htdocs Files, or Agentic Display Files enabled.
  • There are eligible changed files of the matching kind, and either the matching action hasn't run yet or the task has new work since the last run (a follow-up turn finished after the previous sync/deploy).

File Selection​

The dialog shows a tree of all files changed by the task. Files are pre-selected when their extension matches a known IBM i source type (RPGLE, CLLE, DSPF, PF, LF, PRTF, SQL, BND, MSGF, BNDDIR, etc.).

Files that can't be IBM i source members are disabled in the tree. The most common reasons are:

  • Member name (filename without extension) longer than 10 characters.
  • Source physical file name (parent directory) longer than 10 characters.
  • A non-source extension (.md, .json, .yml, .html, .css, .js, image and archive formats).
  • A non-source filename (.gitignore, Dockerfile, Makefile, etc.).

Profound UI htdocs files (any file under htdocs/profoundui/ in the task workspace) are always shown in the deploy section, never the source-member section, even when no deploy connection is configured.

How Files Map to Source Members​

The sync script derives the source physical file, member, and source type purely from the file path:

Path partBecomes
Parent directory (uppercased)Source physical file (SRCPF)
Filename stem (uppercased, before first .)Member name
File extension (uppercased)Source type

Example: app/qrpglesrc/customer.rpgle → LIBRARY/QRPGLESRC(CUSTOMER) source type RPGLE.

The library and source physical file are created automatically if they don't exist:

  • CRTLIB LIB(<library>) TEXT('CoderFlow task <task-id>')
  • CRTSRCPF FILE(<library>/<srcpf>) RCDLEN(112)

If the member exists, sync updates its source type with CHGPFM and overwrites its content. If it doesn't exist, sync creates it with ADDPFM. Member content is written through Rfile -Qw so newlines and column 1 alignment match IBM i conventions.

Member Text Descriptions (@MBRTEXT)​

Sync looks for an @MBRTEXT: comment in the first five lines of each file and, when present, sets it as the member's TEXT() description (truncated to 50 characters). The comment syntax depends on the source type — for example, /* @MBRTEXT: ... */ for CL, // @MBRTEXT: ... for ILE RPG, or * @MBRTEXT: ... in column 7 for DDS and fixed-format RPG.

This is the round-trip companion to the Insert member text descriptions option in Import IBM i Sources. When that option imports a member, the original IBM i TEXT() description is preserved as an @MBRTEXT: line; sync reads that line back and re-applies it to the member.

Files without an @MBRTEXT: line are synced with an empty TEXT() description.

Source Member Collisions​

If two selected files would resolve to the same (SRCPF, MEMBER) pair — for example qrpglesrc/foo.rpgle and qrpglesrc/foo.dspf both target QRPGLESRC/FOO — sync rejects the request before transferring anything. Either rename one of the files or unselect one in the dialog.

Rich Display Files (.json)​

Rich Display files (Profound UI EJS-template .json files and traditional RDF .json files) live in the repo as JSON but on IBM i must exist as DSPF source members containing DDS. When sync sees a .json file selected for sync, it:

  1. Reads the file from the task container.
  2. Classifies it as EJS or RDF.
  3. Converts it to DDS using @profoundlogic/codermake.
  4. Stages the resulting .dspf file inside the container.
  5. Syncs the staged .dspf as a regular DSPF member.

.json files that aren't recognized Rich Displays are dropped with a warning in the sync log. The original .json is left untouched in the repo — only the converted DDS is synced. If conversion fails, the warning explains why.

Profound UI htdocs Deploy​

When the IBM i connection has the Profound UI htdocs Files or Agentic Display Files feature enabled, files under htdocs/profoundui/ in the task workspace can be deployed to the IBM i IFS. The connection's PUI htdocs Path (for example /www/myinstance/htdocs) is the deploy root; the path below htdocs/ in the workspace is preserved on the target.

For example, with pui_htdocs_path = /www/myinstance/htdocs:

Workspace pathIFS target
app/htdocs/profoundui/userdata/css/theme.css/www/myinstance/htdocs/profoundui/userdata/css/theme.css
app/htdocs/profoundui/userdata/ui/login.html/www/myinstance/htdocs/profoundui/userdata/ui/login.html

Only files under htdocs/profoundui/ are eligible. Anything outside that directory is ignored for deploy (and goes through the normal source-member sync path if eligible).

Sync Log and Stale Indicators​

After a sync completes, the task records:

  • The library name written to.
  • A timestamp.
  • A link to the full sync log.

For Profound UI deploy the same metadata is recorded for the deploy operation.

If the task completes a new turn after the last sync (a follow-up that produced more changes), the sync is marked stale and the Sync to IBM i button reappears. The same applies to deploy htdocs. Re-running sync sends only the currently-changed files; it does not re-send anything that hasn't moved since.

Authentication and Authorization​

Sync runs bash sync_to_ibmi.sh inside the task container, which opens an SSH connection back to IBM i. Authentication depends on the credentials mode:

  • Connection mode — uses the SSH user and key configured on the connection. No password is sent.
  • Prompt mode — uses sshpass with the prompted user and password. The password is held in container memory only for the SSH handshake and is unset immediately after the master connection opens.

In both modes the IBM i user profile must have authority to:

  • Create the target library (CRTLIB) — or *USE and *ADD on a pre-existing library.
  • Create source physical files (CRTSRCPF) and members (ADDPFM) in the library.
  • Run Rfile from QShell to write member content.

If authentication fails, the sync log reports the failure and the operation exits with a distinct error so the UI can prompt for credentials again.

Notes​

  • Sync runs over a single multiplexed SSH connection, so successive operations within one sync don't pay multiple TCP/auth round-trips.
  • Sync to IBM i is task-scoped — there is no environment-wide bulk sync. To sync across tasks, sync each task individually.
  • Sync writes only the files you select. It does not delete members on IBM i for files removed from the repo; member deletion is a manual operation.