Future Student Document Upload API Specification

Overview

This API allows for the uploading of documents for future students into the document management system (DocMan). It is designed for testing purposes and follows the standards and patterns outlined in the Synergetic API Patterns and Rules.

Preconditions / Synergetic Setup

Identify or create Future Student in Synergetic for testing
Verify that the necessary configurations (luDocumentSourceCode, luDocumentClassification, luDocumentType) match the intended tests (refer to Acceptance Criteria)
Ensure the values to be used in these reference tables have been flagged for use by external API clients

example of “EnabledForClientAPI” flag in lookup table
Ensure that “Load User Profile” in the Advanced Settings of the application pool used by CoreAPI is set to True. This is needed to ensure that the directory used when scanning for viruses is accessible.

Virus scanning is configured using the System|FileUpload|VirusScan|Enabled config key

Endpoint

Route: apiportal/v1/FutureStudent/Document

HTTP Method

POST

Request Payload

The request payload should be of the multipart/form-data type. The document should be attached as shown below. The SourcePath will be inferred from the file metadata. All other metadata should be form-data fields.

Required Fields

ID: The ID of the future student.
Description: A description of the document.
SourceCode: The document source code (from luDocumentSourceCode).
SourceDate: The date the document was sourced.
SourceReference: A reference for the source of the document.
SourcePath: The path of the source, given in the file metadata as the filename.
File: The document file, attached as a file. Field name should be File.
ClassificationCode: The classification code (from luDocumentClassification).

Example Request

POST /apiportal/v1/FutureStudent/Document HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="ID"

12345
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="Description"

Student Transcript
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="SourceCode"

SC001
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="SourceDate"

2024-11-12
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="SourceReference"

Ref123
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="ClassificationCode"

CC001
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="File"; filename="transcript.pdf"
Content-Type: application/pdf

<file content here>
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Response Payload

The response will be in JSON format and will vary depending on the result of the request.

Success

JSON

{
  "RowNum": 1,
  "Result": {
    "DocumentSeq": <tDocumentSeq of the created document>
  }
}

Validation Failure

JSON

{
  "RowNum": 1,
  "Result": {
    "ValidationDetails": [
      {
        "FieldName": "<name of field failing validation>",
        "Reason": "<reason field failed validation>"
      }
    ]
  }
}

Non-Validation Error

JSON

Acceptance Criteria

Happy Path

GIVEN a client has a request payload including all required information
AND the ID matches a future student
AND all other information is valid

WHEN the client sends that request by calling the API to upload a document with the payload

THEN the document is created
AND all relevant fields populated with supplied values
AND the document is linked to the given ID
AND a success response is returned