PDF Report Scheduling

The PDF Report Scheduling API allows you to schedule reports to be generated, and view and manage existing schedules. Multiple PDF reports can scheduled through this API.

The PDF Report Schedule Resource

Properties

Name
id
Required
Type
integer
Description
Unique identifier for the schedule.
Name
report_type
Required
Type
ReportTypeEnum
Description
The type of report scheduled to be generated. Available types: consumer-duty

Name

status

Required

Type

string

Description

The status of the schedule

Value	Description
scheduling	The report has been scheduled to be created and the system is determining which dealers it should generate the report for.
queued	The dealers this schedule is appropriate for have been determined, and generation is pending
generating	Generation of the reports has started and is currently in progress
review	All reports have been generated and the files are pending a manual review by the business
rejected	Issues were found with some of the generations and the whole schedule has been rejected. Reports will not be sent out to dealers.
approved	No issues were found with the generations, and the reports have been approved to be sent to dealers, but are not currently being sent.
dispatching	Reports are being dispatched to dealers. How reports are dispatched is determined by the report type.
complete	All scheduling, generation and dispatching has been completed, and there is nothing left for the system to do.
cancelling	The schedule has been cancelled, either by the system programmatically, or through manual intervention, and is in the process of winding down scheduling for this batch.
cancelled	The schedule was cancelled, and the system has finished cancelling all jobs that were in progress. No further action can be taken.

Name
month
Required
Type
integer
Description
The month the report is to be generated for.
Name
year
Required
Type
integer
Description
The year the report is to be generated for.
Name
is_preview
Required
Type
boolean
Description
Indicates this is a preview generation and not intended to be delivered to dealers
Name
filters
Required
Type
Array<ScheduleFilterResource>
Description
An array of Schedule Filter resources
Name
id
Required
Type
integer
Description
Unique ID for the schedule filter record. This is unique to this schedule and filter.
Name
filter
Required
Type
string
Description
The name of the filter being applied to the schedule
Name
config
Required
Type
object|array
Description
The configuration object specific to this filter.
Name
dates.created_at
Required
Type
datetime
Description
The date the schedule record was created, represented in YYYY-MM-DD HH:MM:SS format
Name
dates.updated_at
Required
Type
datetime
Description
The date the schedule record was last updated, represented in YYYY-MM-DD HH:MM:SS format

Schedule Resource

{
  "id": 1,
  "report_type": "consumer-duty",
  "status": "scheduling",
  "month": 11,
  "year": 2024,
  "is_preview": false,
  "filters": [
    {
      "id": 1,
      "filter": "inclusion-dealer-id",
      "config": [1, 2, 3]
    }
  ],
  "dates": {
    "created_at": "2024-01-01 00:00:00",
    "updated_at": "2024-01-02 12:00:00"
  }
}

The Schedule Progress Resource

Properties

Name
schedule_id
Required
Type
integer
Description
Unique identifier for the schedule.
Name
status
Required
Type
string
Description
The current status of the schedule. Will be one of scheduling, queued, generating, review, rejected, approved, dispatching, complete, cancelling or cancelled.
Name
description
Required
Type
string
Description
A description of what happens in this state
Name
progress
Required
Type
integer | null
Description
The current progress, represented as a percent of the current state. If the state is not a "progressable" type state, this value will be null. For example, when generating, 2 out of 10 reports may have been generated, so this value would be 20 to represent its 20% complete. However when the state is complete, there is nothing to calculate progress against, so this value will be null.
Name
run_time
Required
Type
string
Description
A human readable string representing how long the schedule has been running.

Schedule Progress Resource

{
  "schedule_id": 1,
  "status": "generating",
  "description": "An example description of this state",
  "progress": 75,
  "run_time": "1 day, 1 hour and 30 seconds"
}

GET/v2/pdf-reports/schedules

Search Schedules

The search schedules endpoint uses the standard Search package from the SDK.

An array of schedule resources are returned. If no results are found, an empty collection is returned.

