Use Calendar Integration Technical Objects and Calendar Task APIs

As an application designer or story developer, you can add a calendar integration technical object and use calendar task APIs on it, to submit, decline, approve, reject and activate a calendar task, for example. Furthermore, you can enquire the properties of a calendar task and use convenience APIs to verify if you can perform a task status change. The calendar task must be either of type general task, review task or composite task.

Add a Calendar Integration Technical Object

To add a calendar integration technical object, in the Scripting section of the Outline panel, (for analytic applications) choose right next to Calendar Integration, or (for optimized stories) choose Start of the navigation path Next navigation step Calendar Integration End of the navigation path .

A side panel opens where you can set the ID of the technical object and choose whether the calendar toolbar is visible in view time.

Then, you can use the following APIs for the calendar integration technical object:

CalendarIntegration.getCurrentTask()
CalendarIntegration.getCurrentTask().getStatus()
CalendarIntegration.getCurrentTask().getType()
CalendarIntegration.getCurrentTask().hasUserRole(CalendarTaskUserRoleType)

Depending on the calendar role type, additional APIs such as submit(), decline(), approve() and reject(), can be used for the following task types:

general task
composite task
review task

To use these APIs, you first have to convert a CalendarIntegration to the target calendar task using the cast() API.

Use `getCurrentTask` API

You can use the getCurrentTask API to inquire the calendar task that is loaded with your analytic application or story.

This is necessary because a user can't perform operations on a calendar, like submit and decline or approve and reject if an analytic application or story isn't associated with a calendar through a working file.

Sample Code

var calendarTask = CalendarIntegration_1.getCurrentTask();
console.log(calendarTask);

Use `getStatus` API

You can get the overall status of a calendar task by using the getStatus API. The API returns a CalendarTaskStatus

Sample Code

var status = CalendarIntegration_1.getCurrentTask().getStatus();
switch (status) {
    case CalendarTaskStatus.InProgress:
        console.log("In Progress");
        break;
    case CalendarTaskStatus.Canceled:
        console.log("Canceled");
        break;
    case CalendarTaskStatus.OnHold:
        console.log("OnHold");
        break;
    case CalendarTaskStatus.Open:
        console.log("Open");
        break;     
}

The code snippet returns the task status from the calendar task:

Use `getType` API

You can get the task type of a calendar task by using the getType API. The API returns the type of task that is created in the calendar (general, composite or review task).

Sample Code

var calendarTaskType = CalendarIntegration_1.getCurrentTask().getType();
console.log(calendarTaskType);

Use `hasUserRole` API

You can inquire the calendar user role of the currently loaded calendar task by using the hasUserRole API. The API accepts the following roles:

CalendarTaskUserRoleType.Reviewer
CalendarTaskUserRoleType.Owner
CalendarTaskUserRoleType.Assignee

The API returns true if the current logged in user has the specified user role given as parameter, and false otherwise.

Sample Code

var calendarTask = CalendarIntegration_1.getCurrentTask();
var isReviewer = calendarTask.hasUserRole(CalendarTaskUserRoleType.Reviewer);
console.log(isReviewer);

Use `submit` API

As an assignee, you can use the submit API to submit a calendar of type General Task or Composite Task. The API returns true if successful, false otherwise.

CalendarGeneralTask.submit()
CalendarCompositeTask.submit()

To submit a calendar task for a composite task, you can use the following code snippet:

Sample Code

var calendarTask = CalendarIntegration_1.getCurrentTask();
var isAssignee = calendarTask.hasUserRole(CalendarTaskUserRoleType.Assignee);
var calendarTaskStatus = calendarTask.getStatus();
var calendarTaskType = calendarTask.getType();
if (isAssignee && calendarTaskType === CalendarTaskType.CompositeTask && calendarTaskStatus === CalendarTaskStatus.InProgress) {
     var compositeTask = cast(Type.CalendarCompositeTask, calendarTask);
     var isSuccessfullySubmitted = compositeTask.submit();
     if (isSuccessfullySubmitted) {
         console.log("You have successfully submitted your task.");
     } else {
       console.log("Sorry, something went wrong.");
    }
}

The API replaces the Submit action from the calendar view:

Use `decline` API

As an assignee, you can use the decline API to decline a composite task or general task for all assignees. If there are multiple assignees, you'll decline the task for your role only. This replaces the option Decline Your Role Only in the Decline Task dialog. The API returns true if successful, false otherwise:

CalendarCompositeTask.decline()
CalendarGeneralTask.decline()

Sample Code

To decline a composite task, you can use the following code snippet:

var calendarTask = CalendarIntegration_1.getCurrentTask();
var isAssignee = calendarTask.hasUserRole(CalendarTaskUserRoleType.Assignee);
var calendarTaskType = calendarTask.getType();
if (isAssignee && calendarTaskType === CalendarTaskType.CompositeTask) {
     var compositeTask = cast(Type.CalendarCompositeTask, calendarTask);
     var isSuccessfullyDeclined = compositeTask.decline();
     if (isSuccessfullyDeclined) {
         console.log("You have successfully declined your task.");
     } else {
       console.log("Sorry, something went wrong.");
    }
}

