API Guide for Data Orchestration for Dell

Introduction

Data Orchestration for Dell (Superna Golden Copy) exposes a GraphQL API for automating archive folder configuration, starting and monitoring copy and recall jobs, and canceling running jobs. This is sometimes referred to informally as "the Golden Copy REST API" in other Superna documentation, but the API itself is implemented as GraphQL over HTTPS, not a traditional REST resource API.

note

This page documents the operations available in the Golden Copy GraphQL API as published by Superna. It does not cover the searchctl and ecactl CLI tools — see the Configuration Guide for CLI-based folder configuration, job management, and monitoring.

Endpoint and Query Format

All queries are issued over HTTPS to any node in the appliance cluster:

https://ip.of.gc.node/graphql

The GraphQL query is passed as a URL-encoded value on the query parameter:

https://ip.of.gc.node/graphql?query=url_encoded_graphql_query

Authentication

Authentication is performed by retrieving a JSON Web Token (JWT) via the login mutation. The token must be included in the Authorization header of all subsequent calls using the Bearer scheme.

Schema:

login(id: String!, pass: String!): LoginResult

type LoginResult {
  user: User!
  token: String!
}

type User {
  name: String!
  role: String!   # USER or ADMIN
}

• id (required) — username, in user@domain.com format. Omit the domain for local users.
• pass (required) — the user's password.

Example request:

curl -s -G -k https://search.igls.com/graphql --data-urlencode 'query={
  login(id:"testuser@exampledomain.com", pass:"NotReal!") {
    user {
      name
    }
    token
  }
}'

Example response:

{
  "data": {
    "login": {
      "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJTSUQ6Uy0xLTUtMjEtMjAxODMyNTY2LTMxODczNTM0MDctMjgyOTk5MTcxMC0xNDQ4Iiwicm9sZSI6IlVTRVIiLCJleHAiOjE1NzAyODk3MTR9.0vs-tnOgs0cOBSYB_SOuNHdmV7NT6YisTwuIbZFMkJE",
      "user": {
        "name": "EXAMPLEDOMAIN\\testuser"
      }
    }
  }
}

Use the returned token on subsequent calls:

Authorization: Bearer <token>

Adding Archived Folders

The addArchivedFolder mutation configures a new archive folder target and returns information about it.

Schema (key arguments):

addArchivedFolder(
  accessKey: String,
  archiveDataAuditCron: String,
  backupNum: String,
  bucket: String,
  cloudtype: String,
  clusterName: String,
  container: String,
  endpoint: String,
  endpointIps: String,
  excludes: String,
  fullCron: String,
  host: String!,
  includes: String,
  incrementalCron: String,
  metaPrefix: String,
  path: String!,
  rateLimit: String,
  region: String,
  secretKey: String,
  skipS3FileExists: String,
  tier: String,
  trashBucket: String
): ArchivedFolderInfo

Key arguments:

• host (required) — name of the source PowerScale/Isilon cluster.
• path (required) — base location on the source file system to archive, starting with /ifs.
• cloudtype — one of aws, azure, ecs, gcs, or other.
• bucket / container — target bucket (or, for Azure, container) name.
• endpoint — URI of the cloud storage endpoint.
• accessKey / secretKey — credentials for the cloud endpoint.
• region — cloud region (required for AWS).
• endpointIps — group of IPs to load balance over (ECS).
• fullCron / incrementalCron / archiveDataAuditCron — cron expressions for scheduled full archive, incremental archive, and data audit jobs.
• includes / excludes — glob syntax to include or exclude files/folders from archiving.
• rateLimit — outbound traffic limit in bytes/sec.
• skipS3FileExists — True/False; skip checking whether the object already exists in cloud storage before uploading.
• tier — cloud storage tier for archiving.
• trashBucket — bucket to use as a trash location for deletions.
• metaPrefix — for other cloud types, the prefix used for custom metadata tags in the payload.
• backupNum — for full backups, the number of independent copies to retain.

The mutation returns an ArchivedFolderInfo object, including the generated id (used in job operations below), cluster, path, and the configuration fields you supplied, along with checksum, lastArchiveDate, and lastFullArchiveDate.

Starting, Viewing, and Canceling Jobs

Start a Full Archive or Recall Job

The gcWalk mutation starts a job. The action argument controls the direction: UPLOAD to archive to cloud storage, GET to recall from cloud storage.

Schema (key arguments):

gcWalk(
  id: String!,
  action: String,
  applyMetadata: Boolean,
  auto_rerun: Boolean,
  csvPath: String,
  endTime: String,
  file: String,
  s3Update: Boolean,
  skipAcls: Boolean,
  skip_meta: Boolean,
  snapshot: String,
  sourcePath: String,
  startTime: String,
  subdir: String,
  targetCluster: String,
  targetPath: String,
  versionsNewerThan: String,
  versionsOlderThan: String
): ProcedureResult

Key arguments:

• id (required) — the archived folder's ID.
• action — UPLOAD (archive) or GET (recall).
• applyMetadata — apply metadata to recalled files.
• auto_rerun — automatically start a rerun job for failures after the main job completes.
• snapshot — read from an existing snapshot rather than creating a new one.
• subdir — folder below the archived folder's path to archive or recall.
• startTime / endTime — date range for date-based recall.
• versionsOlderThan / versionsNewerThan — date range for version-based recall.
• targetCluster / targetPath — recall to a different cluster or destination folder than the original source.
• s3Update — runs the file-system-to-S3 audit function during an archive job.
• skipAcls / skip_meta — skip uploading or recalling ACLs, or owner/group/mode metadata.

Response:

type ProcedureResult {
  jobId: String!
  state: JobState!    # e.g. QUEUED, ARCHIVING, or others
  finishedAt: Long
  message: String
  success: Boolean
  startedAt: Long
}

View Running Jobs

runningSearchJobs(type: String!): [MonitoredJob]

• type — "all" for all jobs, or a specific type such as "GoldenCopy Recall", "Incremental Archive", or "GoldenCopy Archive".

View Job History

jobsHistory(type: String!, folderId: String, tail: Long, kafkaOffset: Long): [MonitoredJob]

• type (required) — same values as runningSearchJobs.
• folderId — filter by folder ID.
• tail — return the most recent number of jobs.
• kafkaOffset — used together with tail to paginate results.

MonitoredJob fields (shared by both queries): jobId, folderId, type, state, startedAt, finishedAt, duration, success, acceptedBytes/acceptedFiles, archivedBytes/archivedFiles, erroredBytes/erroredFiles, skippedBytes/skippedFiles, s3WalkBytes/s3WalkFiles, metaAcceptedFiles, changelistId, changelistFileChangeCount, and hasAutoRerun.

Cancel a Running Job

cancelSearchJob(jobId: String!): [Boolean]

• jobId (required) — ID of the job to cancel. Returns true if the cancel operation succeeded.

See Also

• Configuration Guide – CLI (searchctl) equivalents for folder configuration, job scheduling, and monitoring, plus the Data Orchestration GUI and Cloud Browser.
• Integration Guide – Notification channels, Smart AirGap integration, and a Kafka-based job history export pattern for external systems.