7.6 File Import API

The File Import API provides a framework for creating technical document content programmatically by extracting data from a selected file. The process works as follows:

1. Using an existing or a new Technical Document, the User initiates the File Import operation by selecting an Action. Note that this Action is only enabled when the Technical Document is in Edit mode.
2. The system prompts the user with a File Dialog, filtered based on configured Document Types (extensions)
3. After the User chooses a single file, the system executes a custom Method that parses the data from the selected file and generates Document Element content
4. The system displays the generated content in a side-by-side view (right side) where the content is read-only
5. The user can copy/merge all generated content with a single operation or can selectively drag and drop individual Document Elements from the view to the opened Technical Document
6. Closing the right-side view discards the generated content

A similar description is provided in the following diagram:

The custom Method (7.6.2.4) is responsible for reading the content from the file and use the Content Generator API (7.1) to programmatically generate Document Element content based on the parsed file data. Thus, custom implementations need only provide the logic to read the specific file format content and use the associated Content Generator Classes/Methods to create document content.

The following example shows how to set up File Import for MS Word (.docx) files

System Administrators provide the following as part of File Import Configuration:

1. Supported Document type(s). This is specified using file name extensions. The system will use this information to filter the files displayed in the File Dialog.
2. Identify whether the system should provide the custom Method with file content in ASCII text format or as binary Base64 format. The latter is required for non-ASCII files.
3. Identify whether the system should store the selected file in the vault. Imported files can first be uploaded and stored in the vault. End-user customizations are responsible for managing these File Items.
4. Identify the Method that will be executed to parse the file data and return the generated Document Elements

Method cui_tdf_ivicb_fileimport_init is used to initialize the Configurable UI (CUI) action for File Import. Within this Method is the JavaScript software to initialize the ImportManager object. The configs array parameter for the ImportManager identifies the configuration for each supported File Type. It needs to be populated. As an example, the following sample code initializes the Import Manager with two file types: JSON, and MS Word.

