Administrate the Jobs¶

The jobs in an Output Engine system can be administrated via PLOSSYS CLI.

Hint - Web user interface

Some of the operations can be executed via PLOSSYS Administrator as well.

Requirements¶

For the requirements for using PLOSSYS CLI, refer to PLOSSYS CLI.

Command Overview¶

Usage: plossys job [options] [command]

Options:
  -V, --version                   output the version number
  --server <value>                server url
  --insecure                      accept invalid https certificate from server
  --auth <auth_type>              Auth Type "basic" or "oidc"
  --user <name>                   user name for authentication
  --pass <password>               password for authentication
  --bearer <token>                JSON Web Token (JWT) for authentication
  --credential <credentialsfile>  file containing user name and password or JWT token
  -h, --help                      display help for command

Commands:
  logs <jobId>                    retrieve job logs
    required arguments:
      jobId: the id of the job that logs shall be retrieved for

  pause <jobs...>                 pause jobs
    required arguments:
      jobs: the list of jobs, separated by whitespace or newline
        use '-' for pipe

  cancel <jobs...>                cancel jobs
    required arguments:
      jobs: the list of jobs, separated by whitespace or newline
        use '-' for pipe

  query [options] <criteria>      search for jobs using OData
    required arguments:
      criteria: the query
        e.g., jobs starting with '6c84':  "startswith(_id, '6c84')"
              jobs with exact status: "status eq 'processing'"
              printerName ending with '4050': "endswith(current/printerName, '4050')"
              userName starting with 'John Doe': "startswith(current/userName, 'John Doe')"

  remove <jobs...>                remove jobs
    required arguments:
      jobs: the list of job ids, separated by whitespace or newline
        use '-' for pipe

  repeat <jobs...>                repeat jobs
    required arguments:
      jobs: the list of jobs, separated by whitespace or newline
        use '-' for pipe

  resume <jobs...>                resume jobs
    required arguments:
      jobs: the list of job ids, separated by whitespace or newline
        use '-' for pipe

  show [options] [jobs...]        show job details
    required arguments:
      jobs: the list of job ids
        use '-' for pipe

  tempfiles [options] <jobs...>   Enable or disable saving of tempfiles of jobs
    Default is enabling.
    required arguments:
      jobs: the list of jobs, separated by whitespace or newline
        use '-' for pipe

  collect [options] <jobId>       retrieve job files, including input file, job properties
                                  and log file
    required arguments:
      jobId: the id of the job that files shall be retrieved for

  print [options] <file>          print document
  help [command]                  display help for command

Options¶

--insecure¶

Specify the --insecure option to avoid that the certificate will be checked by the client.

plossys job <command> --insecure

--server¶

For administrating the jobs of a specific Output Engine server, specify the --server <plossys_server> option. Default is https://localhost:8080.

plossys job <command> --server https://<plossys_server>:8080

Example - show all jobs of the plossys.server1.com server

plossys job show --server https://plossys.server1.com:8080

User Authentication¶

Depending on the type of user authentication activated for the seal-rest service, you have to specify the user and the password with PLOSSYS CLI. By default, the specified user is first checked via OpenID Connect. Basic authentication is use as fallback.

plossys job <command> --auth <auth_type> --user <user> --pass <password>

Example - show all jobs as user test authenticated via OpenID Connect

plossys job show --auth oidc --user test --pass test

Using OpenID Connect, you can specify a JSON Web token (JWT) instead of a user and his password.

plossys job <command> --auth oidc --bearer <jwt>

Example - show all jobs as a user authenticated via JSON Web token

plossys job show --auth oidc --bearer eyJ0eXAiOiJKV1QiLCJhbG...

The credentials, i.e. user and password or token, can also be transmitted via file.

plossys job <command> --auth oidc --credential <credential_file>

Commands¶

cancel¶

The command cancels jobs.

plossys job cancel [options] <job_id_1> <job_id_2> ... <job_id_n>

required arguments:

jobs: the list of jobs, separated by whitespace or newline; use - for pipe

collect¶

The command retrieves job files, including input file, job properties and log file.

plossys job collect [options] <jobId>

required arguments:

jobId: the id of the job that files shall be retrieved for

logs¶

The command retrieves the logs of a specific job.

plossys job logs <jobId>

required arguments:

jobId: the id of the job that logs shall be retrieved for

Hint - logged data

On how to specify the scope of data logged, refer to Logging on Windows or Linux.

pause¶

The command pauses jobs.

plossys job pause [options] <job_id_1> <job_id_2> ... <job_id_n>

required arguments:

jobs: the list of jobs, separated by whitespace or newline; use - for pipe

print¶

The command prints the document specified by file.

plossys job print [options] <file>

options:

