Local API - Linked Documents within SIMS 7

Updated 31/5/2023

Linked Documents within SIMS 7

This sections explains what Linked Documents in SIMS are and provides sample code to access and create them.

SIMS contains a 'Document Server' which stores linked attachments to various entities within SIMS. An "entity" could be a student or member of staff, for example. SIMS offers APIs that enable developers to add and retrieve documents and attachments for these entities. 'Documents' consist of:

• A Type - this generally suggests the purpose of the document.
• A Status:
  • Private - Use this classification with care; the document will only be visible to the person who created it. If this person leaves the school, the document will be orphaned and cannot be seen in SIMS by anyone else.
  • Confidential - The document will be visible to the person who created it and the Senior Management Team.
  • Public - Available to all SIMS users who have access to the relevant entity. Anyone who can see data for a student can also see the student's documents.
• A Summary - A title for the document.
• [Optional] Notes - Further information about the document.
• [Optional] Attachment - An attached file held on the document server.

Different entities may offer different document types. 

The SIMS Document User Interface

Below is an example of a Linked Document for a student. The normal access route is to open the edit form for the entity, in this case a student.

On the right hand side is the links panel (shown below). NB: Pictures are low resolution partly to show principle rather than focus on the entity concerned.

Click on Linked Documents.

You will now see a list of linked documents for the student.

Documents can be added to or edited

 

Concepts

A "Linked Document" is the entire window above, which contains a note and a summary. 

The pdf / Word document /other file which is optionally added is not the 'Linked Document' but simply an 'attachment' to the Linked Document. 

Security Concepts

Schools may attach any document they choose to a Linked Document. The content of the attachment may or may not be clear from the Summary or the Note fields.   

Student Documents are usually reasonable to share with school staff who are bound by GDPR to access these documents only when appropriate as part of their role.  Staff Documents are usually restricted to the Personnel team (which may just be the head teacher).  However, staff with access have a duty to use the data only for the purpose for which it has been provided and solely as required for their role within the school.

The example document above may be flagged as 'Public' and 'General' and suitable for teaching staff to see but should not be shared with the student or her parents.  The subject matter is sensitive and contains the address of the student / mother which may put them at risk if this is shared with the father.

Documents attached to pupils must not be shared with parents unless somebody in the school with appropriate authority approves and takes responsibility for the decision. SIMS recommends that external systems record and audit these grants.

 

Code Samples

Accessing Documents via other Entities in code

If you want to obtain the documents linked to an entity (such as all documents linked to a particular pupil) then load the main entity first and then step through the document entities linked to that main entity.

The code sample below steps through each document loaded for the pupil with a person_id of 4030.

//instantiate objects
SIMS.Processes.DocManagementCache docCache = new SIMS.Processes.DocManagementCache();
SIMS.Processes.DocumentServers docserv = new DocumentServers();
SIMS.Processes.DocManagementCache.Populate();
SIMS.Processes.EditStudentInformationReadOnly editStudent = new SIMS.Processes.EditStudentInformationReadOnly();
//load editstudent entity for person_id 4030
editStudent.Load(new Person(4030),DateTime.Now);

//step though each document that the student is linked to
foreach (SIMS.Entities.Document gendoc in editStudent.Student.Documents) 
	{
//sample document properties
gendoc.LocalFilename;
gendoc.AttachmentName;
gendoc.DocumentType.DescriptionAttribute.ToString();	
}

Accessing the Document Server directly

This method allows you to create and read documents directly. You will still need to supply a person_id for the documents you want to interact with but you will be able to add documents rather than just view or amend them.

In this sample code a new SIMS Entity of type Document is created, amended and then linked to the ManageEntityDocuments process. The ManageEntityDocuments Save process (loaded for the IDocumentLinkedEntity for student with a person_id pf 6345) is then called linking this new document to the pupil.

//Creates a ManageEntityDocuments process for the person_id you pass in.

SIMS.Entities.IIDEntity identity  = new SIMS.Entities.Person(6345);                 
EditStudentInformation edStudInfo = new EditStudentInformation();
edStudInfo.Load(identity,System.DateTime.Now);
                  
 //create a linkedEntity of type PERSON for the passed in student id.
IDocumentLinkedEntity entity = new DocumentLinkedEntity(edStudInfo.Student.ID, "PERSON");
// create a collection of linkedEntity’s
DocumentLinkedEntitys entitys = new DocumentLinkedEntitys();                  

//set the Entities as of type PERSON.
entitys.MainEntity = new DocumentLinkedEntity(entity.ID, entity.EntityType.CodeAttribute.Value);
entitys.SubEntity = new DocumentLinkedEntity(entity.ID, "PERSON");

//create a new document and set the properties. Example is for a student medical document
Document document = new Document(entitys, InformationDomainEnum.StudentBasic);
document.State = DocumentState.New;             
document.AttachmentNameAttribute.Value = "test.doc";
document.LocalFilename = "d:\temp\test.doc";                
document.DocumentType = SIMS.Entities.DocManagementCache.DocumentTypes.ItemByCode("STUDMED") as DocumentType;
document.SummaryAttribute.Value = "test";       
                  