if (!importManager) {

Promise.resolve(window.TDF || import('../jsBundles/tdf.es.js')).then(() => {

importManager = additionalData.importManager =

new window.TDF.import.managers.FileImportManager({

aras: window.aras,

configs: [{

extensions: ['.json'],

processing: {

methods: ['fi_tdf_importcontent_json'],

},

},

{

extensions: ['.docx'],

processing: {

methods: ['td_WordImporter'],

},

}

]

});

The configs property must be defined to include one or more JSON objects with the following properties:

extensions: array of strings for all related file extensions. Each string identifies the file extension starting with a ‘.’

processing: Identifies one or Method names that will be called in succession after the User has chosen a File for import

reading: Optional (see below)

contextData: Optional (see below)

Method cui_tdf_ivicb_fileimport_click is called when the Import File Action is executed. Within this Method is the JavaScript software that extends the ImportManager configuration with data used for calling the configured Methods. The reading parameter for the ImportManager identifies how the configured Method should be called. For example, the following sample code configures the Import Manager to read the selected File data, provide it as Base64 content to each configured Method, and not save the file to the vault.

if (isEditorActive) {

const { tdfSettings } = tabController.shareData;

const xmlSchema = window.aras.getItemProperty(window.item, 'xml_schema');

const { importManager } = additionalData;

importManager

?.import(null, {

reading: {

readContent: true,

outputFormat: 'base64',

saveFile: false,

},

contextData: {

xmlSchema: xmlSchema,

contentBuilder: tdfSettings.contentBuilderMethod,

},

})

.then((result) => {

if (result) {

const editorWindow =

tabController.views['editor_container'].domNode

.contentWindow;

editorWindow.openImportPanel(result);

}

});

The reading property must be defined to include one or more JSON objects with the following properties:

readContent: If ‘true’, the file contents are read from the selected file and provided as input to the configured Method(s).

outputFormat: Either ‘text’ or ‘base64’(default). This determines the format of the input data provided for the configured Method(s).

saveFile: if ‘true’, the selected file is saved in the Vault. If ‘false’, it won’t.

contextData: Contains configurable options for the schema and Content Builder Methods. In this example, the xmlSchema is retrieved from the opened Technical Document and the contentBuilder uses the default. It is best to leave these values as provided in the sample.

The following example shows a server-side Method used to read data from a MS Word (docx) file and generate Document Elements. Note that the details related to parsing/extracting content from the input file are not included. The code is used to describe how to access the input data and how to use the Schema Factory and Content Generator API to create Document Elements and return the results in the expected format. Much of the code can be copied and used as is.

return Execute(this, RequestState);

}

internal static Item Execute(Item sourceItem, Aras.Server.Core.IContextState requestState)

{

Innovator innovator = sourceItem.getInnovator();

string languageCode = innovator.getI18NSessionContext().GetDefaultLanguageCode();

var executionContextData = Aras.TDF.Base.ComplexObjectJsonDeserializer.Deserialize(sourceItem.getProperty("executioncontext"));

var contextData = executionContextData["context"] as Dictionary<string, object>;

string schemaId = contextData["xmlSchema"] as string;

string contentBuilder = contextData["contentBuilder"] as string ?? "tp_DocumentGet";

         var importData = executionContextData["input"] as Dictionary<string, object>;

var fileContent = Convert.FromBase64String(importData["content"] as string);

var memStr = new MemoryStream(fileContent);

Aras.TDF.Base.SchemaElementFactory factory = CreateFactory(sourceItem, innovator, schemaId, contentBuilder);

factory.CustomContentEnabled = true;

factory.DefaultLanguageCode = languageCode;

using (WordprocessingDocument wordprocessingDocument = WordprocessingDocument.Open(memStr, true))

{

mainDocPart = wordprocessingDocument.MainDocumentPart;

Body body = mainDocPart.Document.Body;

var rootElement = factory.NewBlock() as Aras.TDF.Base.DocumentSchemaElement;

…

}

var importedData = factory.ExportElementToXml(rootElement);

return innovator.newResult(importedData);

}

public static Aras.TDF.Base.SchemaElementFactory CreateFactory(Item thisItem, Innovator innovator, string schemaId, string contentBuilderMethod)

{

if (thisItem == null)

{

throw new ArgumentException("Processing error for File Import");

}

var executionContext = new Aras.TDF.Base.SchemaElementExecutionContext(thisItem.getID(), thisItem.getType(), contentBuilderMethod);

return new Aras.TDF.Base.SchemaElementFactory(innovator, schemaId, executionContext);

1. The context of the Method (this) is the Document Item opened or created as part of the Use Case to initiate the File Import Action (see above). RequestState is not used or needed for this implementation. Note the missing initial curly brace – it is based on the Method template chosen.
2. Input for this Method is passed as a JSON-encoded string. This line de-serializes the data into Objects for ‘input’ and ‘context’.
3. context data is a series of name/value pairs that were defined in the client Action Method (see above). In this case, it includes the XML Schema (DocumentType) and the Content Builder. For the purposes of File Import, this data is only required when instantiating the Schema Factory (#6 below) used for creating Document Elements.
4. input data describes the file being imported. This includes the file name without the path (‘name’), file extension string (‘extension’), file size (‘size’), MIME Type (‘mimeType’), and file content (‘content’).
5. Because the file data was passed as a Base64 stream (see above), it needs to be converted back to the format as it was defined in the file.
6. The embedded method – CreateFactory() – shows the code necessary for creating the Schema Factory used to create Document Elements. This code can be used as is.
7. The Factory object is used as a mechanism to create individual Document Elements. The root element must be a Block as shown on this line.
8. The Factory object is used to convert the entire hierarchy of Document Element Objects into the XML representation needed for the expected return of this Method.
   
   Note

   The XML for the Technical Document content should be generated using the Schema Factor only to ensure compatibility with new and future versions of the Technical Document Editor.
   
   
9. The generated XML is included in the returned result. This is used for display in the right-side view within the Document Editor.

The Import from Document… Menu Item needs to be enabled using the Configurable User Interface configuration. The menus and toolbar buttons for the Technical Document Editor are configured within the TechDoc Presentation Configuration.

Edit the TechDoc Presentation Item to add the itemview.itemcommandbar.tdf Command Bar Section.

Select the Add CommandBarSection button, search for and add the itemview.itemcommandbar.tdf Command Bar as shown, setting the Sort Order and For Identity as required.