Build and Configure Mainframe Integration Projects

Create mainframe push reservation

Acquires a distributed reservation required for batched mainframe push requests. Validates that the client's snapshot baseline matches the remote state. If drift is detected (canReserve=false), returns conflict details without acquiring a lock. If baseline matches, reserves exclusive access and returns a reservationId valid for 5 minutes.

Features:

  • Distributed reservation locking (Redis-backed TTL of 5 minutes)
  • Preflight fingerprint validation against the current remote snapshot
  • Snapshot drift detection: returns canReserve=false with remote snapshot details on mismatch
  • Hidden/system files are excluded from fingerprint evaluation by default (includeHidden=false)
  • Concurrent push blocking: 409 response if another push already holds the lock
  • Atomic check-and-lock pattern: ensures the baseline matches before the reservation is acquired
  • Heartbeat extension during multi-batch push (each batch extends TTL)

Use Cases:

  • Preflight validation before batching multi-file push to remote
  • Blocking concurrent push attempts to same pipeline
  • Obtaining unique reservationId for multi-phase orchestration
  • Detecting stale local snapshot before starting expensive push operations

Workflow:

  1. Extension computes local snapshot fingerprint
  2. POST /push-reservation with fingerprint
  3. If canReserve=true: proceed with batched push, use reservationId for each batch
  4. If canReserve=false: show snapshot drift with remote files, prompt user for refresh/rebase

Required Permissions: replication-pipeline::create when permission harmonization is enabled; otherwise, replication-pipeline::manage.

post/v1/integration/mainframe/projects/{projectId}/pipelines/{pipelineId}/push-reservation

Request

  • Base URL: https://integration-adapter.connect.cloud.precisely.com
  • URL: https://integration-adapter.connect.cloud.precisely.com/v1/integration/mainframe/projects/{projectId}/pipelines/{pipelineId}/push-reservation
  • Auth: HTTP bearer

Path parameters

projectIdstring required

Unique identifier of the project that owns the pipeline.

pipelineIdstring required

Unique identifier of the pipeline that will receive the reservation.

Query parameters

includeHiddenboolean

Include hidden/system files in push-reservation fingerprint evaluation

Request body

expectedSnapshotFingerprintstring required

Canonical snapshot fingerprint computed by the client from its stored baseline.

Algorithm: SHA-256 over sorted tuples of id|fileName|contentHash, joined by newline. Used to detect remote snapshot drift before acquiring the reservation.

Example request

{
  "expectedSnapshotFingerprint": "4f3dfafda2ddf9753f6d9b7cf5f97f2c81f668f756ad0d6a4c930f725f4f3c8e"
}

Response

Reservation response (acquired or snapshot drift detected)

reservationIdstring

Reservation identifier that must be sent with each push batch.

expiresAtstring date-time

Reservation expiry timestamp. Null if reservation was not acquired.

canReserveboolean

Whether the remote snapshot matches the client baseline.

remoteSnapshotFingerprintstring

Remote snapshot fingerprint currently stored on the adapter side.

Changes

No recorded changes to this operation across all 1 revision of this API.