Skip to content

Modules

Jump to bottom
AccentuSoft edited this page Feb 12, 2022 · 9 revisions

Introduction

Modules are the intended way for users to extend the functionality of LinkScope. Each module is a folder containing zero or more XML files with new entities to install (or existing entities to redefine), and zero or more Python files with new Resolutions to install.

Installing Modules

WARNING: INSTALLING MODULES FROM THIRD PARTIES IS DANGEROUS. ACCENTUSOFT IS NOT LIABLE FOR ANY DAMAGES CAUSED BY THE INSTALLATION, USE OF, OR HANDLING OF MODULES NOT CREATED BY ACCENTUSOFT.

To install a module, simply drop the module folder (it must be a regular folder, i.e., uncompressed) into the 'Modules' folder in the installation directory of the software. Note that certain builds of the software may not support the use of modules, especially in the case of precompiled binaries.

Creating a Module

Creating Entities

Entities are defined in XML Files. The template used follows the format below:

<Name_Of_Entities_Group>
    <Name_Of_Entity>
        <Attributes>
            <Attribute default="Default value for PrimaryField attribute" check="String" primary="True">Primary Field</Attribute>
            <Attribute default="Default value for Field 1 attribute" check="String" primary="False">Field 1</Attribute>
            <Attribute default="Default value for Field 2 attribute" check="String" primary="False">Field 2</Attribute
        </Attributes>
        <Icon>
            PathToSVG.svg
        </Icon>
    </Name_Of_Entity>
</Name_Of_Entities_Group>

The value of 'default' is the default value for the corresponding field.

The value of 'primary' is either 'True' or 'False', and indicates if that field is the primary field or not. Entities must have only one primary field.

The value for 'check' is the type of validation to be performed on the field's value. Acceptable values for 'check' are:

Email
Phonenumber
String
URL
Domain
Float
WordString
Numbers
IPv4
IPv6
MAC
ASN
CUSIP
EIN
LEIID
ISINID
SIC/NAICS

Most of these are self-explanatory. We suggest you use 'String', which verifies that the field is not empty, unless you have a good reason to want to restrict users further.

Note that you may re-define existing Entities (found in the XML Files under the 'Core' folder), or create new XML files in Modules to define custom Entities used by that Module.

WARNING: DO NOT CHANGE AN ENTITY AFTER USING IT IN A PROJECT. DEFINE A NEW ONE INSTEAD.

Creating Resolutions

Resolutions are the functions that make this software useful. Each one of them takes as input one or more entities. Each of those entities may have a different entity type, as long as the resolution supports that type.

Resolutions take the entities given as input, perform some operations, and return some output, which is displayed as entities and connections between entities.

Resolution File Structure

Each Resolution is its own class, and it is stored in a file by itself. The name of the Resolution class and the name of the file must be the same. For example, if someone wants to create a Resolution called Get Movie Quote, it must be created as a class called GetMovieQuote and stored in a file called GetMovieQuote.py.

Resolution Class Variables

Each Resolution class declares the following variables:

  • name: Returns a string that is the name of the Resolution.
  • description: A string that describes the Resolution.
  • originTypes: A set of entity types that are accepted as input by the Resolution. The asterisk symbol (i.e., '*') can be used to denote that any entity type can be taken as input.
  • resultTypes: A set of entity types that the Resolution could produce as a result of its operations. The asterisk symbol (i.e., '*') can be used to denote that any entity type can be produced as output.
  • parameters: A dictionary that declares variables that the resolution accepts as input. The names of the variables are the keys in the dictionary. The value of each one is another dictionary, with the following fields:
    • 'description': A string containing a description for this variable.
    • 'type': A string. One of: 'String', 'File', 'SingleChoice', 'MultiChoice'. This defines how the user will input a value for this variable. Strings have a text input, Files show a file manager, SingleChoice offers radial buttons (one can be selected), and MultiChoice offers checkboxes (multiple can be selected).
    • 'value': The placeholder that appears in the input field for string and file inputs. This is expected to be a blank string (i.e., '') in these cases, to prompt the user to enter something. For single and multi choice inputs, this is instead a set containing all the options that the user is expected to choose from.
    • 'default': The default, pre-selected value for this parameter. The default string is already written in the input field (or selected, in the case of SingleChoice) and needs to be deleted by the user, if the user wants to input a different string. The value of this field is expected to be a string, except in multi choice inputs that it is a list of the strings to be preselected.
    • 'global': This is a boolean parameter that determines whether this parameter should be globally used. For these to apply, the name of the parameter should be the same in all files in order to be considered global. In other words, Resolution parameters with the same parameter name, and the global field set to True, will inherit the input that was entered in any one of those fields, provided that the user checks the 'Remember Choice' check box.

