Introduction to the Schedule Publication API

RejinJose · ‎2024 Oct 14

Introduction to the Schedule Publication API

The Schedule Publication API is designed to facilitate the seamless integration of scheduling functionalities for selected reports within the SAP Analytics Cloud. This API enables partners and customers to programmatically manage the publication of reports, ensuring that all actions typically performed through the user interface can also be executed via API calls.

This API is particularly beneficial for customers seeking event-based scheduling, as it allows for the creation and triggering of publication schedules in response to specific events. By leveraging the capabilities of the Schedule Publication API, users can automate workflows, enhance operational efficiency, and ensure the timely delivery of critical reports. Whether it's initiating a schedule based on an external trigger or managing report publications on a recurring basis, this API provides the flexibility and control needed to streamline the reporting process.

This is available from QRC4.2024 and in fast track tenant it is available from Version 2024.21

API Guide

API Description Method Endpoint Usage

API	Description	Method	EndPoint	Usage
Template API	Retrieves a prefilled JSON payload for creating, updating, or deleting schedules.	GET	/api/v1/storyPublication/schedules/template	Get this template, then modify the placeholder values based on the requirement and use it for Creating or updating the Schedule.
Create API	Establish a new single or recurring Schedule Publication.	POST	/api/v1/storyPublication/schedules	Send your modified JSON payload from the template to create a schedule.
Update API	Modify specific properties of an existing Schedule Publication.	PATCH	/api/v1/storyPublication/schedules/scheduleID	Make modifications without needing to recreate the entire schedule.
Delete API	Remove a single schedule or a series of schedules.	DELETE	/api/v1/storyPublication/schedules/scheduleID	Clean up outdated or unnecessary schedules easily.
Get Schedule API	Retrieve details of a specific Schedule Publication by its ID.	GET	/api/v1/storyPublication/schedules/scheduleID	Fetch the details of the specified schedule.

Note: Replace scheduleID with the ID of the schedule you want to update, delete, or retrieve.

API Body Payload Definition

The following payload will be returned by the template API:

{
    "storyId": "",
    "scheduleName": "",
    "recurrenceType": 1,
    "runNow": true,
    "scheduleMode": 0,
    "runOnceStartDate": "2024-10-14T15:02:56.111Z",
    "recurrence": [
        {
            "recurrenceMode": 3,
            "endMode": {
                "endModeRepetitions": 2,
                "endModeDate": null
            },
            "onMonday": false,
            "onTuesday": false,
            "onWednesday": false,
            "onThursday": false,
            "onFriday": false,
            "onSaturday": false,
            "onSunday": false,
            "firstRun": "2024-10-14T15:02:56.111Z",
            "dayCount": 30
        }
    ],
    "addStoryLink": true,
    "fileFormat": "PDF",
    "emailSubject": "",
    "emailMessage": "",
    "deliveryOption": 0,
    "timezoneFullName": "",
    "views": [
        {
            "bookmarkId": "STORY",
            "viewName": "view 1",
            "filename": "Sample",
            "fileSettings": {
                "selectedStoryPages": [],
                "includeAppendix": true,
                "appendixIncludeDate": true,
                "resolution": "1920,1080",
                "includeComments": false,
                "pageSize": "Auto"
            },
            "destinations": {
                "email": {
                    "extEmailUsr": [],
                    "internalEmailUsr": []
                }
            }
        }
    ],
    "xsTimeTaken": 53
}

Field Definitions

storyId: (string) Unique identifier for the story.
scheduleName: (string) Name of the schedule.
recurrenceType: (integer) Type of recurrence; defines how often the schedule runs. For a single schedule enter 1; for a recurring schedule enter 2.
runNow: (boolean) Indicates whether the schedule should run immediately.
scheduleMode: (integer) Mode of the schedule. For broadcasting enter 1, for bursting enter 2
runOnceStartDate: (string) Specifiy UTC Date String for start date (ex:'2022-06-07T08:15:46.523Z').
recurrence: (array) List of recurrence settings.

