Related to MXSuite

• Field types of custom attributes
• Update MXSuite V3 to a newer version
• Custom Properties and Word merge
• API interface
• Manage API keys
• General API usage
• Update counters via API
• API for Assets Tasks
• Why don't I have enough space on the disk while we are processing document packages?
• MXSuite Excel Import – Export
• General info
• AssetsCategories
• AssetsCategoriesProperties
• Counters
• AssetsTasksGroups
• AssetsTasks
• AssetsTasksRanks
• AssetsTasksApproversRanks
• AssetsTasksParts
• C-drive full during synchronisation
• The specified network password is not correct.
• Unable to upload big files

Field types of custom attributes

At several places in MXSuite custom attributes are used to populate data. Each field type has its own behavior. Below is the overview with all field types and explanations.

An example of a form with all field types:

Type	Description	Image
AUTO NUMBER	This is an automatically generated sequential number. It can be used for example to have a unique numbering for created documents.   Configuration options: Prefix: Here a prefix for the number can be set. For example to distinguish documents created by the office from the ones created by the vessels.: ABC-1 ABC-2 OFF-3 OFF-4 Start number: the first number the sequential number should start with.
BOOLEAN	This is a yes/no tickbox.   Configuration options: Default value: to have the tickbox by default enabled or disabled.
DATE TIME	This is a field where the date can be filled or chosen from a calendar. Also can be defined if the field should contain only the date or the time as well.   Configuration options: Is date only: when selected only the date can be filled. If not selected also the time can be given. Default value: a default date (and time) can be given.
DOUBLE and INTEGER	This is a numeric field. The difference between a double and an integer: A double is a numeric value with decimals, like 123,45 An integer is a numeric value without decimals, like 123 Configuration options: Minimum value: fill here the minimum allowed value. Maximum value: fill here the maximum allowed value. Default value: a default value can be given here.
LOOKUP  and  SYSTEM LOOKUP	A lookup is a list with predefined selections. The difference between a lookup and a system lookup: A lookup is a list that can be defined by the user in Administration > Lookups. A system lookup is a predefined list with values or a list that is managed anywhere else in MXSuite. For example the list with users or the list with countries. Configuration options: Lookup type as configured in Administration > Lookups or one of the system lookups. Default value: a default selection can be made here.
TEXT	A text field is a field where a free text can be entered.   Configuration options: Multiline: if enabled the text field will be shown with 3 lines. If disabled, the field has a height of one line. Maximum length: the maximum number of characters that can be filled in the text field. Default value: a default text can be given here.
LOGBOOK	A logbook is an extended version of a text field. Every new entry will be saved with username and date and time.   Configuration options: Multiline: if enabled the text field will be shown with 3 lines. If disabled, the field has a height of one line. Users can edit their own logs: allow the user to change the text he typed afterwards. Use edit rights: editing the logbook depends on the user rights of the current user. Default value: a default text can be given here.
IMAGE and FILE	An image or a file can be used to save an attachment to MXSuite.  For an image only known extensions are allowed: .bmp .jpg .gif .png .svg .tiff .dds .wdp .emf .ico .wmf For a file all extensions can be saved.   Configuration options: Maximum file size: fill here the maximum attachment size in bytes. 1 MB = 1.048.576 bytes 5 MB = 5.242.880 bytes 10 MB = 10.485.760 bytes 50 MB  = 52.428.800 bytes
READ ONLY	Read-only information is used to show a text in the form or page, which is helpful for the user. Configuration options: Show name: if enabled, the name (first field in the picture) is also shown on the form or page. Default value: type here the text that should be shown on the form or page.
GPS	With a GPS field, the exact position can be saved in Degrees, Minutes and Seconds.     Configuration options: none
AVERAGE	In the field Average, you can add a numeric value including decimals. For each average attribute, you can decide how much the score will adjust the overall score. The total value of all average fields should be in total 100.   Configuration options: Minimum value: fill here the minimum allowed value. Maximum value: fill here the maximum allowed value. Default value: a default value can be given here. Average: the weight of this field. The total value of all average fields in the form or page should be 100.

Update MXSuite V3 to a newer version

To update MXSuite V3 to the latest version available please follow the below steps.

There is no need to create a backup of the database as the update does not affect the data in the database and cannot cause any loss.

1. Check if there is a new version available for the update.
   
   • Go to Summary -> About -> Check for Updates
   • A pop-up window appears with the information (either that you are already on the latest version or about the latest version available):
     
     
     
