Skip to content

Jobs Resource

Introduction

A job in the Open Publishing ecosystem is any backend task e.g. for creating a report or uploading a report to a destination.

The distinction for the backend is the module field. There are predefined or customer specific modules. Each job has a log or a files subresource for storing the log output of the job processor or its artefacts.

Example URL

https://api.openpublishing.com/resource/v3/jobs/[ID]

Allowed methods: GET, PUT, DELETE.

For creating a job POST an object to https://api.openpublishing.com/resource/v3/jobs.

Search Filters

List jobs:

https://api.openpublishing.com/resource/v3/jobs

Filter by module:

https://api.openpublishing.com/resource/v3/jobs?module=some-module

Search for all unprocessed jobs of a module:

https://api.openpublishing.com/resource/v3/jobs?module=some-module&processed=false

Fields

Module

module string containing the type of backend job. Preconfigured values are:

  • title-report: Report of all titles of a realm.
  • assets-report: Report about all ingested assets.
  • business-partner-report: Report about all business partners.
  • missing-assets-report: Report of all missing assets (e.g. e-titles without epub).
  • turnover-report: Report of turnover of realm.
  • aggregation-report: Report of all aggregation turnover.
  • statement-report: Report of all invoiced statements.
  • royalties-report: Report of all generated royalties.
  • payout-report: Report of all paid royalties.

Created

created field contains the unix timestamp when the job was created.

Processed

processed field is a boolean indicating if job was processed.

Properties

In the properties field any arbitrary json may be stored. The values are used as parametes for the backend job.

Realm

realm is the Open Publishing terminology for tenant. It contains a dict with _id and name and screenname.

Example JSON

{
    "_id": 2077,
    "_links": {
        "files": "https://api.openpublishing.com/resource/v3/jobs/2077/files",
        "log": "https://api.openpublishing.com/resource/v3/jobs/2077/log",
        "self": "https://api.openpublishing.com/resource/v3/jobs/2077"
    },
    "created": 1673001722,
    "module": "turnover-report",
    "processed": true,
    "properties": {
        "email": "example@publisher.com",
        "from": "2022-10-01",
        "to": "2022-12-31"
    },
    "realm": {
        "_id": 232,
        "name": "example",
        "screenname": "Example Publishing"
    }
}

Files

Additionally assets and files associated with a job may be stored to the following endpoint. URL:

https://api.openpublishing.com/resource/v3/jobs/[ID]/files
https://api.openpublishing.com/resource/v3/jobs/[ID]/files/[ID]

For adding files, POST to above URL with an multipart/form encoded body with the following parameters:

  • file the file itself
  • type of the file. An arbitrary string, e.g. avatar.

The URL also supports GET for retrieving information about uploaded files. It contains a JSON with the following fields:

  • file_name : File name of uploaded file.
  • file_size : File size in bytes.
  • mime_type : mime type of file, e.g. application\/xml.
  • href : URL to download file.
  • labels : labels of file - at the moment read only.
  • properties : Properties of file - at the moment read only.
  • sha1 : SHA1 checksum of uploaded file..
  • timestamp : Unix timestamp when file was uploaded.
  • type : type of the file. An arbitrary string, e.g. generic.

Example JSON:

{
    "_id": 131233,
    "file_name": "sales_preview_20220602_o50009589.csv%22",
    "file_size": 96052,
    "href": "https://api.openpublishing.com/resource/v3/jobs/14657/files/131233/file",
 "labels": [],
 "mime_type": "text/plain",
 "properties": {},
 "sha1": "1e5ca58c5dc91e3c9171646c9ffb1d27a2ca6c23",
 "timestamp": 1658668349,
 "type": "generic"
}

Log

Log related with a job may be stored to the following endpoint. URL:

https://api.openpublishing.com/resource/v3/jobs/[ID]/log
https://api.openpublishing.com/resource/v3/jobs/[ID]/log/[ID]

For creating a log entry POST an object to https://api.openpublishing.com/resource/v3/jobs/[ID]/log.

  • message the file itself
  • type of the file. An arbitrary string, e.g. error / warning or info.
  • created field with unix timestamp.

The URL also supports GET for retrieving information about uploaded files. It contains a JSON with the following fields:

Example JSON:

{
   "_id": 1,
   "created": 1658668349,
   "message": "Uploaded file",
   "type": "info"
}