UsingExternals
This topic contains the following sections:
- External sources
- Configuration of AutomationML file servers
- Adding references to external libraries
- Define new library versions
- Open documents from external sources
- Displaying and using content from external sources
- Outsourcing of libraries
- Find published classes
CAEX explicitly supports accessing external CAEX files by means of the CAEX element “ExternalReference”. Regarding ExternalReferences, the following provisions apply:
- Each
ExternalReferenceshall reference to another CAEX document of the same schema version. - Each
ExternalReferenceshall provide a valid URI to the external CAEX document and an Alias which shall be unique within the CAEX document. No other information shall be stored. - The referenced external CAEX documents shall be valid and accessible.
The AutomationML Editor supports the configuration of network communication profiles to access an external file server, which can provide AutomationML files to be referenced by ExternalReference elements. A predefined communication profile is provided by AutomationML to access the AutomationML file server managed by the AutomationML association. Currently, only servers, supporting the WebDAV network protocol can be used. The use of the WebDAV protocol is mainly for technical reasons. User rights can be integrated and complete directories can be searched and transferred. WebDAV allows to lock a resource, to prevent the resource from being processed elsewhere on the server while the editor is doing so.
The files provided by the AutomationML association via its file server are divided into the following categories.
- Library files of AML Edition 1
- Library files of AML Edition 2
- Files with application examples
- Files with preconfigured external references
A company's own file server, providing AutomationML files, can be integrated in the same way as the AutomationML server. If a company's own web resource can be accessed via the WebDAV protocol, the editor can also display the resources directory content.
The editor also supports the upload of AutomationML files to a configured file server for the purpose of publication. For publication on the AutomationML file server, the conventions for modeling AutomationML libraries must be observed.
The configuration dialog for an AutomationML file server can be called up in several ways. One option is to call it up via the options dialog. Other options can be found in the dialogs for retrieving external documents and in the publishing dialog, both by clicking a button at the top of the window. The name of the selected file server for the file download or upload is also displayed there.
Server Configuration from the Options Dialog
Server Configuration from the Upload/Download Dialog
The configuration of the standard AutomationML file server cannot be changed. The following image shows an example configuration of a company's own file server.
Server Configuration Dialog
In this server profile, read-only access rights are configured. To search and select AutomationML files, only read-access rights are needed. Write-access rights are only required, when documents are uploaded to the file server in the publication dialog. The standard AutomationML file server is configured with a read-only server profile and a write enabled profile. The write-enabled profile requires the entry of a user name and password for write access. All persons and organizations that are registered for access to the AutomationML NextCloud server are authorized.
Each server profile consists of a basic profile with the server name and, if necessary, a port number. A base path and a global username can also be specified. Password protection is possible but not recommended for read-only profiles, as it is then not possible to share a file by an accessible URI. The file server can manage AutomationML files with special content (categorized as specific document types like library only documents or example documents). To distinguish document content, additional folder profiles must be configured for each document type. These can either use the base user authentication or be configured with separate usernames and passwords. It is also possible to assign a folder profile to a specific AutomationML Edition. A server profile can be saved, whereby all passwords are saved in encrypted form. All saved profiles are loaded when the Editor is started.
References to external libraries can be added in the 'Library-Selection' dialog. The dialog is opened via the AddReference menu item in the File menu. All files published on the activated file server that are classified as library documents and are compatible with the AutomationML Edition currently in use are displayed.
Library Selection and Referencing Dialog
If the file names correspond to the conventions for naming AutomationML files, the displayed collection can be filtered according to the criteria encoded in the file name. A selected file can be inserted once as a reference in the current document. The download URI and the alias name are generated. The alias name can be changed to a more compact form, as long as it is unique in the document. The content of a selected file can be made visible clicking the Preview-Button.
If the Add Reference-Button is clicked, the selected library is included as an ExternalReference into the current document. If the Create New Version-Button is clicked, a new version of the selected document is created. To define the new version numbers for the libraries in the document, a define library versions dialog is shown.
Library versions can be defined for a document that is selected in the "Add reference" dialog. New versions must be defined for the document and all libraries in the document. If the versioned document is only to define extensions for the libraries, the extension must be named.
The Open menu item in the File menu provides two new alternatives to open and edit documents, provided by an activated file server. External collections are AutomationML files which already contain one or more included external references to AutomationML libraries. External examples are documents, modeling use cases for specific AutomationML libraries.
Open external documents
The View Externals menu item in the View menu allows to load views of all documents, referenced in ExternalReference elements of the document. The Documents are identified by the defined alias names, followed by the alias separator.
View external documents
The check box is three state. A box with a check mark indicates, that all libraries in a document are already viewed. A box with a minus sign indicates, that some library views have been closed but not all. An empty check box indicates, that all library views are closed. Unchecking will close all library views.
External libraries are viewed in read-only windows. How to work with external library views, showing some examples, is explained in the Layout section.
If you want to replace class or type libraries in an AutomationML document with external references, use the Outsource function, available via the Outsource libraries menu item in the File menu. This function analyzes the dependencies of the libraries contained in the document, groups the libraries into collections and searches for suitable external documents for each collection. The signed version and current version column for each analyzed library indicates whether the external library is an identical version of the library used. Libraries that are not externally accessible are combined into a separate group. This group can be further subdivided. The associated libraries can also be outsourced or remain in the document.
Outsource Dialog
The grouped libraries are organized topologically. If a group member is selected, the required properties of a link to the external document are generated and displayed. The Outsource function is based on the split function. Externally available libraries are removed from the document and replaced by external references.
Classes and attribute types in publicly accessible libraries can be found and used directly via a new search function. The Find class online function is available via the background menu of the library windows and when selecting an existing class or attribute type.
Find published classes online
The file server can be selected in the search window. The server must have a repository of all published classes. Searches are carried out using the name of the class or attribute type; similar terms are also found if a tolerance (defined using the slider) is used for the search. Two methods are offered for the similarity search, one search uses text comparison and editing operations and the second searches for phonetically similar terms.
If the term you are looking for is found, the library can be integrated via an external reference.
Search and use the online catalog