Scheduling a report

Schedule a report to run at a specific time and send the result to email recipients.

Method and URI

To schedule a report, use a POST method and a URI:

POST    https://{hostname|IPv4}/ngp/report

Parameters

Parameter 1: action

Start an action to schedule the report.

  • Value: schedule

  • Type: System string. Required. Available in the web user interface.

Data

Data 1: userId

Use this value when you want to run a report on behalf of someone else. For example, the user Sarah ({userId}: 1001} creates a session ID and sends a request to run a report without the userId key-value pair and her name appears in the report. Add _sppadmin_ ({userId}: 1000) in the key-value pair and this username appears in the report.

Tip

To get a {userId} value based on its name, follow the instructions in Getting a {userId}.

  • Example value: 1000

  • Type: String.

Data 2: resources

Specify the reports to use. Use the following syntax:

[
   {
       "name":     {reportName 1},
       "id":       {reportIdStr 1},
       "rbacPath": {reportRbacPath 1},
       "href":     {reportHref 1}
    },
    ...,
    {...}
]
  • Example value: A list that is similar to the following example can be used to specify the Database Backup History report:

[
   {
       "name":     "Database Backup History",
       "id":       "1012",
       "rbacPath": "root:0/report:0/reportcategory:ProtectionCategoryName/report
↪:1012",
       "href":     "https://10.0.0.100/api/endeavour/report/1012"
    },
    ...,
    {...}
]
  • Type: List (JSON object). Required. Available in the web user interface.

Data 2.1: resources > name

The name of the report.

  • Type: String. Required. Available in the web user interface.

Data 2.2: resources > id

The {reportIdStr} of the report.

Tip

To get a {reportIdStr} based on the report name, follow the instructions in Getting a {reportIdStr}.

  • Type: String. Required.

Data 2.3: resources > rbacPath

The {reportRbacPath} of the report.

Tip

To get a {reportRbacPath} based on the report name, follow the instructions in Getting a {reportRbacpath}.

  • Type: String. Required.

Data 2.3: resources > href

The {reportHref} of the report.

  • Type: String. Required.

Tip

To get a {reportHref} based on the report name, follow the instructions in Getting a {reportHref}.

  • Type: JSON object. Required. Available in the web user interface.

Data 3: trigger

Define the frequency, start date and time, and the time zone for the web user interface. The structure of the value is the same as the value of spec > subpolicy > trigger for an SLA policy. For details, follow the instructions in Adding an SLA policy.

  • Type: JSON object. Required. Available in the web user interface.

Data 4: notification

The email addresses of the recipients.

  • Example value:

[
    "sarah.wiseman@bluemachines.com.invalid",
    "arthur.roberts@bluemachines.com.invalid"
]
  • Type: List (string). Required. Available in the web user interface.

Data 5: option

Specify the options.

  • Example value: Use the following value to get the scheduled report in PDF:

{
    "renderPdf":   true,
    "renderExcel": false,
    "renderWord":  false,
    "export":      false
}
  • Type: JSON object. Available in the web user interface.

Data 5.1: option > renderPDF

Enable or disable to attach a copy of the report in PDF to the scheduled email.

  • Type: Boolean. Available in the web user interface.

Data 5.2: option > renderExcel

Enable or disable to attach a copy of the report in Microsoft Excel format to the scheduled email.

  • Type: Boolean. Available in the web user interface.

Data 5.3: option > renderWord

Enable or disable to attach a copy of the report in Microsoft Word format to the scheduled email.

  • Type: Boolean. Available in the web user interface.

Example: Schedule a report

Sarah ({userId: 1001}) is based in Dallas where the time zone is US Central Time. First, she schedules one of the reports on a browser as below:

  • Report: vSnap Storage Utilization ({reportIdStr}: 1013}

  • Frequency: One time every day

  • Start Time: 1 January 2020 at 0:00 AM US CST or 1577858400 in the UNIX timestamp format.

  • Recipients:

    • sarah.wiseman@bluemachines.com.invalid

    • arthur.roberts@bluemachines.com.invalid

  • User: sppadmin ({userId}: 1000)

  • Option: Attach the PDF file to the scheduled report email.

A Python snippet that is similar to the following example can be used to scheule the report:

report_id = "1013"    # vSnap Storage Utilization

_params = {"action": "schedule"}

_data = f'''
    {{
        "userId":    "1000",
        "resources":    [{{
                            "name":     "vSnap Storage Utilization",
                            "id":       "{report_id}",
                        }}],
        "trigger":      {{
                            "frequency":    1,
                            "type":         "DAILY",
                            "activateDate": 1577858400000,
                            "timezone":     "America/Chicago",
                        }},
        "notification": [
                            "sarah.wiseman@bluemachines.com.invalid",
                            "arthur.roberts@bluemachines.com.invalid"
                        ],
        "option" {{
            "renderPdf":   true,
            "renderExcel": false,
            "renderWord":  false,
            "export":      false
        }}

     }}'''

requests.post('https://' + spp_ipv4 + '/ngp/report',
    headers={...}, params=_params, data=_data, verify=...)
_images/reference_report_schedule01.png

Figure 64 The same action can be taken in the IBM Spectrum Protect Plus web user interface: In the navigation pane, click Reports and Logs > Reports, and click the Schedule Report with default parameters button for the report you want to use.

_images/reference_report_schedule02.png

Figure 65 Enter the freqnency, start time, and email addresses of recipients. Click Schedule.

The request prompts a response that is structured as shown, with the HTTP status of 201 (Created).

{
    "statusCode": 201,
    "response": [
        {
            "links": {...},
            "name": "Report_vSnap Storage Utilization",
            "type": "Schedule",
            "category": "SCHEDULE",
            "properties": {
                "activateDate": 1577858400000,
                "deactivateDate": null,
                "frequency": 1,
                "type": "DAILY",
                "dowList": [
                    false,
                    ...
                ],
                "domList": [
                    false,
                    ...
                ]
            },
            "rbacPath": "trigger:0/trigger:1020",
            "onHold": false,
            "id": "1020"
        },
        {
            "links": {...},
            "name": "Report_vSnap Storage Utilization",
            "type": "analyze",
            "subType": "report",
            "serviceId": "serviceprovider.report",
            "description": "",
            "version": "3.1",
            "rbacPath": "root:0/policy:0/policytype:serviceprovider.report/polic
↪y:1023",
            "tenantId": 1000,
            "creationTime": 1576173685532,
            "lastUpdated": 1576177184653,
            "spec": {
                "source": [
                    {
                        "href": "https://10.0.0.100/api/endeavour/report/1013",
                        "name": "vSnap Storage Utilization",
                        "id": "1013",
                        "parentId": "",
                        "tags": {}
                    }
                ],
                "option": {
                    "renderPdf": true,
                    "renderWord": false,
                    "renderExcel": false,
                    "export": false
                },
                "notification": [
                    {
                        "href": "https://10.0.0.100/api/smtp/1001",
                        "type": "email",
                        "recipients": [
                            "sarah.wiseman@bluemachines.com.invalid",
                            "arthur.roberts@bluemachines.com.invalid"
                        ]
                    }
                ]
            },
            "logicalDelete": false,
            "id": "1023"
        }
    ]
}