​
Content Management

​
Upsert

Overview

Our unified LMS API uses an “upsert” approach for content management, ensuring efficient synchronization across various Learning Management Systems (LMS). This means content creation requests will either update existing content or create new content based on matching criteria.

Key Features and Behavior

  • Primary Identifier: external_reference: The API prioritizes external_reference for content matching. If content with the provided external_reference exists, it will be updated.

  • Enhanced Deduplication:

    • In most cases, external_reference is sufficient.

    • If the target LMS supports deduplication based on other attributes (e.g., title), the API leverages these to enhance matching, allowing synchronization with systems containing pre-existing data.

  • Upsert Implementation:

    • If the LMS supports native upsert, it’s used directly.

    • Otherwise, a “get” operation checks for existing content using external_reference and/or other attributes.

  • Response:

    • The API always returns the external_reference.

    • An id is also returned if the LMS requires it for completions/assignments (i.e., doesn’t support external_reference for these operations).

Workflow

  1. Request Submission: Send a content creation request with data and external_reference.

  2. Matching: The API attempts to match content using external_reference and/or other attributes, leveraging native upsert when available, or a “get” check otherwise.

  3. Operation: Existing content is updated or new content is created.

  4. Response: The API returns external_reference, and id if necessary.

  5. Subsequent Operations: Use external_reference (or id) for completions/assignments.

Important Considerations

  • Ensure external_reference is unique and consistent.

  • The id is only provided when the LMS does not support the external_reference for completions/assignments.

  • Matching can occur based on attributes beyond external_reference if the LMS supports it.

Benefits

  • Simplified content management.

  • Data consistency.

  • Efficient operations.

  • Enhanced synchronization with systems containing pre-existing data.

​
Batch Operations

Overview

Our batch functionality streamlines bulk content creation, essential for integrations with LMS systems that impose strict rate limits or require batch processing (e.g. SAP). This allows you to efficiently upload large content catalogs.

Key Features and Behavior

  • Bulk Content Creation: Simplifies the upload of numerous content items in a single request.

  • Rate Limit Management: Handles LMS rate limits by queuing and processing requests as required. Some LMS systems have very low rate limits, and this feature is designed to handle those.

  • Native Batch Support: If the target LMS supports native batch operations, the API utilizes them, managing batch sizes and rate limits automatically.

  • Fallback Batch Processing: If native batch operations are not supported, the API splits the catalog into individual content requests, managing rate limits accordingly.

  • Automatic Batch Splitting: If the submitted batch exceeds the LMS’s maximum batch size, the API automatically splits it into smaller, compliant batches.

  • Underlying Upsert Support: Each item within a batch request is processed using the same upsert logic as individual content requests. This ensures existing content is updated and new content is created as needed.

Workflow

  1. Request Submission: Send a batch content creation request containing the complete catalog list.

  2. Validation and Queuing: The API validates the request and, upon successful validation, returns a 202 Accepted response. The request is then placed in a processing queue.

  3. Processing: The API processes the queued requests, managing rate limits and batch sizes according to the LMS’s requirements.

  4. LMS Interaction: The API interacts with the LMS, either using native batch operations or individual requests

Example Payload

{
  "items": [
    {
      "external_reference": "generic#lo123456789001",
      "title": "Learning Object 1",
      "description": "Generic description for learning object 1",
      "languages": [
        {
          "value": "en_US"
        }
      ],
      "content_url": "https://example.com/learning/object1",
      "content_type": {
        "source_value": "article"
      },
      "cover_url": "https://example.com/images/learning-object1.jpg",
      "active": true,
      "duration": "PT10M",
      "categories": [
        {
          "name": "Category A"
        }
      ]
    },
    {
      "external_reference": "generic#lo123456789002",
      "title": "Learning Object 2",
      "description": "Generic description for learning object 2",
      "languages": [
        {
          "value": "en_US"
        }
      ],
      "content_url": "https://example.com/learning/object2",
      "content_type": {
        "source_value": "article"
      },
      "cover_url": "https://example.com/images/learning-object2.jpg",
      "active": true,
      "duration": "PT15M",
      "categories": [
        {
          "name": "Category B"
        }
      ]
    },
    {
      "external_reference": "generic#lo123456789003",
      "title": "Learning Object 3",
      "description": "Generic description for learning object 3",
      "languages": [
        {
          "value": "en_US"
        }
      ],
      "content_url": "https://example.com/learning/object3",
      "content_type": {
        "source_value": "article"
      },
      "cover_url": "https://example.com/images/learning-object3.jpg",
      "active": true,
      "duration": "PT12M",
      "categories": [
        {
          "name": "Category C"
        }
      ]
    },
    ....
  ]
}

Success Validation

  • Currently, success validation for batch operations is performed by checking the request logs in the StackOne UI. This allows you to verify that the requests were successfully made to the underlying provider.

  • Note: This log checking is specific to batch operations. Individual upsert operations success can be determined by the 201 response.

Future Enhancements

  • Return of content IDs upon initial batch request queuing.

  • A response upon operation completion with a URL in the header linking to request logs.

Important Considerations

  • It is best practice to include as many content items as possible in the batch request.

  • Each item within the batch will be processed with our standard upsert behaviour.

​
Removing Content

Overview

Content removal is handled through two methods, depending on LMS provider support: Soft Delete (universally available) and Hard Delete (provider-dependent).

Removal Options

  • Soft Delete (via Upsert):

    • Sets content to an inactive state, preserving all associated records.

    • Effects:

      • Content is hidden from user views.

      • Content is inaccessible to users.

      • Content remains visible in admin views and API list responses.

      • Completion and assignment records are retained.

    • This is achieved by sending an upsert request with the content and an inactive status.

  • Hard Delete (via DELETE):

    • Permanently removes content.

    • Availability: Dependent on LMS provider support.

    • Provider Restrictions: Often limited due to contractual requirements and the need to maintain completion record relationships.

Key Considerations

  • Soft Delete is available across all providers.

  • Hard Delete availability is subject to LMS provider capabilities.

  • Soft delete is achieved through the upsert endpoint by sending an inactive status.

​
Assignment & Completion Management

​
Creating Assignments & Completions

The creation process for assignments and completions supports two distinct flows, depending on your needs and the desired level of control.

Creation Flows:

  1. User Assignment -> User Completion:

    • Create Assignment: First, create an assignment for a specific user using:

      • The user ID.

      • The content external reference.

      • Any other required assignment data.

    • Create Completion: Subsequently, create a completion for the same user and content, using:

      • The user ID.

      • The content external reference.

      • Any required completion data.

    • This flow allows for explicit assignment creation and tracking before marking it as complete.

  2. User Completion:

    • Create a completion directly using:

      • The user ID.

      • The content external reference.

      • Any required completion data.

    • This flow simplifies the process by directly marking content as complete for a user, handling any underlying assignment creation if necessary.

Key Requirements:

  • All assignment and completion creation operations must be performed as a user sub-resource.

  • The system uses the user ID and the content external reference to associate assignments and completions.

Was this page helpful?

Suggest edits