Search Filters

Name
filters.id.equals
Required
Type
integer
Description
Match a single schedule by ID
Name
filters.id.in
Required
Type
array<integer>
Description
Match schedules by multiple IDs
Name
filters.report_type.equals
Required
Type
string
Description
Match a schedule by its report type
Name
filters.report_type.in
Required
Type
array<string>
Description
Match schedules by multiple report types
Name
filters.dealer_id.equals
Required
Type
integer
Description
Find schedules for a given dealer ID. If schedules are still in a scheduling state, the results may not contain all the schedules.
Name
filters.status.equals
Required
Type
string
Description
Match schedules by a given status
Name
filters.status.in
Required
Type
Array<string>
Description
Match schedules by multiple statuses
Name
filters.month.equals
Required
Type
integer
Description
Match schedules for a given month
Name
filters.year.equals
Required
Type
integer
Description
Match schedules for a given year
Name
filters.is_preview.equals
Required
Type
boolean
Description
Match schedules being generated for a preview

Search Ordering

id
report_type
status
month
year
is_preview
created_at
updated_at

Request

GET

/v2/pdf-reports/schedules

use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;
use Compliance\Sdk\Search\Search;

private ApexV3SdkInterface $sdk;

$search = new Search();

$response = $this->sdk
  ->v2(new Machine())
  ->pdfReports()
  ->schedules()
  ->search($search);

Response

{
  "data": [
    {
      "id": 1,
      "report_type": "consumer-duty",
      "status": "scheduling",
      "month": 11,
      "year": 2024,
      "is_preview": false,
      "filters": [
        {
          "id": 1,
          "filter": "inclusion-dealer-id",
          "config": [1, 2, 3]
        }
      ],
      "dates": {
        "created_at": "2024-01-01 00:00:00",
        "updated_at": "2024-01-02 12:00:00"
      }
    }
  ]
}

GET/v2/pdf-reports/schedules/:schedule_id

Retrieve Schedule

Will retrieve a specific schedule record by ID

URL Parameters

Name
schedule_id
Required
required
Type
integer
Description
ID of the schedule to retrieve

Error Codes

Status	Description
404	The requested schedule could not be found

Request

GET

/v2/pdf-reports/schedules/:schedule_id

use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->pdfReports()
  ->schedule(1)
  ->get();

Response

{
  "data": {
    "id": 1,
    "report_type": "consumer-duty",
    "status": "scheduling",
    "month": 11,
    "year": 2024,
    "is_preview": false,
    "filters": [
      {
        "id": 1,
        "filter": "inclusion-dealer-id",
        "config": [1, 2, 3]
      }
    ],
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00"
    }
  }
}

GET/v2/pdf-reports/schedules/:schedule_id/progress

Schedule Report

Will attempt to schedule a report to be generated

Payload

Name
report_type
Required
required
Type
ReportTypeEnum
Description
The type of report to schedule. Available options: consumer-duty
Name
month
Required
required
Type
integer
Description
Month number to generate the report for. For example, to generate a report using Novembers data, specify 11
Name
year
Required
required
Type
integer
Description
Year to generate the report for.

Name

filters

Required

Type

Array<ScheduleFilter>

Description

An array of filters to generate reports for. Filters run using an and condition. If the dealer passes all filter constraints, a report will be generated for them. If no filters are provided, the report will be generated for all active V3 dealers.

Name

filter

Required

Type

string

Description

The filter to apply during scheduling

Filter	Purpose
`exclusion-dealer-id`	Prevents dealer IDs from having reports generated
`exclusion-group-id`	Prevents dealers in the given groups having reports generated
`inclusion-dealer-id`	Only generates reports for specified dealers
`inclusion-group-id`	Only generates reports for dealers within the specified groups

Name
config
Required
Type
array | object
Description
The filter configuration object.

Error Codes

Status	Description
422	The data provided in the payload was invalid. See errors for more details.

Request

POST

/v2/pdf-reports/schedules

