Tasks and Notes

Querying Data for Task Creation

var data = await dms.TasksAndNotices.LoadTaskCreationItems();

This loads a structure containing the data needed to create a task.

Users assigned to task functions are usually specified with a DMS ID, instead of the Xid from STP UserManagement.

Querying Tasks

For Users/Groups

var loadType = LoadTasksModus.Mine;
var taskIds = await dms.TasksAndNotices.LoadTaskIds(loadType);
var tasks = await dms.TasksAndNotices.LoadTasksByIds(taskIds);

This returns a list of TaskReadDto with the tasks currently active for the user. You can also query other lists by changing the mode. For example, if you want to act as a substitute for a colleague:

var taskIds = await dms.TasksAndNotices.LoadTaskIds(LoadTasksModus.InBehalfOf, userOrGroupId);

This way, you get the open tasks for the user/group you are substituting for.

With an additional, optional parameter, you can also load completed tasks. However, this can result in very large result sets, so use this option with caution.

var allTaskIds = await dms.TasksAndNotices.LoadTaskIds(LoadTasksModus.Mine, null, true);

For Document, File/Folder

You can also query tasks based on their relation to a document.

var includeFinished = true;
var documentTaskIds = await dms.TasksAndNotices.LoadTaskIdsForDocument(documentId, includeFinished);

This will retrieve all tasks for a document.

If you use the following call …

var includeFinished = true;
int? trayId = null;
var containerId = new Guid(...);
var documentTaskIds = await dms.TasksAndNotices.LoadTaskIdsForContainerRegister(containerId, trayId, includeFinished);

… you will get all tasks for all documents in the file/folder. Alternatively, you can limit the call to a specific register (sub-registers are NOT included).

Creating a Task

A task is assembled using a creator.

var creator = TaskCreator.RegularTaskForUser(documentId);
creator.SetText("Task text");
creator.AddUser(userId);

With this creator, the API can then create the task.

var success = await dms.TasksAndNotices.CreateTask(creator);

Working with Tasks

Changing Data

The data of a task can change over time (as long as it is not completed). However, not all data can be changed.

var modifications = new ModifyTaskModel();
modifications.Reminder = tomorrow;
var modifiedTask = await dms.TasksAndNotices.ModifyTask(task.Id, modifications);

With the help of ModifyTaskModel, you can change an existing task. All properties are nullable. Only the values you set will be changed for the task identified by the ID.

Commenting on a Task

var commentPlain = "A comment";
var commentRtf = "{\rtf1\ansi\...}";
var result = await dms.TasksAndNotices.AddCommentToTask(task.Id, commentRtf, commentPlain);

The comment is appended to the task text, separated by a line saying “Comment by {user} on {date}”.

Answering a Task

TaskReadDto taskDto = ...
var manager = await dms.TasksAndNotices.GetTaskManager(taskDto);
var creator = TaskCreator.Answer(taskDto);
creator.SetText("Follow-up question ...");
await manager.AnswerTask(creator);

When you answer a task, the current task is set to ‘Completed’ and a new task is created, which is sent to the sender of the current task. This function cannot be called with list steps!

Forwarding a Task

If you are not the right person to handle a task, you can forward it to another user. The task itself remains unchanged; only the assignee is changed.

TaskReadDto taskDto = ...
var manager = await dms.TasksAndNotices.GetTaskManager(taskDto);
var forwarder = manager.CreateForwarder();
forwarder.ToUser(userId);     //userId is long.ToGuid.
or
forwarder.ToGroup(groupId);   //groupId is long.ToGuid.
await manager.ForwardTask(forwarder);

Completing a Task

TaskReadDto taskDto = ...
var manager = await dms.TasksAndNotices.GetTaskManager(taskDto);
await manager.FinishTask();

Querying Notes for a Document

var notices = await dms.TasksAndNotices.LoadNoticesForDocument(documentId);

This will give you a list of notes set on the document.

Create Note

To create a note, the TaskCreator is used again.

var creator = TaskCreator.Note(documentId);
creator.SetText("Text der Notiz");
var success = await dms.TasksAndNotices.CreateTask(creator);

Task Lists

Start

To start a task list, you need its definition. You can load it with the following command.

var taskListDefinitions = await dms.TasksAndNotices.LoadTaskLists();

Important: Since version 2021.11.22.45, data is only loaded from the server once when using LoadTaskLists, and is then kept in an internal API cache.

The result of this method is a hierarchical structure, which matches the one from the management dialog in the Firm settings:

To find the task list definition for a specific ID, you can use the following command:

var taskListInfo = await dms.TasksAndNotices.FindInfoInCategorie(taskListDefinitions, taskListId);

To start a list, you proceed similarly to starting a single task. First, you need a creator, which can then be configured as needed.

var creator = new TaskListCreator(taskListInfo, documentId);
creator.SetFirstUser(userId);

var success = await dms.TasksAndNotices.StartTaskList(creator);

After a task list has been started, you can perform various actions on the individual tasks created by it. This also depends on the type of task list.

Checklist

Entries in a checklist are all created immediately when the list starts and can be checked off in any order. To do this, the checklist entry is marked as "done" using the method dms.TasksAndNotices.FinishTaskListStep(finisher) and can be given a comment if needed.

The Other Task Lists

There are 3 other types of task lists, which are not quite as straightforward to handle.

Complete Task Step

For this, a TaskListStepFinisher is needed. This is required because there are many options here.

var finisher = await dms.TasksAndNotices.GetFinisherForTaskListStep(taskId, taskListInfo);

The taskListInfo must match the specified task. In the data structure returned by GetActiveTasks(), the ID of the task and the task list are included. If these do not match, an exception is thrown.

With the finisher, you can now change the user for the next step, or for flexible task lists, you can also select the next step.

finisher.MoveToStep(5);
finisher.SetUser(userId);

Finally, you pass the finisher to the method to complete the corresponding task step:

var success = await dms.TasksAndNotices.FinishTaskListStep(finisher);

Cancel Task List

To cancel the processing of a list at the active step, call the following:

var success = await dms.TasksAndNotices.AbortTaskList(taskId);

ModifyTaskModel

The following describes the structure of the ModifyTaskModel class. All properties are nullable. If a value is set, it will be changed for the task. If it remains null, the task keeps its current value.

The Permission column in the table indicates who is allowed to change the value.

UserDto

TaskReadDto