2. Download the latest version
   • Press OK to proceed with the download of the latest version (screenshot above).
     
3. Wait until the download is finished. 
4. Open the downloaded file, and right click on the installation file -> Run as administrator
   

   The installation file should be run as administrator to be able to update all files.
   

5. Follow the steps from the installation wizard (click on Next button)
   
   
   
6. The update is ready and installed successfully the message shows: Completed the MXSuite Setup Wizard
   
   

Custom Properties and Word merge

In MXSuite

The fields that are available to merge to a Microsoft Word document, are defined in MXSuite. You can find these fields in:

• For the document module:
  Administration > Documents > Custom Properties
  
  
  
• For the crewing module:
  Administration > Crewing > Contract Templates > Contract Custom Properties 
  or
  Administration > Crewing > Contract Templates > Conformation of employment Custom Properties 
  
  

In Microsoft Word

Open the document in Microsoft Word and do the following.

1. Select File
2. Select Info
3. Click on the arrow right of Properties
4. Select Advanced Properties.
   
   

When the popup opens, select the Custom tab.

Add new text values with the same descriptions as defined in MS Word Mail merge Exchange. These fields are case sensitive so it needs to be used “Vessel Name” and not “vessel name”.

In the content of the document

1. Select the tab Insert
2. Select Quick Parts
3. Select Fields
4. Choose the category: Document information
5. Select field name: DocProperty

In the right window, you get your properties.

At Vessel Name insert, automatically in MXSuite the name of the vessel is inserted in the document.

API interface

Manage API keys

The HTTP(S) API has been available since MXSuite version 3.3.0.

To create an API key, there are 2 steps needed:

1. Create the API-user
2. Create the API-key

Create an API user

1. Open the Administration module 
2. Click on Users
   

   
   

   
   
3. Create a new user for the API with the correct user rights. Assure that you select user type API.
   

   

   
   

Create the API key

1. Open the Administration module
2. Click on API keys
   

   
   

   
   
3. Click on New...
   

   
   
   

4. Enter the Name of the API so you can easily distinguish all API keys.
5. Select the related API user
6. If needed, enter an expiry date.
7. Click on Save & close
8. Now the API key is created and visible.

General API usage

Authentication

To access the API, first an API key needs to be created from the Administration page. The key will be used as a header in the HTTP request.

MXSuite expects a mx-apikey header on each request.

mx-apikey: apikey

Besides the mx-apikey header, two more headers are required.