use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->pdfReports()
  ->schedules()
  ->create('consumer-duty', 11, 2024, [
    [
      'filter' => 'inclusion-dealer-id',
      'config' => [1, 2, 3],
    ],
  ]);

Response

{
  "data": {
    "id": 1,
    "report_type": "consumer-duty",
    "status": "scheduling",
    "month": 11,
    "year": 2024,
    "filters": [
      {
        "id": 1,
        "filter": "inclusion-dealer-id",
        "config": [1, 2, 3]
      }
    ],
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00"
    }
  }
}

POST/v2/pdf-reports/schedules/preview

Schedule Preview Report

Will attempt to schedule a preview report to be generated.

Preview schedules do not use filters. Instead you should pass up the dealer ID

Payload

Name
report_type
Required
required
Type
ReportTypeEnum
Description
The type of report to schedule. Available options: consumer-duty
Name
month
Required
required
Type
integer
Description
Month number to generate the report for. For example, to generate a report using Novembers data, specify 11
Name
year
Required
required
Type
integer
Description
Year to generate the report for.
Name
dealer_id
Required
required
Type
integer
Description
The dealer ID to preview

Error Codes

Status	Description
422	The data provided in the payload was invalid. See errors for more details.

Request

POST

/v2/pdf-reports/schedules/preview

use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->pdfReports()
  ->schedules()
  ->createPreview(12935, 'consumer-duty', 11, 2024);

Response

{
  "data": {
    "id": 1,
    "report_type": "consumer-duty",
    "status": "scheduling",
    "month": 11,
    "year": 2024,
    "is_preview": true,
    "filters": [
      {
        "id": 1,
        "filter": "inclusion-dealer-id",
        "config": [12935]
      }
    ],
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00"
    }
  }
}

POST/v2/pdf-reports/schedules/:schedule_id/cancel

Cancel Schedule

Will attempt to cancel a schedule. A report can only be scheduled while its status is not either complete, cancelling or cancelled.

URL Parameters

Name
schedule_id
Required
required
Type
integer
Description
ID of the schedule to cancel

Error Codes

Status	Description
404	The schedule couldn't be found
409	The schedule has a state of either `complete`, `cancelling` or `cancelled`

Request

POST

/v2/pdf-reports/schedules/1/cancel

use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->pdfReports()
  ->schedule(1)
  ->cancel();

Response

{
  "data": {
    "id": 1,
    "report_type": "consumer-duty",
    "status": "cancelling",
    "month": 11,
    "year": 2024,
    "is_preview": false,
    "filters": [
      {
        "id": 1,
        "filter": "inclusion-dealer-id",
        "config": [1, 2, 3]
      }
    ],
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00"
    }
  }
}

POST/v2/pdf-reports/schedules/:schedule_id/review

Review Schedule

When the schedule is in a review status, this endpoint can be called to progress the schedule.

URL Parameters

Name
schedule_id
Required
required
Type
integer
Description
ID of the schedule to review

Payload

Name
state
Required
required
Type
string
Description
Specify whether the schedule should be approved or rejected. Available values: approved, rejected

Error Codes

Status	Description
404	The schedule couldn't be found
409	The schedule was not in a reviewable state
409	If the state was set to `approved` but all the generations marked as chosen for review weren't reviewed

Request

POST

/v2/pdf-reports/schedules/1/review

use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

// To approve a schedule
$response = $this->sdk
  ->v2(new Machine())
  ->pdfReports()
  ->schedule(1)
  ->approve();

// To reject a schedule
$response = $this->sdk
  ->v2(new Machine())
  ->pdfReports()
  ->schedule(1)
  ->reject();

Response

{
  "data": {
    "id": 1,
    "report_type": "consumer-duty",
    "status": "dispatching",
    "month": 11,
    "year": 2024,
    "is_preview": false,
    "filters": [
      {
        "id": 1,
        "filter": "inclusion-dealer-id",
        "config": [1, 2, 3]
      }
    ],
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00"
    }
  }
}