Creates and enqueues a batch job for asynchronous processing.

POST /batch/jobs

Operation id: BatchService_CreateBatchJob

Description

The job creates new data records or updates existing ones based on the provided data. If a record with the same key/value pair already exists, the system will only update a specific subset of mutable fields unless 'replace_existing' is set to true.

Supported upload formats for FSS uploads include CSV, XLS, and XLSX.

For updates to existing Hierarchies, note that only the lowest tier is allowed to be removed.

Permission Level: Read-Write

Tags: BatchService

Security

• Authorization (apiKey)
  • Bearer token

Responses

200 — A successful response.

Content type: application/json

default — An unexpected error response.

Content type: application/json

Request body

Required: Yes

application/json

Schema

{
  "type": "object",
  "properties": {
    "tenantId": {
      "type": "string"
    },
    "jobName": {
      "type": "string"
    },
    "importType": {
      "type": "string",
      "description": "The type of data being imported.\n\n - LOCATIONS: The import file is forwarded directly to the zac-server locations API\nConstraints:\n  - template_name, deviation, and dry_run are all ignored.\n  - zac-server performs an upsert always, any errors in the file will fail the entire file",
      "enum": [
        "USERS",
        "ROLES",
        "WORKSPACES",
        "SITES",
        "DEPARTMENTS",
        "HIERARCHIES",
        "SITE_TEMPLATES",
        "PERMISSION_TEMPLATES",
        "GROUPS",
        "LOCATIONS"
      ],
      "default": "USERS"
    },
    "templateName": {
      "type": "string"
    },
    "ignoreHeader": {
      "type": "boolean"
    },
    "replaceExisting": {
      "type": "boolean",
      "description": "Boolean value to replace existing Users upon upload. Not supported for Permission Templates upload type Required = false."
    },
    "file": {
      "type": "object",
      "description": "This protobuf message represents any file through an array of bytes.",
      "properties": {
        "content": {
          "type": "string",
          "format": "byte"
        }
      }
    },
    "signedUrl": {
      "type": "string",
      "description": "A signed URL for a GCS bucket. Required: false."
    },
    "sftpDetails": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string"
        },
        "port": {
          "type": "integer",
          "format": "int32"
        },
        "directory": {
          "type": "string"
        },
        "fileName": {
          "type": "string"
        },
        "username": {
          "type": "string"
        },
        "password": {
          "type": "string"
        },
        "sshKey": {
          "type": "string"
        }
      }
    },
    "fssId": {
      "type": "string"
    },
    "gcsDetails": {
      "type": "object",
      "description": "GCS Details are used for granting access to a GCS bucket for us to read the file from.",
      "properties": {
        "projectId": {
          "type": "string"
        },
        "bucketName": {
          "type": "string"
        },
        "keyFile": {
          "type": "string"
        },
        "fileName": {
          "type": "string"
        }
      }
    },
    "emails": {
      "type": "array",
      "description": "Email(s) to be sent upon Job completion/failure.",
      "items": {
        "type": "string"
      }
    },
    "deviation": {
      "type": "integer",
      "format": "int32"
    },
    "dryRun": {
      "type": "boolean"
    }
  }
}

Response models

200 — A successful response.

Content type: application/json

Schema

{
  "type": "object",
  "properties": {
    "tenantId": {
      "type": "string"
    },
    "jobName": {
      "type": "string"
    },
    "importType": {
      "type": "string",
      "description": "The type of data being imported.\n\n - LOCATIONS: The import file is forwarded directly to the zac-server locations API\nConstraints:\n  - template_name, deviation, and dry_run are all ignored.\n  - zac-server performs an upsert always, any errors in the file will fail the entire file",
      "enum": [
        "USERS",
        "ROLES",
        "WORKSPACES",
        "SITES",
        "DEPARTMENTS",
        "HIERARCHIES",
        "SITE_TEMPLATES",
        "PERMISSION_TEMPLATES",
        "GROUPS",
        "LOCATIONS"
      ],
      "default": "USERS"
    },
    "status": {
      "type": "string",
      "enum": [
        "UNKNOWN_STATUS",
        "PENDING",
        "IN_PROGRESS",
        "SUCCEEDED",
        "SUCCEEDED_WITH_ERRORS",
        "FAILED"
      ],
      "default": "UNKNOWN_STATUS"
    },
    "message": {
      "type": "string"
    },
    "startTime": {
      "type": "string",
      "format": "date-time"
    },
    "endTime": {
      "type": "string",
      "format": "date-time"
    },
    "fssId": {
      "type": "string"
    },
    "instanceId": {
      "type": "string"
    },
    "historicalJobs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "UNKNOWN_STATUS",
              "PENDING",
              "IN_PROGRESS",
              "SUCCEEDED",
              "SUCCEEDED_WITH_ERRORS",
              "FAILED"
            ],
            "default": "UNKNOWN_STATUS"
          },
          "message": {
            "type": "string"
          },
          "startTime": {
            "type": "string",
            "format": "date-time"
          },
          "endTime": {
            "type": "string",
            "format": "date-time"
          },
          "fssId": {
            "type": "string"
          },
          "instanceId": {
            "type": "string"
          }
        }
      }
    },
    "creationTime": {
      "type": "string",
      "format": "date-time"
    },
    "createdBy": {
      "type": "string"
    },
    "emails": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "deviation": {
      "type": "integer",
      "format": "int32"
    }
  }
}

default — An unexpected error response.

Content type: application/json

Schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "integer",
      "format": "int32"
    },
    "message": {
      "type": "string"
    },
    "details": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "@type": {
            "type": "string"
          }
        }
      }
    }
  }
}