Note

This API replaces the Decline action from the side panel of the calendar.

Use `approve` API

As a reviewer you can use the approve API to accept a composite task or a review task. The assignee should have first submitted the task before. The API returns true if successful and false otherwise:

CalendarCompositeTask.approve()
CalendarReviewTask.approve()

Sample Code

To approve a calendar task for a review task, you can use the following code snippet:

var calendarTask = CalendarIntegration_1.getCurrentTask();
var isReviewer = calendarTask.hasUserRole(CalendarTaskUserRoleType.Reviewer);
var calendarTaskType = calendarTask.getType();
if (isReviewer && calendarTaskType === CalendarTaskType.ReviewTask) {
     var reviewTask = cast(Type.CalendarReviewTask, calendarTask);
     var isSuccessfullyApproved = reviewTask.approve();
     if (isSuccessfullyApproved) {
         console.log("You have successfully approved the task of the assignee.");
     } else {
       console.log("Sorry, something went wrong.");
    }
}

Note

The API replaces the Approve action from the side panel of the calendar.

Use `reject` API

As a reviewer you can use the reject API to reject a composite task or a review task for the assignee to have another look at it. The assignee should have first submitted the task before. The API returns true if successful and false otherwise.

CalendarCompositeTask.reject()
CalendarReviewTask.reject()

Sample Code

To reject a composite task, you can use the following code snippet:

var calendarTask = CalendarIntegration_1.getCurrentTask();
var compositeTask = cast(Type.CalendarCompositeTask, calendarTask);
var isSuccessfullyRejected = compositeTask.reject();
if (isSuccessfullyRejected) {
    console.log("You have successfully rejected your task.");
} else {
    console.log("Sorry, something went wrong.");
}

Note

The API replaces the Reject action from the calendar toolbar or from the side panel of the calendar.

Use `getCalendarTaskById()` API

If you want to retrieve information about a specific task, you can use the getCalendarTaskById() API. Simply pass the eventId from the query string in the URL The analytic application or story doesn't need to be opened by clicking a work file from the calendar task to use this API.

Sample Code

The following code logs the result of the getType() API to the browser console for any task:

var task = CalendarIntegration_1.getCalendarTaskById("taskId");
if (task.getType() === CalendarTaskType.CompositeTask) {
  console.log("This is a composite task");
} else if (task.getType() === CalendarTaskType.GeneralTask) {
  console.log("This is a general task");
} else if (task.getType() === CalendarTaskType.ReviewTask) {
  console.log("This is a review task");
}

Use `activate()` API

You can use the activate() API to activate a task and also specify the notify option. This API replaces the Activate or Activate and Notify option from the calendar view.

Use `getRelatedTaskIds()` API

You can use the getRelatedTaskIds() API to retrieve all the calendar task ids for which the opened application or story is a working file. The API returns either an array of task ids, or if no tasks are found, an empty array.

Note

Recurring composite tasks are currently not delivered as part of the result.

Sample Code

With this sample code snippet, you can retrieve all the tasks for which the opened analytic application or story is a working file


var allTasks = CalendarIntegration_1.getRelatedTaskIds(); 
 
console.log(allTasks);

Use `createCompositeTask()` API

You can use the createCompositeTask() API to create a composite task with properties and options.

When creating a composite task, you can choose a name, startDate and dueDate, which are the mandatory properties. You can choose between an analytic application or a story when specifying the work file.

Sample Code

With this sample code snippet, you can create a composite task that starts now and ends on January, 16th 2022. There's one work file belonging to this composite task, the current opened application or story. One assignee is defined, the current logged in user. Additionally, a reviewer is specified, in one review round. The option autoActivate replaces the Activate the task at start date automatically option in the software user interface.

var newTask = CalendarIntegration_1.createCompositeTask({
     name: "newCompositeTask",
     startDate:new Date(Date.now()),    
     dueDate: new Date(2022, 0, 16, 0, 0, 0),
     workFiles: [{
         id: Application.getInfo().id,
         type: CalendarTaskWorkFileType.AnalyticApplication,        
     }],
    assignees: [Application.getUserInfo().id], 
    description: "Calendar Composite Task description",
    reviewers: {
        "1": ["reviewerId"],
        }
    }, {
    autoActivate: true
});

Use the Status Change APIs for a Calendar Composite Task

You can use the submit(), decline(), approve() or reject() APIs for any composite task given a task Id.

Sample Code

With this sample code snippet, you can submit any composite task given a task Id.

var task = CalendarIntegration_1.getCalendarTaskById("taskId");
if (task.getType() === CalendarTaskType.CompositeTask) {
var compositeTask = cast (Type.CalendarCompositeTask, task);
compositeTask.submit();
}

Use Calendar Task Convenience APIs