--printer <printer> Name of printer to print the document
--ippserver <value> IPP server url (http://localhost:631) (default: "http://localhost:631")

Hint - graphic file

If file is a graphic file, the --printer option has to be specified.

The file can also be a Zip file resulting from plossys job collect or the correspondent operation in PLOSSYS Administrator.

In this case, the original input file in the Zip file is printed. The printer specified in the original print parameters of the Zip file (<jobID>.json) is used unless it is overwritten by the --printer option and the original print parameters in the Zip file (<jobID>.json) are used.

query¶

For advanced job queries, the query subcommand is available. The query subcommand supports the OData language. The result of the subcommand is a list of jobs. In order to execute complex queries and operations, this list can be combined with other PLOSSYS CLI commands.

plossys job query [options] <criteria>

plossys job query <query> --fields <field_name_1>,<field_name_2>,...,<field_name_n>

options:

--fields <value> fields to display

If --fields is omitted, only the Job-IDs are returned. If --fields ALL is specified, all job parameters are returned. For further usage of --fields see plossys job show

Example - show jobs starting with 6c84

plossys job query "startswith(_id, '6c84')"

Example - list active jobs

plossys job query "status eq 'active'"

Example - show active jobs with all parameters

plossys job query "status eq 'active'" --fields ALL

Example - pause the active jobs

plossys job query "status eq 'active'" | plossys job pause -

Example - remove all jobs

The following example uses the third-party-tool jc for parsing the JSON output of plossys job show. This tool is usually not installed on your system and has to be installed so that the following command will work. You can download jc from https://stedolan.github.io/jq/download/ for example.

plossys job show | jq -r .[]._id | plossys job remove -

remove¶

The command removes jobs from the job list.

plossys job remove [options] <job_id_1> <job_id_2> ... <job_id_n>

required arguments:

jobs: the list of jobs, separated by whitespace or newline; use - for pipe

repeat¶

The command repeats jobs.

plossys job repeat [options] <jobs...>

required arguments:

jobs: the list of jobs, separated by whitespace or newline; use - for pipe

Example - repeat job with jobID 15614e36-3a8b-4e0e-9461-9a759fd42e75

plossys job repeat 15614e36-3a8b-4e0e-9461-9a759fd42e75

resume¶

The command resumes paused jobs.

plossys job resume <job_id_1> <job_id_2> ... <job_id_n>

required arguments:

jobs: the list of job ids, separated by whitespace or newline; use - for pipe

show¶

The command returns the details to all or specific jobs in JSON format. You can specify the fields to be returned.

plossys job show [options] [jobs...]

required arguments:

jobs: the list of job ids, separated by spaces. If no jobIDs are provided, the details of all jobs will be returned; use - for pipe

options:

--fields <value> fields to display

Hint - field names with hierarchie

The field names have to be specified with the complete hierarchy, for example, current/jobName.

Example - show the job with the ID b6f50fe3-1292-4d56-922f-bcd26038bb97

plossys job show b6f50fe3-1292-4d56-922f-bcd26038bb97

results in:

[
  {
    "_id": "b6f50fe3-1292-4d56-922f-bcd26038bb97",
    "orig": {
      "jobName": "Testjob@p50-roe-hp2055-001",
      "printerName": "p50-roe-hp2055-001",
      "userName": "test",
      "fileName": "",
      "copies": 1,
      "checkinType": "ipp/2.0",
      "server": "p5",
      "pdl": {
        "name": "postscript",
        "version": "3.0"
      },
      "creator": "",
      "arrivedTime": 1568280537768,
      "checkinTime": 1568280537778,
      "fileSize": 35266
    },
    "current": {
      "jobName": "Testjob@p50-roe-hp2055-001",
      "printerName": "p50-roe-hp2055-001",
      "userName": "test",
      "fileName": "",
      "copies": 1,
      "checkinType": "ipp/2.0",
      "server": "p5",
      "pdl": {
        "name": "postscript",
        "version": "3.0"
      },
      "creator": "",
      "arrivedTime": 1568280537768,
      "checkinTime": 1568280537778,
      "fileSize": 35266
    },
    "refId": "b6f50fe3",
    "fileName": [
      "b6f50fe3-1292-4d56-922f-bcd26038bb97"
    ],
    "status": "canceled"
  }
]

Example - export the details for all jobs into a file

plossys job show --user test --pass test --insecure > jobs.txt

Example - show the status and the original user name of all jobs

plossys job show  --fields status,orig/userName

results in:

[
  {
    "_id": "5250f1e6-03f8-4525-bc22-e13fcd9cb38c",
    "orig": {
      "userName": "joe"
    },
    "status": "postponed"
  },
  {
    "_id": "15614e36-3a8b-4e0e-9461-9a759fd42e75",
    "orig": {
      "userName": "jane"
    },
    "status": "waiting"
  },
  {
    "_id": "fe4db59c-b397-48ac-bd59-8beb02c6a7ea",
    "orig": {
      "userName": "willy"
    },
    "status": "waiting"
  },
  {
    "_id": "b6f50fe3-1292-4d56-922f-bcd26038bb97",
    "orig": {
      "userName": "test"
    },
    "status": "canceled"
  }
]

tempfiles¶

The command enables or disables the saving of tempfiles for jobs. Default is enabling.

plossys job tempfiles [options] <jobs...>

required arguments:

jobs: the list of jobs, separated by whitespace or newline; use - for pipe

options:

--save <enable> Enable or disable saving of tempfiles.
- possible values: true | false
- default: true (default: "true")