Related to MXSuite

FAQ 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

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

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.

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):
Download the latest version
- Press OK to proceed with the download of the latest version (screenshot above).
Wait until the download is finished.
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.
Follow the steps from the installation wizard (click on Next button)
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.

Select File
Select Info
Click on the arrow right of Properties
Select Advanced Properties.

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

Select the tab Insert
Select Quick Parts
Select Fields
Choose the category: Document information
Select field name: DocProperty

In the right window, you get your properties.
$insert_properties.png$

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

API interface

The application programming interface (API) is used to make a connection between MXSuite and other software.

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:

Create the API-user
Create the API-key

Create an API user

Open the Administration module
Click on Users
Create a new user for the API with the correct user rights. Assure that you select user type API.

Create the API key

Open the Administration module
Click on API keys
Click on New...
Enter the Name of the API so you can easily distinguish all API keys.
Select the related API user
If needed, enter an expiry date.
Click on Save & close
Now the API key is created and visible.

API interface

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

API interface

Update counters via API

ExternalCounters/UploadCountersHistory

Using this action a list of counter values can be updated.

This action requires the "Update counters" user right and a valid MXSuite license.

Body parameters

A list with this object type:

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

The entry is ignored if:
- there is no location with that name.
- there is no counter with that name for that location.
- there is already an entry added for that counter in that location with the same value and timestamp.

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:

Open Component Services from Windows Start
Click on Distributed Transaction Coordinator
Right click on Local DTC
Click on Properties (a new window will open)
Click on tab Security
Enable Client and Administration / Transaction Manager Communication
Open SQL Server Configuration Manager from Windows Start
Click on SQL Server Services
Right click on SQL Server (MXSuite)
Click on Properties (a new window will open)
Go to the tab Filestream
Enable Filestream for transact SQL access
If sharename MXSuite already exists, use the filestream share name MXSuite2
Open Services from Windows Start
Restart Distributed Transaction Coordinator

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

Go to (C:\Program Files\Mastex\Synchronization Service) MXSuiteSync.exe.config
Right click Open
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"/>
Restart the database
Check the logfiles of the synchronization service to check if there are no errors

MXSuite Excel Import – Export

In this chapter you can find technical details on preparing an import per module.

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

MXSuite Excel Import – Export

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.

Field	MAX Characters	Required	Comment
ID	128		Id number of the category
ParentCategories			If this category is a child of another category, enter the ID number of the parent category, followed by a space, followed by the name of the parent category
Name	128	X	Name of the category
IsCritical	5		True or False
IsOperationalCritical	5		True or False
Priority	18.2		Number with 2 decimals, separated by a comma
Comments	1024		Comment for the category
Defaultcounter	128		Preferred counter for counter-based maintenance tasks. The name of the counter should be mentioned

Example

MXSuite Excel Import – Export

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.

Field	MAX Characters	Required	Comment
ParentCategories		X	Show the category path of the category that this entity needs to be connected to. If this is linked to a subcategory, enter the ID + name of the main category, followed by a space, > , and a space, followed by the ID + name of the subcategory
Name		X	The Name of the attribute
Value			The Value of the attribute
Type		X	The Type of the attribute, the default value is None
ShowOnServiceOrders			If this information must be printed on the Service order, set the value to True; otherwise, set it to False
ShowOnProductOrders			If this information must be printed on the Product order, set the value to True; otherwise, set it to False

Example

MXSuite Excel Import – Export

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.

Field	MAX Characters	Required	Comment
Name	128	X	Name of the Counter
Unit	128	X	The unit name should exactly match the name of the Unit as known in Administration -> Units
AveragePerWeek		X	The maximum average per week for the selected unit. For unit Running hours, the average must be set to 168
ActualCounterValue		X	The actual counter value for the imported counter machine
ParentCounter			If the counter will use the input from another counter, specify here the countername

Example

MXSuite Excel Import – Export

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.

Field	MAX Characters	Required	Comment
ParentCategories		X	Show the category path of the category that this entity needs to be connected to. If this is linked to a subcategory, enter the ID + name of the main category, followed by a space, > , and a space, followed by the ID + name of the subcategory
Name	128	X	Name of the group
ID	128		ID number of the group
CostCode			The Costcode name should exactly match the name of the Budgetcode as known in Administration -> Budgetcodes

Example

MXSuite Excel Import – Export

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.