//create a manageEntityDocuments process, then add in the document from above and save. 
SIMS.Processes.ManageEntityDocuments manEntDoc = new  ManageEntityDocuments(entity);
manEntDoc.Entity.Documents.Add(document);
manEntDoc.Save();       

Attaching a document to Agent

editAgent.Load(5867,System.DateTime.Now); 
Document doc = ((IDocumentLinkedEntity)editAgent.Agent).CreateNewDocument();
doc.DocumentType = (DocumentType)SIMS.Entities.DocManagementCache.DocumentTypes.ItemByCode("SENFDESC");	//You should have all the documenttypes in the DocumentCache
doc.State = DocumentState.New;
doc.AttachmentNameAttribute.Value = "test";
doc.LocalFilename = @"D:\priya\CSSMobileTestBed\CSS Mobile Test Bed.doc"; //This doc is on my local machine
doc.SummaryAttribute.Value = "test";

SIMS.Processes.ManageEntityDocuments manEntDoc = new  ManageEntityDocuments(editAgent.Agent);
manEntDoc.Entity.Documents.Add(doc);
manEntDoc.Save();       

Similar code works for employee and agency.

Retrieving Documents

Warning: It is hard to know what a Linked Document for a student contains and who that document may reasonably be shared with.  Technical Integrators are recommended to obtain express permission from an appropriate user to provide any document to someone by some means and to audit that permission grant.  Any automated provision of documents may have serious consequences and potentially breach GDPR law.

Some documents such as Profiles and individual Assessment reports may be suitable for onward transmission once complete as a batch but TIs are recommended to audit such requests.

​
public static void DMXStudentDocumentExport(int StudentID, ref XmlDocument d, string folderName, DateTime ChangedAfter)
        {
            StringBuilder details = new StringBuilder();
            // Check the existence of the folder requested
            // Create the folder for student's ID.
            details.Append("<Root>");
            SIMS.Entities.IIDEntity identity = new SIMS.Entities.Person(StudentID);
            SIMS.Entities.CalendarCache calCache = null;
            SIMS.Entities.DocManagementCache docCache = null;
            calCache = new SIMS.Entities.CalendarCache();
            docCache = new SIMS.Entities.DocManagementCache();
            SIMS.Processes.DocManagementCache.Populate();
             
            // Show the lucky student's name
            // st.LegalFullName;
            //create a linkedEntity of type PERSON for the passed in student id.
            bool doneOne = false;
            SIMS.Entities.IDocumentLinkedEntity entity = new SIMS.Entities.DocumentLinkedEntity(StudentID, "PERSON");
            SIMS.Processes.ManageEntityDocuments manEntDoc = new SIMS.Processes.ManageEntityDocuments(entity);
            foreach (SIMS.Entities.Document gendoc in manEntDoc.Entity.Documents)
            {
                if (gendoc.AttachmentName != null && gendoc.AttachmentName != "")
                {
                    string extension = ".unknown";
                    string[] parts = gendoc.AttachmentName.Split('.');
                    if (parts.Length > 0)
                        extension = parts[parts.Length - 1];
                    string docFileName = Path.Combine(folderName, gendoc.AttachmentName);
                    //string docFileName = Path.Combine(folderName, Guid.NewGuid().ToString() + "." + extension);
                    if (SIMS.Processes.DocumentManagement.DownloadAttachment(gendoc, docFileName, false, false))
                    {
                        if (File.Exists(docFileName))
                        {
                            if (!doneOne)
                            {
                                details.Append(OpenXML(InnerDocListTag));
                                details.Append(Wrap(Tag_StudentID, StudentID.ToString())); // ID  
                                details.Append(OpenXML(Tag_Documents));
                                doneOne = true;
                            }
                            // Add the Summary if the doc got downloaded - otherwise there is nothing to do.
                            details.Append(OpenXML(Tag_Document));
                            details.Append(Wrap(Tag_DocumentSummary, gendoc.Summary.ToString())); // Summary
                            details.Append(Wrap(Tag_DocumentType, gendoc.DocumentType.Description)); // Type
                            details.Append(Wrap(Tag_DocumentSecurity, gendoc.DocumentStatus.Description)); // Status
                            details.Append(Wrap(Tag_CreatorID, gendoc.CreatedByName)); // Creator
                            details.Append(Wrap(Tag_DocFileName, docFileName)); // Creator
                            details.Append(CloseXML(Tag_Document));
                        }
                    }
                }
                
            }
            if (doneOne)
            {
                details.Append(CloseXML(Tag_Documents));
                details.Append(CloseXML(InnerDocListTag));
            }
            details.Append("</Root>");
            if (doneOne)
            {
                string x = details.ToString();
                d.InnerXml = x;
            }
        }      
        

​

NB: It is essential to create something that knows where the documents are saved to and we understand that there is no API call that reads the document into memory without writing it to disk.  Please remember that code needs to clean up downloaded documents after it has processed them.