Changes in behavior
This topic summarizes changes introduced to Kofax PSIsafe API since the previous release.
Update to file management class
The PSIGEN.Affinity.API.Client.FileManager class for file management was updated. Methods for preparing a file for download are added to this class.
Update to PSIsafe API download document method
The existing PSIsafe Client API Download Document method now gives an error when trying to download a file larger than 50 MB and indicates the need to use a new method from FileManager.
- DownloadDocumentAsync() updated.
PSIsafe Client API download process
If the user calls CreateFileDownloadSessionAsync() to create a download session, the API returns an instance of FileDownloadSession for the new session.
If the user downloads the file from the link, using the provided session ID, the User calls CloseFileDownloadSessionAsync() to close the file download session specifying the DownloadSessionID.
PSIsafe REST API updates
The FilesController for REST API methods is now updated:
- Updated Endpoint api/documents/download to return an error when trying to download a file larger than 50 MB.
- Updated api/documents/import endpoint to accept either the existing FileContent string or an UploadedFileID of a file uploaded using the new file upload process.
- Updated api/documents/checkin endpoint to accept either the existing FileContent string or an UploadedFileID of a file uploaded using the new file upload process.
Download File Storage
The root storage location for file downloads is a subdirectory of the repository specified in the download session: <RepositoryDirectory>\DownloadSessions
- When a new download session is created, a new directory <RepositoryDirectory>\DownloadSessions\<SessionID> is created and the file that user wants to download is copied to this directory
- When a download session is closed, its corresponding session directory in <RepositoryDirectory>\DownloadSessions is deleted.
Download Session details
The Download Session ID should be a GUID to ensure it is a unique value.
- Sessions should have an expiration date so that abandoned sessions can be auto-deleted. The expiration should be 1 day from the time the session is created.
WCF service changes
The WCF service is updated. To support the new file download process, corresponding methods should be created in the WCF service for each new method in the PSIsafe REST API.
Polling process to delete expired sessions
File download sessions are deleted if they are not committed after a certain amount of time (30 minutes). The process runs under the service to monitor for expired sessions and delete them as necessary.
New file chunking methods
File chunking is handled by the API.
- UploadFileAsync(RepositoryID, FileStream): Uploads a file. File chunking is handled internally by the client API using
the upload session and file part uploading methods defined above. Returns the FileID of the uploaded file.
- RepositoryID: The ID of the repository where the file being uploaded will be stored.
- FileStream: File stream pointing to the file to upload.
Updated Request classes
- ImportDocumentRequest: add the following properties to the existing request class:
- UploadedFileID
- DocumentCheckInRequest: add the following properties to the existing request class:
- UploadedFileID
PSIsafe Client API upload process (user handled file chunking)
- User calls CreateFileUploadSessionAsync() to create an upload session
- API returns an instance of FileUploadSession for the new session.
- User calls UploadFilePartAsync() to upload each file part specifying the UploadSessionID, file part number (to maintain
ordering of the file).
- The API generates the SHA1 hash of the file part and reads the length of the file part, which is used by the business layer when saving the file part to validate the file part by 1) verifying the hash of the received file part against the generated SHA1 hash, 2) verifying that the size of the received file part matches the file part size of the stream sent by the user.
- API returns a unique FileUploadPart object for the new the file part.
- User calls CommitFileUploadSessionAsync() to commit the file upload session specifying the UploadSessionID.
- The API validates the upload session and builds the file.
- API returns an instance of UploadedFile for the completed file.
- User can then call either ImportDocumentAsync() or CheckInDocumentAsync() with the provided UploadedFileID.
PSIsafe Client API upload process (API handled file chunking)
If the user calls UploadFileAsync(), passing in the file stream pointing to the file to upload, the API returns an instance of UploadedFile for the uploaded file. User can call either ImportDocumentAsync() or CheckInDocumentAsync() with the provided UploadedFileID.
Uploaded File Storage
The root storage location for file uploads is a subdirectory of the repository directory specified in the upload session. <RepositoryDirectory>\UploadSessions
- When a new upload session is created, a new directory is created to hold the file parts for that session. <RepositoryDirectory>\UploadSessions\<SessionID>
- When an upload session is committed, the files parts are put together to create the completed file. The completed file is stored in <RepositoryDirectory>\UploadedFiles.
- When an upload session is committed or deleted, its corresponding session directory in <RepositoryDirectory>\UploadSessions is deleted.
Upload Session details
- The Upload Session ID is a GUID to ensure it is a unique value.
- Sessions have an expiration date so that abandoned sessions can be auto deleted. The expiration is 1 day from the time the session is created.
WCF Service changes
- To support the new file upload process, corresponding methods have been created in the WCF service for each new method in the PSIsafe REST API.
Business layer changes
A new business layer class is available for file upload methods: busFileUpload
- The following methods are added to the business layer class:
- CreateFileUploadSession()
- Create new record for the session in the FileUploadSessions table.
- Create storage folder for the session.
- UploadFilePart()
- Create new record for the file part in the FileUploadParts table.
- Copy file part to session storage folder.
- CommitUploadSession()
- Validate that the session is complete.
- Build the file from the file parts in the session.
- Move generated file to the uploaded file storage directory.
- Delete the records in the database for the session and file parts.
- Delete the storage folder for this session.
- DeleteFileUploadSession()
- Delete the records in the database for the session and file parts.
- Delete the storage folder for this session.
- GetFileUploadSession()
- Read the session from the FileUploadSessions database table.
- GetUploadedFileParts()
- Read the file parts for the given session from the FileUploadParts database table.
- GetFileUploadSessions()
- Read all the sessions from the FileUploadSessions database table.
- CreateFileUploadSession()
Polling process to delete expired sessions
File upload sessions are deleted if they are not committed after a certain amount of time (3 days).
- Uploaded files that are created when committing an upload session but never used by ImportDocument or CheckInDocument processes are deleted after a certain amount of time (3 days).
- The process runs under the service to monitor for expired sessions/uploaded files and delete them as necessary.