recurrenceMode: (integer) Mode of recurrence. For hourly recurrence enter 2; for daily recurrence enter 3; for weekly recurrence enter 4 (to specify the day of the week, use true/false operators (ex: onMonday: true); for monthly recurrence enter 5
endMode: (object) Settings for ending the recurrence. You can use either endModeRepetitions or endModeDate. Specify the number of times you want the schedule to repeat using the corresponding number (ex: 2, for 2 repetitions of the schedule

endModeRepetitions: (integer) Number of repetitions before ending.
endModeDate: (string|null) End date for the recurrence, if applicable.

onMonday to onSunday: (boolean) Indicates if the schedule runs on the respective day of the week.
firstRun: (string) Date and time of the first run in ISO 8601 format.
dayCount: (integer) Day on which Monthly recurrence has to run.

addStoryLink: (boolean) Enter ‘true’ if you want to add a link to the story and ‘false’ if you do not want to add a link to the story.
fileFormat: (string) Enter ‘PDF’ to share a PDF copy of the story or ‘PPT’ to share a PPT format of the story).
emailSubject: (string) Subject line for email notifications.
emailMessage: (string) Message body for email notifications.
deliveryOption: (integer) Specifies the email delivery Option. Enter 0 for Attachment, 1 for Attachment and preview inline, and 2 for Preview Inline
timezoneFullName: (string) Full name of the timezone for scheduling.
views: (array) List of views to be included in the generated output.

bookmarkId: (string) Identifier for the bookmark. Use default “STORY” for scheduling without any bookmark
viewName: (string) Name of the view.
filename: (string) Name of the file to be generated.
fileSettings: (object) Settings for file generation.

selectedStoryPages: (array) List of selected pages for the story.
includeAppendix: (boolean) Indicates if the appendix should be included.
appendixIncludeDate: (boolean) Indicates if the date should be included in the appendix.
resolution: (string) Resolution of the output file (e.g., "1920,1080").
includeComments: (boolean) Indicates if comments should be included.
pageSize: (string) Size of the pages (e.g., "Auto").

destinations: (object) Delivery destinations for the file.

email: (object) Email delivery settings.

extEmailUsr: (array) Enter the email address of the external user/s (ex:abc@gmail.com).
internalEmailUsr: (array) Enter the user ID or Team ID of the internal user/s.

xsTimeTaken: (integer) Time taken for the execution in milliseconds.

User Authorization through OAuth 3.0 in SAC

Having administrator privileges on our SAC tenant, we can register an OAuth-client in the App Integration tab of the administration page. We navigate to the administration page by clicking on ≡ (Main Menu) -> System -> Administration.

Within the App Integration tab (1), we are now able to register a new OAuth client by clicking on +Add New OAuth Client (2).

This will open the dialog for registering a new OAuth Client as shown below:

Client Configuration Instructions

Client Name: Choose a name for your client.
Purpose: Select “Interactive Usage.”
Redirect URI: Indicate the callback URL that the authorization server will return to after successful authorization.
Token Lifetimes: Defining a lifetime for access and refresh tokens is optional.
Final Steps:

Once you provide the required details, ensure to copy the Client ID and Client Secret for use in your application.

Obtaining the Access Token

The diagram below shows the Authorization Code Grant flow for our context and helps you implement it. The end-user authorizes an application to access a protected resource on the Service Provider (SP) and must interact with the IdP (authorization server).

Please note that the SCP Authentication Service is the default IdP but can be changed.

Our custom application should first direct the user to the authorization server's authorization endpoint (Authorization URL). After obtaining the authorization code, the application must exchange it for an access token by making a POST request with the authorization code to the token endpoint (Token URL).

You can find the Authorization URL and Token URL in the App Integration tab under OAuth Clients on SAC's administration page.

Using Postman to Call the Public API

Open Postman and create a new collection.
Go to the Authorization page and fill in the following details to get a new access token:
- Auth Type: OAuth 2.0
- Token Name: Provide a suitable token name.
- Grant Type: Select Authorization Code.
- Callback URL: Check "Authorize using browser."
- Auth URL: Use the Authorization URL received from the App Integration page.
- Client ID: Use the Client ID received while creating the app.
- Client Secret: Use the client secret obtained in the previous step.
Click on "Get New Access Token." This will open your browser for user authentication. Once authentication is complete, you will be redirected to Postman with the token.
Use the access token obtained to call the endpoints.
CSRF Token: You will need the CSRF token to call the API endpoints. Use the following code in the Pre-Request script to get and set the csrf_token header:

const getAppInstancePropsRequest = {
  url: "https://<tenant-url>/api/v1/csrf",
  method: 'GET',
  header: { 'Content-Type': 'application/json' , 'Authorization': 'Bearer ' + pm.collectionVariables.get("bearer.token"), 'x-csrf-token': 'fetch',
  'x-sap-sac-custom-auth': "true" }
};

pm.sendRequest(getAppInstancePropsRequest, function (err, response) {
    console.log(response)
    var csrfToken = response.headers.get("x-csrf-token");
    pm.collectionVariables.set("csrf_token", csrfToken);
})

SAP Analytics Cloud Schedule Publication API's: Getting Started Guide

Introduction to the Schedule Publication API

API Guide

API Body Payload Definition

Field Definitions

User Authorization through OAuth 3.0 in SAC

Client Configuration Instructions

Obtaining the Access Token

Using Postman to Call the Public API