Field	MAX Characters	Required	Comment
ParentCategories		X	Show the category path of the category that this entity needs to be connected to. If this is linked to a subcategory, enter the ID + name of the main category, followed by a space, > , and a space, followed by the ID + name of the subcategory
AssetsTasksGroupName	128	X	Name of the group which the maintenance task is connected.
TaskType	9	X	Type of the interval of the maintenance task. 2 options are possible: - Recurring: This is used if the task needs to be done according to a given interval - OneTime: This is used if the task needs to be done one time. There is no interval connected
ID	128		ID number of the maintenance task
TaskName	128	X	The name of the maintenance task
UseTaskOnce	5		If the TaskType is set to Onetime, this setting must be set to True Otherwise, this setting must be set to False
IsDefect	5		Only if the Tasktype is set to Onetime, and the UseTaskOnce is set to True, can this setting be set to True if the task is a defect. Usually, this setting is False.
IsCounterBased	5		If the maintenance task is based on running hours, this must be set to True; otherwise, fill in the option False. If the maintenance task is both based on running hours and time-based, set this to True. In column Duedate, fill in the proper date, and fill in column DueRunningHours, the due running hours value
IsRemarkMandatory			If a remark is mandatory during marking a maintenance task as done, set this to True If no remark is needed during marking a maintenance task as done, set this to False
CostCode	50		The Costcode name should exactly match the name of the Budgetcode as known in Administration -> Budgetcodes
IsFixedInterval	5		If the maintenance task has a fixed interval, set this option to True. Otherwise, fill in option False
IntervalValue			If the task has a time interval, fill in here the value of days/weeks/months If the task has a counter interval, fill in the value of the counters If the task is a one-time task, leave this field empty If the task is a docking task, leave this field empty
IntervalType	6	X*	* In case that the task is not a counter-based task or the field IsDocking = false, this field is mandatory Fill in here the type of interval. Possible values are: - Days - Weeks - Months
DueDate	19	X*	* In case that the task is not a counter-based task or the field IsDocking = false, this field is mandatory. The due date of the task. Written in the date-time format of the PC that imports the file. The default Dutch format is D-M-YYYY HH:MM:ss
MaximumIntervalValue			If the task is based on counters and time-based, fill here the number of days/weeks/months
MaximumIntervalType	6	X*	* In case a value is entered in MaximumIntervalValue, this field is mandatory. Fill in here the type of interval. Possible values are: - Days - Weeks - Months
RunningHoursMachine		X*	*In case the task is counter-based, this field is mandatory. Fill in the name of the related counter machine here.
DueRunningHours		X*	*In case the task is counter-based, this field is mandatory. Fill in here the value of the counter when the task becomes due. A numeric value is accepted without decimals.
IsProject	5		Is the task is related to a project, set the value to True, otherwise set to False
DownTime			The time needed to finish the task in hours. Only a numeric value without decimals is accepted.
WarningPeriod			Here, the warning period as a numeric field in combination with the field WarningType. For example, WarningPeriod 7 and WarningType 1 mean that the task becomes due 7 days before the due date; in this case, fill in number 7.
WarningType	1		Fill in here the type of interval. Possible values are: Value 1 for the interval in days Value 2 for the interval in weeks Value 3 for the interval in months
LongDescription			The long task description where the procedures can be described how to perform the task. With Alt-Enter in the Excel sheet, the text starts on a new line. Note: layout formatting is not possible via the import from Excel.
TaskCompletionNeedsApproval	5		If the task needs to be approved by another rank, set the value to True. If the task does not need to be approved by another rank, set the value to False. Note: The approver rank can be entered in Sheet: AssetsTasksApproversRanks
IsAttachmentMandatory	5		If an attachment is required when completing the task, set this value to True If an attachment is not required when completing the task, set this value to False
Priority			The possible priorities are: - Top priority - Urgent - High - Normal - Low - Not prioritized The priorities can be managed in Administration -> Lookups -> Task priority

Related to MXSuite

Field types of custom attributes

AUTO NUMBER

BOOLEAN

DATE TIME

DOUBLE

INTEGER

LOOKUP

SYSTEM LOOKUP

TEXT

LOGBOOK

IMAGE

FILE

READ ONLY

GPS

AVERAGE

Update MXSuite V3 to a newer version

Custom Properties and Word merge

In MXSuite

In Microsoft Word

In the content of the document

API interface

Manage API keys

Create an API user

Create the API key

General API usage

Authentication

Error handling

Examples

Postman

Console

Update counters via API

ExternalCounters/UploadCountersHistory

Body parameters

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

MXSuite Excel Import – Export

General info

Import field relations with general data

AssetsCategories

General

Details fields

Example

AssetsCategoriesProperties

Details fields

Example

Counters

General

Details fields

Example

AssetsTasksGroups

General

Details fields

Example

AssetsTasks

General

Details fields