Skip to content

Application configuration

Jump to bottom
Ioan Crișan edited this page Nov 26, 2019 · 14 revisions

Application configuration

The configuration files are stored in the Config sub directory of the application. They may come with some preset values, but they will typically require editing, either manually or through the commands within the application.

Their structure is the common JSON format, and for each purpose there will be a specific file containing the required settings.

Setting up document fields

The application allows to configure document fields at various levels. The rule is that the fields are added from the top level to the bottom level, overwriting their values if the same name is used. For example, for the file system source, the fields are added in the following order:

  • Application level: default fields set up in the sharePointSettings.json file.
  • Source level: fields set up in the fileSystemSettings.json file.
  • Folder level: fields set up for the folder containing the document.

The lower the level, the higher the priority of the fields.

Let's consider the following configuration, based on the example above:

  • sharePointSettings.json
{
    ...
    "defaults": {
        ...
        "fields": {
            "RequireOCR": true
        }
    }
}
  • fileSystemSettings.json
{
    "fields": {
        "Source": "Scan",
        "RequireOCR": false
    },
    "syncFolders": [
        ...
        {
            "path": "D:\\Temp\\ToSyncUnknown",
            "fields": {
                "Source": "Unknown",
                "RequireOCR": true,
                "Kind": "Other"
            }
        }
    ]
}

The application will add the following fields to the document:

  1. RequireOCR: true from the application level settings.
  2. Source: Scan from the file system source level, and also the RequireOCR's value will be overwritten with false.
  3. Source: Unknown from the folder level will overwrite the Scan value, RequireOCR will be overwritten again with true, and Kind: Other will be added.

Finally, the document will have the following fields:

  • RequireOCR: true
  • Source: Unknown
  • Kind: Other

sharePointSettings.json file

Purpose

Contains the Microsoft SharePoint Online connection information and default settings applied to all sources, folders, and accounts.

  • sites: the named list of SharePoint sites to connect to.
    • siteUrl: the URL to the Microsoft SharePoint site. It has a typical form of https://<mytenant>.sharepoint.com/sites/<mysite>.
    • userName: the Azure AD account of the user connecting to the Microsoft SharePoint site. This user should have read-write permissions for all the target libraries/lists where the documents should be stored.
    • userEncryptedPassword: the encrypted password of the user configured above. Check the encrypt command for more information about how to get an encrypted password.
    • userPassword: the plain password of the user configured above.
      • Avoid using this value in the long run, use it only for the initial connection testing and, after that, switch to the encrypted password.
      • Do not use both userPassword and userEncryptedPassword settings at the same time. Even though the application will not complain, it is not ensured that a specific setting is used.
  • defaults: section containing document related settings, applied to all sources.
    • maxFileSize: the maximum size in bytes of the documents accepted for upload. Default value: 10485760 (10 MB).
    • library: the default library where the documents should be uploaded. If a source does not specify a target library, this value is used for document upload. Default value: Unsorted.
    • syncIdField: The name of the list field/column storing the internal synchronization ID. Type: one-line text. Default value: SyncID.
    • syncToolField: The name of the list field/column storing the ID and version of the application that uploaded/synchronized the document. Used for informational purposes. Type: one-line text. Default value: SyncTool.
    • textContentField: The name of the list field/column storing the extracted text from the uploaded document. For documents needing OCR, this is the place where the extracted text will be stored, to enable full-text search over the documents. Type: multi-line text. Default value: TextContent.
    • originalNameField: The name of the list field/column storing the original file name. Type: one-line text. Default value: OriginalName.
    • parentIdField: The name of the list field/column storing the SyncID of the container document. A typical case are mail messages, where the extracted attachments hold a reference to the container message. Type: one-line text. Default value: ParentID.
    • groupField: The name of the list field/column storing the group. This can be used to group the documents based on their logical association.
      • For mails, this is the document name of the mail. Using it, the original mail and the attachments can be displayed together.
    • keywordsField: The name of the list field/column storing the search keywords. Type: one-line text. Default value: Keywords.
    • fields: A list of fields to be applied to all uploaded documents, regardless of source.

Example

{
    "sites": {
        "<mysite-1>": {
            "siteUrl": "https://<mytenant>.sharepoint.com/sites/<mysite-1>",
            "userName": "<user@my-tenant.com>",
            "userPassword": "<user-password>",
            "userEncryptedPassword": "<some-long-text-containing-the-encrypted-password>"
        },
        "<mysite-2>": {
            "siteUrl": "https://<mytenant>.sharepoint.com/sites/<mysite-2>",
            "userName": "<user2@my-tenant.com>",
            "userPassword": "<user2-password>",
            "userEncryptedPassword": "<some-long-text-containing-the-encrypted-password>"
        }
    },
    "defaults": {
        "maxFileSize": 10485760,
        "library": "Unsorted",
        "syncIdField": "SyncID",
        "syncToolField": "SyncTool",
        "textContentField": "TextContent",
        "originalNameField": "OriginalName",
        "parentIdField": "ParentID",
        "keywordsField": "Keywords",
        "fields": {
            "AField": "<a-field-value>",
            "AnotherField": "<another-field-value>"
        }
    }
}

ruleSettings.json file

The service supports rules for automatically setting field values based on keyword matching and this file contains the rules. They will be executed in their defined order.

{
    "keywords": [
        {
            "match": [ "kunden", "kunde" ],
            "fields": {
                "PartnerKind": "Kunde"
            }
        },
        {
            "match": [ "lieferanten", "lieferant" ],
            "fields": {
                "PartnerKind": "Lieferant"
            }
        },
        {
            "match": [ "invoice", "rechnung", "rechnungen" ],
            "library": "Invoices",
            "fields": {
                "DocumentKind": "Rechnung"
            }
        },
        {
            "match": [ "kephas-software.com", "kephas-software" ],
            "fields": {
                "Partner": "Kephas Software SRL"
            }
        }
    ]
}
  • match: contains an array of keywords. If any of the keywords matches the document keyword, the rule fields will be added/overwritten.
  • library: overwrites the document library when the document keywords match the list of rule keywords. Optional.
  • fields: the fields to be added/overwritten when the document keywords match the list of rule keywords. Optional.

idGeneratorSettings.json file

Purpose

Internal application settings, please do not modify or delete.

Final considerations

Warning: All configured libraries/lists in Microsoft SharePoint must be created and assigned with proper permissions at the time of their use.

The application creates fields not found in the lists' definition. Their type is given by their value. Warning: providing misspelled field names may result in creating unwanted fields, so be very careful when specifying field names.

Warning: do not rename or delete the configuration files, as the results are unpredictable!

Note: make sure that the user starting the application has read-write access to the Config sub directory.

Administrative issues: it is a good practice to make backups of the configuration folder, especially when installing application updates.

Clone this wiki locally