An example of a form with all field types: [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/BlXimage.png)
| **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. | [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/KxIimage.png) |
| ##### BOOLEAN | This is a yes/no tickbox. **Configuration options:** - Default value: to have the tickbox by default enabled or disabled. | [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/hOXimage.png) |
| ##### 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. | [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/4TIimage.png) |
| ##### 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. | [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/jMFimage.png) |
| ##### 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. | [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/prOimage.png) |
| ##### 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. | [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/Aw0image.png) |
| ##### 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. | [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/2HGimage.png) |
| ##### 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 | [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/k7Vimage.png) |
| ##### 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. | [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/Hu5image.png) |
| ##### GPS | With a GPS field, the exact position can be saved in Degrees, Minutes and Seconds. **Configuration options:** - none | [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/WCeimage.png) |
| ##### 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. | [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/9H6image.png) |
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): [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/1.JPG) 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) [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/install-1.png) 6. The update is ready and installed successfully the message shows: Completed the MXSuite Setup Wizard [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/install-2.png) # 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 [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/properties-documents-module.png)** - For the crewing module: **Administration** > **Crewing >** **Contract Templates** > **Contract Custom Properties** or **Administration** > **Crewing >** **Contract Templates** > **Conformation of employment Custom Properties [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/properties-crewing-module-contract.png)** ##### 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. [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/advanced-properties-word.png)** 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. [](https://docs.mxsuite.nl/uploads/images/gallery/2024-11/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. # 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** [](https://docs.mxsuite.nl/uploads/images/gallery/2025-01/image.png) 3. Create a new user for the API with the correct user rights. Assure that you select user type API. [](https://docs.mxsuite.nl/uploads/images/gallery/2025-01/1BZimage.png) ##### Create the API key 1. Open the **Administration** module 2. Click on **API keys** [](https://docs.mxsuite.nl/uploads/images/gallery/2025-01/5cHimage.png) 3. Click on **New...** [](https://docs.mxsuite.nl/uploads/images/gallery/2025-01/qzTimage.png) 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. ```bash 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/](http://localhost:4200/) - Location mane: vessel2 - API key: 4a74ad039ffc4f3288da7a0e03e608da ##### Postman Postman can be downloaded here: [https://www.postman.com/downloads/](https://www.postman.com/downloads/) Open Postman, click on Import button and paste the following command: ```bash 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: [](https://docs.mxsuite.nl/uploads/images/gallery/2025-01/cejimage.png) In the Body tab, the payload value can be changed. [](https://docs.mxsuite.nl/uploads/images/gallery/2025-01/CR6image.png) ##### Console Define a payload variable: ```json 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 ```json { name: string, locationName: string, value: number, timeStamp: Date } ``` ```json [ { "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 TasksDo 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.| **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 |
| **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 |
| **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 |
| **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 |
| 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 |
| 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 to which the maintenance task is connected. |
| TaskName | 128 | X | The name of the maintenance task |
| RankName | X | The name of the rank that must be linked to the task |
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.| 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 to which the maintenance task is connected. |
| TaskName | 128 | X | The name of the maintenance task |
| RankName | X | The name of the rank that must approve the task signoff |
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.| 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 to which the maintenance task is connected. |
| TaskName | 128 | X | The name of the maintenance task |
| Owncode | 50 | X | The unique number of the part that will be linked to the task |
| Quantity | X | The quantity of the part that will be used during the task sign-off | |
| CostCode | 50 | Lookup to the Cost Codes as defined in the tab Administration. This should exactly match the name of the cost code. |
Administrative rights of this folder must be present for the current user