Developer Platform (August 2017)

ePortfolio Data Export/Import

«  ePortfolio Collections   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  ePortfolio Activities  »

Contents

The ePortfolio service provides a number of actions you can use to export EP data into a file that you can save offline and later import back into the same, or another, ePortfolio service.

To export ePortfolio data from the service, follow this general work-flow:

  1. Use one of the two POST actions to declare to the service what sort of data export you want: gather a specific set of EP objects, or gather all the EP objects owned by the current user context.
  2. Use the status action periodically to track the progress the service is making on the export task.
  3. Use the package action to fetch the completed export task as a package.

To import ePortfolio data back into a service:

  1. Use one of the two POST actions to start importing the data:
  2. Use the status action periodically to track the progress the service is making on the import task.

Attributes

JOBSTATUS

EP import and export actions can take a long time to complete; accordingly there’s an initiating action to start a job on the service, and a way to check the status of an initiated job: the service organizes status into several general types and we use the term JOBSTATUS to stand in for an appropriate integer value:

Job status Value
Queued 0
Aborted 1
Complete 2
CompleteWithErrors 3
Processing 4
EP.EpImportJobResponse

When you use an action to create an import job with some immediate response details, the details get sent back in a JSON data block that looks like this:

{
    "ImportJobResultType": <string>,
    "SuccessfulJobIds": [ <number:D2LID:jobid> ],
    "FailedUserIds": [ <number:D2LID:userId> ],
    "ErrorMessages": [ <string> ]
}
SuccessfulJobIds
List of import task ID values that you can use to retrieve the status of each import task.
FailedUserIds and ErrorMessages
Paired lists of User IDs for which an import task cannot proceed, and error messages describing in each case, why.

Action

Export

GET /d2l/api/eP/(version)/export/(exportId)/package

Retrieve the packaged results of a particular export task.

Parameters:
  • version (D2LVERSION) – API version.
  • exportId (D2LID) – Export task ID, as returned from one of the export preparation POST actions.
Status Codes:
API Versions:
  • 2.5+ – Route first appears in EP v10.4.0.
  • 2.4-Obsolete as of EP 10.7.0.

Return. This action retrieves a file stream containing all the EP objects packaged as a result of your initiated export task. The package will have the mime-type application/zip and be an unencrypted compressed bundle of one or more XML files.

The file-name for the bundle will concatenate (with underscores) the string eP_Export, the First Name of the calling user, the Last Name of the calling user, and a timestamp (to the minute only, no timezone information) and be provided in the response’s Content Disposition header.

GET /d2l/api/eP/(version)/export/(exportId)/status

Retrieve the status of a particular export task.

Parameters:
  • version (D2LVERSION) – API version.
  • exportId (D2LID) – Export task ID, as returned from one of the export preparation POST actions.
Status Codes:
API Versions:
  • 2.5+ – Route first appears in EP v10.4.0.
  • 2.4-Obsolete as of EP 10.7.0.

Return. This action retrieves a JSON data block including a single number describing the status of your initiated export task.

POST /d2l/api/eP/(version)/export/new

Prepare to export an identified list of EP objects.

Parameters:
Query Parameters:
 
  • includeFormsItems (boolean) – Optional. If “true”, include all form items.
  • includeAssociatedReflections (boolean) – Optional. If “true”, include any object reflections associated with your identified EP objects. Deprecated since API version 2.1 (EP v4.0.0).
  • includeReflectionsAssociations (boolean) – Optional. If “true”, include any EP object associations of the reflections identified within your list of EP objects. Deprecated since API version 2.1 (EP v4.0.0).
  • includeAssociatedItems (boolean) – Optional. If “true”, include any EP objects associated with your identified EP objects. Introduced with API version 2.1 (EP v4.0.0).
JSON Parameters:
 
  • ObjectIds (JSON array of numbers) – EP objects to retrieve.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Empty list of EP object IDs provided, or no matching EP objects found.
  • 403 Forbidden – No permission to export identified EP objects.
  • 404 Not Found – Could not create a valid export task ID.
API Versions:
  • 2.5+ – Route first appears in EP v10.4.0.
  • 2.4-Obsolete as of EP 10.7.0.

Input. Your post body should provide a JSON array of numbers to indicate the EP object IDs that you want to retrieve (note that you must provide a JSON array, even if you only want to retrieve a single object ID):

[
   1234,
   9876
]

Return. This action retrieves a JSON data block including a single number you can use to identify the export task the service will work on.

POST /d2l/api/eP/(version)/export/new/all

Prepare to export all EP objects owned by the current user context.

Parameters:
Status Codes:
API Versions:
  • 2.5+ – Route first appears in LMS v10.4.0.
  • 2.4-Obsolete as of LMS v10.7.0.

Return. This action retrieves a JSON data block including a single number you can use to identify the export task the service will work on.

Import

GET /d2l/api/eP/(version)/import/(importId)/status

Retrieve the status of a particular import task.

Parameters:
  • version (D2LVERSION) – API version.
  • importId (D2LID) – Import task ID, as returned from the import preparation POST action.
Status Codes:
API Versions:
  • 2.5+ – Route first appears in LMS v10.4.0.
  • 2.4-Obsolete as of LMS v10.7.0.

Return. This action retrieves a JSON data block including a single number describing the status of your initiated import task.

POST /d2l/api/eP/(version)/import/new

Prepare to import an export EP package into this service.

Parameters:
Status Codes:
API Versions:
  • 2.5+ – Route first appears in LMS v10.4.0.
  • 2.4-Obsolete as of LMS v10.7.0.

Import. Your post body should contain the EP export package file to upload in an RFC1867-style simple POST form. The file form data part’s content disposition header should have a name property of file.

If your post body includes only the EP export package file, this call imports the package to the calling user context’s ePortfolio. You can also optionally include a list of user ID values to indicate users, other than the calling user, that should receive the imported package. To choose this, you need a separate form-data part for each target user ID value.

Return. This action retrieves a JSON array of import task ID values that you can use to retrieve the status of each import task.

Note

When you use this action to create a task to import to a user other than the calling user context, the import task is owned by that user, and not the calling user context. Thus, you must use a user context for the target user to retrieve the job status for that target user’s import task; the order of items in the JSON array returned should be in the same order as the order of target user IDs you provide in your request.

POST /d2l/api/eP/(version)/import/newwithdetails

Prepare to import an export EP package into this service with immediate feedback on the request.

Parameters:
Status Codes:
API Versions:
  • 2.5+ – Route first appears in LMS v10.4.0.
  • 2.4-Obsolete as of LMS v10.7.0.

Import. Your post body should contain the EP export package file to upload in an RFC1867-style simple POST form. The file form data part’s content disposition header should have a name property of file.

If your post body includes only the EP export package file, this call imports the package to the calling user context’s ePortfolio. You can also optionally include a list of user ID values to indicate users, other than the calling user, that should receive the imported package. To choose this, you need a separate form-data part for each target user ID value.

Return. This action retrieves a EpImportJobResponse JSON block containing immediate known details of your import request:

  • A list of import task IDs for import tasks that can proceed
  • A list of any user IDs for which the import task cannot proceed
  • A list of error messages matching the list of user IDs, one for one

«  ePortfolio Collections   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  ePortfolio Activities  »