You can use the technical object CalendarIntegration together with the convenience APIs canUserSumit,, canUserDecline, canUserApprove, canUserReject to check if you can perform a task status change.

Depending on the calendar role type, the APIs canUserSumit, , canUserDecline, canUserApprove, canUserReject can be used for the following task types:

general task
composite task
review task

Note

To use these APIs, you first have to convert a technical object CalendarIntegration to the target event using the cast() API.

Use `canUserSubmit` API

You can use the canUserSubmit API to verify if a calendar task is ready to be submitted for the assignee user role. If you use the API when the task status is Open , the task status changes to In Progress.

Sample Code

The following code snippet submits a task with the id "myTaskId" that is open:

var task = CalendarIntegration_1.getCalendarTaskById("myTaskId");
var compositeTask = cast (Type.CalendarCompositeTask, task);
var canSubmit = compositeTask.canUserSubmit();
if (canSubmit) {
    var submitSuccesfull = compositeTask.submit();
    if (submitSuccesfull) {
        console.log("Submitted");
    } else {
        console.log("Failed to submit, please try again.");
    }
}

Use `canUserApprove` API

You can use the canUserApprove API for the user role reviewer on a composite task, or for a user role assignee on a review task to verify if the task can be approved.

Sample Code

The following code snippet approves all the related tasks that can be approved, for the current logged in user, either for a review or a composite task:

var allTasks = CalendarIntegration_1.getRelatedTaskIds();

for (var i=0; i<allTasks.length;i++) {
	var task = CalendarIntegration_1.getCalendarTaskById(allTasks[i]);
	
	if (task.getType() === CalendarTaskType.CompositeTask) {
		var compositeTask = cast (Type.CalendarCompositeTask, task);
		var canApprove = compositeTask.canUserApprove();
		if (canApprove) {
			console.log("Approving task with details" + task.getName() + "and with id" + task.getId());
			console.log(compositeTask.approve());
		} else {
			console.log("Cannot approve task with details" + task.getName() + "and with id" + task.getId());			
		}
	} else if (task.getType() === CalendarTaskType.ReviewTask){
		var reviewTask = cast (Type.CalendarReviewTask, task);
		var canApproveReviewTask= reviewTask.canUserApprove();
		if (canApproveReviewTask) {
			console.log("Approving task with details" + task.getName() + "and with id" + task.getId());
			console.log(reviewTask.approve());			
		} else {
			console.log("Cannot approve task with details" + task.getName() + "and with id" + task.getId());	
		}
	}
}

Use `canUserReject` API

You can use the canUserReject API for the user role reviewer on a composite task or for the userrRole assignee on a review task, to check if the task can be rejected.

Sample Code

The following code snippet rejects all composite task for the current logged in user:

var allTasks = CalendarIntegration_1.getRelatedTaskIds();

for (var i=0; i<allTasks.length;i++) {
	var task = CalendarIntegration_1.getCalendarTaskById(allTasks[i]);
	
	if (task.getType() === CalendarTaskType.CompositeTask) {
		var compositeTask = cast (Type.CalendarCompositeTask, task);
		var canReject = compositeTask.canUserReject();
		if (canReject) {
			console.log("Rejecting task with details" + task.getName() + "and with id" + task.getId());
			console.log(compositeTask.reject());
		} else {
			console.log("Cannot reject task with details" + task.getName() + "and with id" + task.getId());			
		}
	} 
}

Use `canUserDecline` API

You can use the canUserDecline API for the user role assignee on a composite or a general task to verify if the task can be declined.

Sample Code

The following code snippet verifies if the logged in user can decline the current opened task:

var task = CalendarIntegration_1.getCurrentTask();

if (task.getType() === CalendarTaskType.CompositeTask) {
      var compositeTask= cast (Type.CalendarCompositeTask, task);
      console.log(compositeTask.canUserDecline());
} else if (task.getType() === CalendarTaskType.GeneralTask){
     var generalTask = cast (Type.CalendarGeneralTask, task);
     console.log(generalTask.canUserDecline());
}

Use Calendar Integration Technical Objects and Calendar Task APIs

Add a Calendar Integration Technical Object

Use getCurrentTask API

Use getStatus API

Use getType API

Use hasUserRole API

Use submit API

Use decline API

Use approve API

Use reject API

Use getCalendarTaskById() API

Use activate() API

Use getRelatedTaskIds() API

Use createCompositeTask() API

Use the Status Change APIs for a Calendar Composite Task

Use Calendar Task Convenience APIs

Use canUserSubmit API

Use canUserApprove API

Use canUserReject API

Use canUserDecline API

Use `getCurrentTask` API

Use `getStatus` API

Use `getType` API

Use `hasUserRole` API

Use `submit` API

Use `decline` API

Use `approve` API

Use `reject` API

Use `getCalendarTaskById()` API

Use `activate()` API

Use `getRelatedTaskIds()` API

Use `createCompositeTask()` API

Use `canUserSubmit` API

Use `canUserApprove` API

Use `canUserReject` API

Use `canUserDecline` API