Introducing Planning Process APIs for SAP Analytics Cloud, Analytics Designer: Embed Planning Workflows into Your Custom Applications!

I am sure many of you have come to love the calendar and planning process features of SAP Analytics Cloud. Within the Calendar, you can model and schedule planning processes that help guide planners and reviewers through complex workflows. Apart from that, you can use the calendar to schedule automatic tasks such as data actions and data locking configuration changes.

Already in 2020, we enabled the integration of calendar tasks into SAP Analytics Cloud, analytics designer applications. But users had to use the details panel in the calendar or the tool bar in the workfile to process their assignments such as submitting data or approving/rejecting input. I could imagine that this was not quite what you expected from a custom-built application and you were looking for a way to automate steps along the progression of a task using existing APIs for data actions, publishing, data locking etc.

This is why, starting with our QRC2.2021 release, you are able to create and use custom buttons and widgets to allow for more automated and guided workflows within your apps! In this blog post, I will show you how to do this.

For sure, this is only the first wave of APIs that we are introducing. So, I will also lay out what we plan to deliver very soon to even allow the creation of tasks and more!

How to

As said, the first calendar APIs for analytic applications let you guide your users with the help of custom buttons or other widgets. They will be able to take care of their tasks by submitting, declining, approving, and rejecting general tasks, review tasks, and composite tasks.

A pre-requisite is that the calendar task has already been created in the calendar with your application added as a workfile. Subsequently, the workfile can be opened from the calendar sidepanel, notifications, e-mail, the SAP Analytics Cloud home screen etc.

Add your applications in the workfiles section of the sidepanel

Building a new analytic application, the first thing you will notice is the new technical object type ‘Calendar Integration’.

Add a calendar integration object to your app!

When you create a new object, you can choose whether you want to leverage the calendar toolbar or not when users run the application. In this example, we are choosing to not use the toolbar at runtime.

Choose to use the Calendar toolbar or not!

Now let’s see what you can do on top of this object.

First of all, you must retrieve the calendar task that the application was opened from via the getCurrentTask() API.

Example:

var calendarTask = CalendarIntegration_1.getCurrentTask();

Now that you got the task object, you can determine the task’s status (E.g. inactive, open, in progress, etc.), the task type (composite task, general task, review task) and whether the current user has the specified role in the calendar event using the following APIs.

• getStatus()
• getType()
• hasUserRole()

Finally, there are APIs to submit, decline, approve and reject calendar tasks. Before using them, the technical calendar object needs to be casted to the correct task type, such as composite task, general task or review task using the cast() script API method. For more details on task types, check out Daniel Lauer’s blog post on the new calendar functionalities released in Q1 2021.

Composite tasks can be approved, rejected, submitted and declined:

• submit()
• decline()
• approve()
• reject()

General tasks can be submitted and declined:

• submit()
• decline()

Review tasks can be approved and rejected:

• approve()
• reject()

Now, let’s finally take a look at a code example – the following snippet can be used for a custom submit button in your application:

var task = CalendarIntegration_1.getCurrentTask();
var taskType = task.getType();
var taskStatus = task.getStatus();

if (taskStatus === CalendarTaskStatus.Accomplished || taskStatus === CalendarTaskStatus.Canceled) {
    Application.showMessage(ApplicationMessageType.Error, "The task is already completed");
    return;
}

var isSubmitted= false;
if (taskType === CalendarTaskType.CompositeTask) {
    var compositeTask = cast(Type.CalendarCompositeTask, task);
    isSubmitted = compositeTask.submit();
} else if (taskType === CalendarTaskType.GeneralTask) {
    var generalTask = cast(Type.CalendarGeneralTask, task);
    isSubmitted = generalTask.submit();
} else if (taskType === CalendarTaskType.ReviewTask) {
    Application.showMessage(ApplicationMessageType.Error, "You can't submit a review task");
    return;
}

if (isSubmitted) {
    Application.showMessage(ApplicationMessageType.Success," You have successfully submitted your task.");
} else {
    Application.showMessage(ApplicationMessageType.Error,"Submission is not successful. Please try again or contact your admin.");
}

And this is the result in real life. We are opening an analytic application for the Calendar, finalize our project planning input by running a data action and directly submit our task. Another look into the calendar confirms that we were successful.

Our code in action!

What will be next?

So far, so good… Easy, isn’t it? I suggest familiarizing yourself with what I described here so that you are ready to take the next step with future releases!

This will open up all new opportunities for processes that can be represented in SAP Analytics Cloud. Think about request and approval processes for new projects or investments etc. When pairing this with the existing and upcoming planning capabilities in SAP Analytics Cloud and the analytics designer, you will be able to implement true end-to-end planning processes in your custom applications.

Check out this further information to learn more about the SAP Analytics Cloud, analytics designer and the calendar:

• Analytics Designer for the Planning Process – When is the Right Time?
• SAP Analytics Cloud, Analytics Designer Developer Handbook
• Enrich Your Planning Process with the New Workflow Capabilities of SAP Analytics Cloud
• Content from help.sap.com:
  • Calendar
  • Working with Calendar Tasks
  • Using Calendar Task APIs