Note that all parameters have to be filled in to launch the Resolution. If you are making a resolution where the user may not need to provide input for a parameter, offer the user a choice that is 'Skip' or similar for Single and Multi Choice inputs. For String inputs, the user could be asked to type 'Skip' into the input box.

Resolution Class Function

Each Resolution class has to have a function called 'resolution'. This is the function that is called to perform the necessary operations.

The resolution function has two inputs that are expected:

  • entityJsonList: This is a list containing the JSON representation of the entities that are to be used as input.
  • parameters: This is a dictionary containing the names of each of the properties of the Resolution as keys, and the user's input as the value. All types of parameters have value type of string, except for MultiChoice, which returns a list of strings instead. The parameter key 'Project Files Directory' is reserved and returns the path to 'Project/FilesDir', which is the directory containing the Project Files. The parameter key 'Server Project Document Details' is also reserved, and is used by the server to determine where the Server Project's data is stored. Using any of those parameters will mean that the value stored will be overwritten.

The Resolution Class Function can return the data structure described below in 'Resolution Output Format', to display links and entities on the Canvas. The function can also return a string in case of error, to show a pop up and inform the user of what happened.

Resolution Output Format

In order to understand the data structure given as the output, we will walk you through a simple example that explains the reasoning behind the output format. The example will walk you through the logic behind each design decision, to demonstrate the flexibility of Resolutions.

We begin with an example Resolution. The input to the Resolution is a list containing the capital letters of the English alphabet:

[A, B, C...]

The Resolution could produce all manner of output depending on the operations it performed. For each input letter for example, the Resolution could try to find the lowercase equivalent, which would give us as an output the list containing the lowercase letters of the English alphabet:

[a, b, c...]

A list of entities is fine and all, but we also need the relationships between the output entities and the input entities. This is because multiple output objects could be produced for each input value, and not all Resolutions are as straightforward as this example.

Each input entity has a unique identifier, a uid field.

For simplicity, the uid field of entity A will be denoted as Au, the uid field of entity B will be denoted as Bu, and the uid field of entity C will be denoted as Cu.

Matching each output entity with the input entity that created it, we get the following data structure:

[[a, Au], [b, Bu], [c, Cu]...]

Simple enough. However, there is one thing that we have not accounted for: Some Resolutions may want to generate connections between the output entities.

In order to facilitate that, we will need a way to refer to the output entities. Note that the output entities do not have a uid field yet. We can solve this problem through references to the indices of the output list, since the order of lists is fixed in Python3:

[Index 0, Index 1, Index 2...]

[[a, Au], [b, Bu], [c, Cu]...]

Assume that the item c is to be linked to the item a, and their relationship is that c is the parent of a. We can express this with the following data structure:

[[a, [Au, 2]], [b, [Bu]], [c, [Cu]]...]

One final step further: The Resolution will want to provide a name and possibly some notes for each of the links. This can be done through the use of dictionaries, like so:

[[a, {Au: {'Resolution': 'A', 'Notes': ''}, 2: {'Resolution': 'c-a', 'Notes': ''}}], ...]

That is the output format expected by the software from Resolutions. Do note that we have been using capital and lowercase letters as proxies for the actual objects. In the software, these would be JSON objects (i.e. dictionaries), and the uid fields would be the actual uid values of those dictionaries (i.e. Au would be A['uid']).

The software differentiates between input items and output items in the innermost lists in a simple way: The uid field has a value that is of the type 'str'. Integers in Python3 are of the type 'int'. By checking what type the parent item reference is, the software can identify what input and output entities each output entity should be linked to.

Regarding the actual structure of the output entities, it should be a JSON object with at least two keys:

  • The primary field for the output entity type. For example, for the 'Person' entity type, the field 'Full Name' should have a value that is not None.
  • The 'Entity Type' field. This is to tell the software what type of entity it is that the JSON represents. Note that if the entity name in the XML file it is defined in has underscores, those are treated as spaces by the software. For example, if an entity is named 'London_Bridge', when setting the entity type of the resulting entities in the resolution, you should set 'Entity Type' to be 'London Bridge'.

It is convention to declare the primary field as the first key in the JSON object. However this is not required or expected, since dict objects sent across the network do not necessarily keep the order of their keys.

Remember: The entity attributes you are reading could be 'None'. Do not assume that they have a proper value.

An example Resolution is included in the 'Example' module, found in the 'Modules' folder. It can be used as a template to create new Resolutions.

Clone this wiki locally