Update.Course.Planner

Updates a planner in a specified course. 

Action

During the update of a planner the following objects are created and updated:

• Planner columns (default and custom) will recreated and updated settings will applied;
• Topics. Deleted topics in the course in the course will restored.
• Lessons (in scope of topic or without topic). Deleted lessons in the course will restored.

Topic and lessons in the course missing in the message will deleted to the trashcan.

All topic and lessons should have unique sync keys. Topic/lessons with the same sync key will excluded from update.

Topic and lessons without sync key also will excluded from update.

Each lesson can also have links to course elements connected with it. There elements should be imported before importing the planner itself.
All rich content is passed through white-list filter. The filtering level is taken according to "Allowed HTML Code Level" option in creator's profile/policy.

Changes  handled via update of planner:

• Topic/lesson titles 
• Topic/lesson description
• Text of any custom column 
• New topics/lesson s
• Deleted topics/lesson s
• Added/deleted LOs
• Added/deleted connected resources (by sync key)
• Lesson thumbnail
• Lesson class hours
• Lesson dates
• Column titles/settings
• Order topics/lessons
• Connection lessons to topics

Scenario

In order to update a planner, a user needs to add a message with type corresponding to action Update.Course.Planner. Result of that message processing can be acquired using GetMessageResult method with message identifier as an input parameter.

Input parameters

Message

ColumnType

CustomColumnDataType

LearningObjectiveType

TopicType

LessonType

ElementSychKeysType

Notes:

• Either CourseID or CourseSyncKey must be specified. This means specify at least one is mandatory.
• Either CreatorUserID or CreatorSyncKey must be specified. This means specify at least one is mandatory.
• It's not possible to import lesson planner into a course, which already contains lesson planner (e.g. there is at least one topic or one lesson created).
• Importing learning objectives through the planner is supported (since the Release 47). Learning objectives can be connected to the topic and the lesson. 
• It is possible to create a columns for learning objectives connected to topics. These columns should have type 'LearningObjectives'. To the topic allows to add a learning objective or category.
• It is possible to customize a name of column for learning objectives connected to a lesson.
• Topics and lessons are assumed to be listed in the order they should appear in the planner.
• Links to assets (i.e. an image) or elements (i.e. an assignment) will be processed in the generic way
• If the planner was disabled for a course, it will be enabled automatically
• If default lesson column is missing in the list of columns, visibility for it will be set to "Nobody" automatically.
• ThumbnailFileId: you can pass FileRepoId, an image should has anonymous access and should be stored in 'Planner' bucket.
• If planner contains topic or lesson with the same sync key, they do not will imported and will shown the warning message.

Best Practice for 3rd Parties:

• The use of topics is optional.
• Titles (topic and lesson) can only contain plain text
• The title for custom columns is mandatory
• Import assets (i.e. an image) and elements (i.e. an assignment) that are used in or linked to from the planner first before importing the planner itself.

Output

Finished Status

• The planner was created successfully. (Returns the message SyncKey).

Warning Status

• Column name '{Column name}': Column name must be plain text. Formatting is stripped.
• Topic '{Topic name}': Topic name must be plain text. Formatting is stripped.
• Lesson '{Lesson name}': Lesson name must be plain text. Formatting is stripped.
• Topic column should always be visible for everyone. Properties 'ShowInGrid' and 'VisibleForAll' are set to true.
• Lesson column should always be visible for everyone. Properties 'ShowInGrid' and 'VisibleForAll' are set to true.
• Lesson '{Lesson name}': Element with id '{ITSLElementSyncKey}' can not be found. Link is removed.

• Item with UniqueId='{LearningObjectiveRepositoryUniqueId}' is not in the national learning objective repository.

• Item with id = '{LearningObjectiveRepositoryUniqueId}' is not a learning objective or category. Only learning objectives and categories can be connected to a topic.

• Item with id = '{LearningObjectiveRepositoryUniqueId}' is not a learning objective. Only learning objectives can be connected to a plan/an element.

• The sync key {topic or lesson syncKey} occurs more than once in the message. {topic or lesson name} with this sync key cannot be imported.
• {topic or lesson name} cannot be imported because doesn't have sync key.

Errors Status

• Invalid format / parameters (different to specified schema).
• Message contains duplicates for syncKeys: {0}. Make sure your syncKeys are globally unique.
• Message must contain valid UserId/UserSyncKey.
• User with specified UserId/UserSyncKey is not valid.
• User with specified UserId/UserSyncKey is deleted.
• User with specified UserId/UserSyncKey is external.
• The use of the lesson planner is disabled on site level.
• Message must contain valid CourseId/CourseSyncKey.
• Course with specified CourseId/CourseSyncKey is not valid.
• Course is deleted.
• Course is external.
• Course is archived.
• The course already contains a planner.
• User {ID} must be added to the course as a teacher or administrator.
• Column IDs must be unique.
• Only columns of the type 'Custom' can exist more than once for the lesson section.
• Only columns of the type 'Custom','LearningObjectives' can exist more than once for the topic section.
• You cannot add lesson related columns to the topic section.
• You cannot add topic related columns to the lesson section.
• At least 1 name of a custom column is blank.
• Lesson '{Lesson name}': Start date is greater than stop date.
• There is no topic column with ColumnId='{Column ID}'.
• There is no topic custom column with ColumnId='{Column ID}'.
• There is no lesson custom column with ColumnId='{Column ID}'.
• Rich content badly formatted or invalid: {Rich content}
• Your security settings doesn't allow you to perform that operation. Please contact administration to grant you an access to {HieararchyName} organisation.

• Course has no Learning Objectives enabled.

• No column assigned to content.

• The column with the id ='{Column ID}' doesn’t allow learning objectives.
• File does not have a valid image format ({Thumbnail file ID}).
• File not found ({Thumbnail file ID})

Schema

Message content example