accept: application/json, text/plain, */*
content-type: application/json

Error handling

Successful responses will return a 200 or 204 HTTP response code. Errors will return a 4xx or a 5xx.

Some scenarios of errors:

• missing the mx-apikey header
• wrong api key
• expired api key
• MXSuite license expired
• The user doesn't have enough rights for that specific request

Examples

Below an example of how to use the API key in MXSuite. In this example the following parameters are used:

• URL for MXSuite: http://localhost:4200/
• Location mane: vessel2
• API key: 4a74ad039ffc4f3288da7a0e03e608da

Postman

Postman can be downloaded here: https://www.postman.com/downloads/
Open Postman, click on Import button and paste the following command:

curl 'http://localhost:4200/api/ExternalCounters/UploadCountersHistory' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'mx-apikey: 4a74ad039ffc4f3288da7a0e03e608da' \
  --data-raw '[{"name":"c1","locationName":"vessel2","value":1119,"timestamp":"2024-10-05T12:11:11.000Z"},{"name":"C2","locationName":"Vessel2","value":2229,"timestamp":"2024-10-05T12:11:11.000Z"},{"name":"c3","locationName":"Vessel2","value":3339,"timestamp":"2024-10-05T12:11:11.000Z"}]'

In the Headers tab the API key can be changed:

In the Body tab, the payload value can be changed.

Console

Define a payload variable:

let payload = [
    {
        "name": "c1",
	"locationName": "vessel2",
        "value": 1119,
        "timestamp": new Date(2024,09,05,15,11,11)
    },
    {
        "name": "C2",
	"locationName": "Vessel2",
        "value": 2229,
        "timestamp": new Date(2024,09,05,15,11,11)
    },
    {
        "name": "c3",
	"locationName": "Vessel2",
        "value": 3339,
        "timestamp": new Date(2024,09,05,15,11,11)
    }
];

Request:

fetch("http://localhost:4200/api/ExternalCounters/UploadCountersHistory", {
  "headers": {
    "accept": "application/json",
    "content-type": "application/json",
    "mx-apikey": "4a74ad039ffc4f3288da7a0e03e608da",
  },
  "body": JSON.stringify(payload),
  "method": "POST"
}).then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Don't forget to change the mx-apikey header value

Update counters via API

Overview

The Counters API provides endpoints for managing running hours (counters) within the MXSuite system. This API allows you to upload counter history records for one or more counters at a location, with proper authorization controls.

Base URL

• api/external/Counters/
  

1. Upload Counters History

Overview

The Upload Counters History endpoint allows authorized users to upload a batch of running hours (counter) history records for one or more counters at a specific location. This is typically used to record the latest readings for equipment counters.

Endpoint

POST /api/external/Counters/UploadCountersHistory

Authentication

All endpoints require authentication and appropriate user rights.
This endpoint requires the UpdateRunningHours right and the location must not be read-only.
Authorization is enforced via the MXApiPolicyAuthorize attribute.

Request

{
  name: string,
  locationName: string,
  value: number,
  timeStamp: Date
}

[
  {
    "Name": "Main Engine",
    "LocationName": "Neptune",
    "Value": 12345,
    "TimeStamp": "2025-06-23T14:00:00Z"
  },
  {
    "Name": "Generator 1",
    "LocationName": "Neptune",
    "Value": 6789,
    "TimeStamp": "2025-06-23T14:00:00Z"
  }
]

Error Responses

•    400 Bad Request: Invalid input data (e.g., missing required fields, invalid values).
•    401 Unauthorized: User is not authenticated.
•    403 Forbidden: User does not have the required rights or location is read-only.
•    500 Internal Server Error: An unexpected error occurred.

If there is no location with that name, the entry is ignored.
If there is no counter with that name for that location, the entry is ignored.
If there is already an entry added for that counter in that location with the same value and timestamp, the entry is ignored.

API for Assets Tasks

[
  {
    "id": "b1a2c3d4-e5f6-7890-abcd-1234567890ab",
    "uniqueId": "CAT-001",
    "name": "Engine Room",
    "parentId": "c2b3a4d5-e6f7-8901-bcda-2345678901bc",
    "displayIndex": 1
  }
]

[
  {
    "id": "d3e4f5a6-b7c8-9012-cdab-3456789012cd",
    "type": 1,
    "uniqueId": "GRP-001",
    "name": "Auxiliary Systems",
    "displayIndex":1
  }
]

{
  "GroupId":"3C160DF1-3A5C-406F-BAC6-00A4AB8C44A9",
  "GroupType":1,
  "UniqueId": "Task-001",
  "TaskName": "Oil Change - Updated",
  "Interval": 45,
  "IntervalType": 1,
  "DueDate": "2025-06-01T00:00:00Z",
  "IsCounterBased": false,
  "IsRemarkMandatory": true,
  "IsProject": false,
  "IsRecurrent": true,
  "IsFixedInterval": true,
  "IsAtServiceRequest": false,
  "IsDefect": false,
  "TaskDescription": "Updated description for oil change.",
  "MaxInterval": 90,
  "MaxIntervalType": 2,
  "DueCounters": 150,
  "Downtime": 3.0,
  "WarningInterval": 10,
  "WarningIntervalType": 1,
  "CounterName": "Main Engine",
  "DefaultEstimatedBudget": {
    "Amount": 600.0,
    "Currency": "USD" 
  },
  "Ranks": ["Rank1", "Rank2"],
  "ApproverRanks": ["Approver1"],
  "RequiresApproval": true
}

{
  "TaskId": "1463aea5-9062-45bf-8b9c-24cc5615d467"
}

{
  "UniqueId": "Task-001",
  "TaskName": "Oil Change - Updated",
  "TaskId": "1463aea5-9062-45bf-8b9c-24cc5615d467",
  "GroupId":"3C160DF1-3A5C-406F-BAC6-00A4AB8C44A9",
  "GroupType":1,
  "Interval": 45,
  "IntervalType": 1,
  "DueDate": "2025-06-01T00:00:00Z",
  "IsCounterBased": false,
  "IsRemarkMandatory": true,
  "IsProject": false,
  "IsRecurrent": true,
  "IsFixedInterval": true,
  "IsAtServiceRequest": false,
  "IsDefect": false,
  "TaskDescription": "Updated description for oil change.",
  "MaxInterval": 90,
  "MaxIntervalType": 2,
  "DueCounters": 150,
  "Downtime": 3.0,
  "WarningInterval": 10,
  "WarningIntervalType": 1,
  "CounterName": "Main Engine",
  "DefaultEstimatedBudget": {
    "Amount": 600.0,
    "Currency":  "EURO"
  },
  "Ranks": ["Rank1", "Rank2"],
  "ApproverRanks": ["Approver1"],
  "RequiresApproval": true
}

[
    "1463aea5-9062-45bf-8b9c-24cc5615d467",
    "7b95cb8b-0cb8-4cdf-ad3e-3285a162cbea"
]

{
  "GroupId": "d3e4f5a6-b7c8-9012-cdab-3456789012cd",
  "GroupType": 1
}

[
  "e4f5a6b7-c8d9-0123-dabc-4567890123de",
  "f5a6b7c8-d9e0-1234-abcd-5678901234ef"
]

{
  "TaskId": "7b95cb8b-0cb8-4cdf-ad3e-3285a162cbea",
  "NumberOfSignOffs": 5
}

{
  "Errors": [
    {
      "message": "string",
      "errorCode": number,
      "isBusinessException": false,
      "businessExceptionData": null,
      "failureServerReason": null
    }
  ]
}

{
    "errors": [
        {
            "message": "Category name is required",
            "errorCode": 9,
            "isBusinessException": false,
            "businessExceptionData": null,
            "failureServerReason": null
        }
    ]
}

Why don't I have enough space on the disk while we are processing document packages?

Processing the document package creates a very big temp file on the disk. The temporary file is located in C:\temp.

The steps to solve this issue are the following in Windows settings:

1. Open Component Services from Windows Start
2. Click on Distributed Transaction Coordinator 
3. Right click on Local DTC
4. Click on Properties (a new window will open)
   
    
5. Click on tab Security
6. Enable Client and Administration / Transaction Manager Communication
   
    
7. Open SQL Server Configuration Manager from Windows Start
8. Click on SQL Server Services
9. Right click on SQL Server (MXSuite) 
10. Click on Properties (a new window will open)
11. Go to the tab Filestream
12. Enable Filestream for transact SQL access
    If sharename MXSuite already exists, use the filestream share name MXSuite2
    
    
     
13. Open Services from Windows Start
14. Restart Distributed Transaction Coordinator

The steps to solve the issue are the following in MXSuite:

1. Go to (C:\Program Files\Mastex\Synchronization Service) MXSuiteSync.exe.config
2. Right click Open
3. Edit connectionStrings (The bold letters must be changed)
   New: <add name="BaseConnectionString" connectionString="Data Source=(LOCAL)\mxsuite;Initial Catalog=MXSuite;Integrated Security=SSPI;MultipleActiveResultSets=True;Connect Timeout=60"/>
   Old: <add name="BaseConnectionString" connectionString="Data Source=VLMAPP01\mxsuite;Initial Catalog=MXSuite;UserID=MXSuiteApp;Password=MXSuiteApp@1234;MultipleActiveResultSets=True;Connect Timeout=60"/>
4. Restart the database
5. Check the logfiles of the synchronization service to check if there are no errors

MXSuite Excel Import – Export

General info

Import field relations with general data

If you filled in the following columns in the Excel file: 

• Budgetcodes 
• Currencies
• Product categories
• Units
• Ranks

Then this data must exist in the Administration module

All fields in the Excel file must be in text format.
For example, if there is a problem after importing inventory with the PartNumber (column C) change the format of this column (Right mouse click on this column, select Format Cells) to category General 

Do not change the top row of the Excel file! If this is changed, the import will fail

AssetsCategories

General

The categories will be used to link all maintenance tasks and spare parts to a category. The sheet in the Excel file is called “AssetsCategories”

Details fields

To fill the Excel file correctly, make sure that all fields are filled correctly. Below are the fields listed.

Example

AssetsCategoriesProperties

This part is used to load all Category Attributes in MXSuite. The sheet in the Excel file is called “AssetsCategoriesProperties”.

Details fields

To fill the Excel file correctly, make sure that all fields are filled correctly. Below are the fields listed.

Example

Counters

General

This part is used to load all counters in MXSuite. The sheet in the Excel file is called “Counters”.

Details fields

To fill the Excel file correctly, make sure that all fields are filled correctly. Below are the fields listed.

Example

AssetsTasksGroups

General

All maintenance tasks are linked to a maintenance job plan. The job plan is linked to a category. So the maintenance job plans are between the categories and maintenance tasks.

The sheet in the Excel file is called “AssetsTasksGroups”.

Details fields

To fill the Excel file correctly, make sure that all fields are filled correctly. Below are the fields listed.

Example

AssetsTasks

General

This part is used to load all tasks in MXSuite. The sheet in the Excel file is called “AssetsTasks”.

Details fields

To fill the Excel file correctly, make sure that all fields are filled correctly. Below are the fields listed.

AssetsTasksRanks

General

This part is used to link ranks to a task. The sheet in the Excel file is called “AssetsTasksRanks”.

Details fields

To fill the Excel file correctly, ensure that all fields are completed accurately. Below are the fields listed.

If more ranks must be linked to one task, add per rank a new line to be linked to the task.

AssetsTasksApproversRanks

General

This part is used to link the ranks that must approve the task signoff. The sheet in the Excel file is called “AssetsTasksApproversRanks”.

Details fields

To fill the Excel file correctly, ensure that all fields are completed accurately. Below are the fields listed.

If more ranks can approve the task signoff, add a new line per rank to be linked to the task.

AssetsTasksParts

General

This part is used to link the parts that are used during the task sign-off. The sheet in the Excel file is called “AssetsTasksParts”.

Details fields

To fill the Excel file correctly, ensure that all fields are completed accurately. Below are the fields listed.

C-drive full during synchronisation

During the creation of a big synchronisation package, it could happen that a lot of files are created in the folder C:/Windows/SystemTemp. If there is not enough space on the disk, the sync package cannot be created. Therefore, it could be useful to move that folder to another location.

Here is how to do that.

1. Log in using a Windows administrator account on the server.
2. Create a folder named "SystemTemp" on a drive with sufficient space.
3. Search for "This PC".
4. Right-click Properties.
5. Select "Advanced Settings".
6. Click on "Environment Variables". 
7. Click on "New" under system variables.
8. Enter "SYSTEMTEMP" for the variable name and the location of the folder you created earlier.
   
   
9. Click OK, and then reboot the server.
10. Restart the client computer and attempt to create the sync package again. 

The specified network password is not correct.

When login to MXSuite the following error message appear : [System.Security.Cryptography.CryptographicException]  The specified network password is not correct.

Solution

• Go to folder C:\ProgramData\Microsoft\Crypto\RSA\
• Right mouse click on the folder MachineKeys and choose Properties
• Go to the tab Security and click Edit
• Check if IIS_IUSRS has Full control permission

In case you don't see the user IIS_IUSRS, please follow the steps below: 

• Click Add and search for user: IIS_IUSRS and click on OK
• Give the user IIS_IUSRS Full control rights on the folder MachineKeys
  
  
• Click OK and OK

Unable to upload big files

It can happen that MXSuite fails when uploading a file larger than 30 MB.
When you expect that MXSuite will upload the file, the upload will never happen. 

This can be related to a missing setting in the file: applicationHost.config.
You can find this file in C:\Windows\System32\inetsrv\config

The following line must be added:

<requestLimits maxAllowedContentLength="262144000" />

This line must be added between 

 <security> 
 <requestFiltering>
[Other commands]

 </requestFiltering> 
 </Security>

Example below:

                    <add fileExtension=".refresh" allowed="false" />
                    <add fileExtension=".compiled" allowed="false" />
                    <add fileExtension=".msgx" allowed="false" />
                    <add fileExtension=".vsdisco" allowed="false" />
                    <add fileExtension=".rules" allowed="false" />
                </fileExtensions>
                <verbs allowUnlisted="true" applyToWebDAV="true" />
                <hiddenSegments applyToWebDAV="true">
                    <add segment="web.config" />
                    <add segment="bin" />
                    <add segment="App_code" />
                    <add segment="App_GlobalResources" />
                    <add segment="App_LocalResources" />
                    <add segment="App_WebReferences" />
                    <add segment="App_Data" />
                    <add segment="App_Browsers" />
                </hiddenSegments>
            </requestFiltering>
            <requestLimits maxAllowedContentLength="262144000" />
        </security>

After the file is saved, a restart of the IIS Server is required.

Administrative rights of this folder must be present for the current user