How to get site/equipment default contact/address details on order ?
Which fields are required as a minimum to create an order in Handyman with API?
Technical minimum example for an Orders endpoint call
How to get all open/active order# for a specific customer?
Which attachment formats are possible and how can we upload these (TIFF, JPG, PNG..)?
How do we get the orders that we need, with one or more Status (ex. 1 and 2)?
Which filters are working for the APIs we plan to use?
How to get site/equipment default contact/address details on order?
There is no default contact for a site, you can collect the attached contacts of an order site with the following endpoint: api/installations/{site-id}/contacts. The site-id can be collected through the following endpoint: api/orders/{order-id}/installations?installationType=1 --> Id property of the returned object(s).
Is there any way to update "OrderHead's CustomerReference” or “OrderHead's Requsition” field via API call for an open order?
Both field update should work on api/orders endpoint (POST)
This is true for api/weboffice/orders (POST) endpoint as well, but since that endpoint uses a different POST model (OrderCreateModel), the corresponding fields are: CustomerReferenceText and Requisition
Which fields are required as a minimum to create an order in Handyman with API?
The technical minimum example for an Orders endpoint call:
Samlple JSON:
[
{
"CustomerReference":
{
"ExternalId": "910478658"
},
"OrderHead":
{
"EstimatedHours": 32,
"OrderDate": "2023-03-13T12:46:42.329Z",
"OrderName": " Testing "
}
}
]
The Json above is a technical minimum for the Api call, meaning that the API will not respond with an Error. From Business point of view, this data is not a meaningful Order.
Business minimum call example:
[
{
"OrderHead": {
"OrderDate": "{{$isoTimestamp}}",
"OrderName": "Bence Testing CW Export 17",
"EstimatedHours": 32,
"Requsition": "External Reference of the order.",
"IsInternalOrder": false,
"DoNotSetAsPassive": false,
"CustomerReference": "Customer Reference for the order.",
"Message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
"ContactName": "Mr. Contact",
"Telephone1": "+36419871234",
"Telephone2": "+3612045406",
"ContactEmail": "mr.contact@email.com",
"FixedPrice": 12345,
"ManagerReference": {
"ExternalId": "10"
},
"DepartmentReference": {
"ExternalId": "400"
},
"StartDate": "{{Order_start_date}}",
"FinishDate": "{{Order_end_date}}",
"ActualStartDate": "{{Actual_start_date}}",
"ActualFinishDate": "{{Actual_end_date}}",
"CategoryList": [
{
"CategoryBackOfficeId": "12",
"CategoryType": 1
},
{
"CategoryBackOfficeId": "2",
"CategoryType": 0
}
],
"Location": {
"Latitude": 47.563660,
"Longitude": 19.093232,
"AddressName": "HQ",
"BoligmappaEdokNumber": "Lebstück",
"BoligmappaPlantID": 1534,
"Address1": "Lebstück Mária",
"StreetNo": "63",
"Address2": "utca",
"PostalCode": "1041",
"PostalArea": "Budapest",
"Country": "Hu"
},
"KB_ValueList": [
{
"Level": 0,
"Value": "12345678910111",
"Description": "Test med lang id",
"Parent": null,
"FixedPrice": null
},
{
"Level": 0,
"Value": "Kan det være tekst",
"Description": "Test med enda lengre id",
"Parent": null,
"FixedPrice": null
},
{
"Level": 1,
"Value": "1",
"Description": "COntract",
"Parent": null,
"FixedPrice": null
},
{
"Level": 1,
"Value": "2",
"Description": "Additional work",
"Parent": null,
"FixedPrice": null
},
{
"Level": 2,
"Value": "1",
"Description": "Indoor work",
"Parent": null,
"FixedPrice": null
},
{
"Level": 2,
"Value": "2",
"Description": "Outdoor work",
"Parent": null,
"FixedPrice": 5000.0
}
]
},
"Status": 12,
"CustomerReference": {
"ExternalId": "31"
},
"ParticipantList": [
{
"EmployeeReference": {
"ExternalId": "10"
},
"MainParticipant": true
}
]
}
]
The sample Json creates an Order which is valid for some businesss cases.
How to get all open/active order# for a specific customer?
- only the active orders:
["Status", "<>", 14]
- s the "Passive" state in HMO, every order with other value is considered as "Active"
Which attachment formats are possible and how can we upload these (TIFF, JPG, PNG..)?
You can add any type of attachment using document-adding endpoints. For example, in case of orders you can use the api/orders/{order-id}/documents POST endpoint and pass the data like this (you should specify the extension in the “FilePath” property and in the “FileExtension”. The image should be passed as a byte array):
[
{
"HSDocumentID": "99",
"DocumentID": "178",
"Date": "2022-10-12T17:04:43.133",
"ChecklistRegistrationReference": null,
"EmployeeReference": {
"Id": 4,
"ExternalId": "2"
},
"Name": "test",
"Comment": "",
"SendToClient": false,
"FilePath": "test.jpg",
"DocumentData": "000000000000000000000000000000000011000000000000000000000000000000011000000100000100000000000000000000000000000000000000000000000000111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111",
"FileExtension": "jpg",
"KB1": "String",
"KB2": "",
"Phase": "",
"AssetID": null,
"AssetPropertyID": null,
"BoligmappaID": null,
"BoligmappaUploadDate": null,
"SyncStatus": 0,
"SiteReference": null,
"EquipmentReference": null,
"DocumentType": 0,
"ResetSyncStatus": null,
"HSId": 99,
"BackOfficeId": "178",
"IsAvailableOnWeb": null
}
]
How do we get the orders that we need, with one or more Status (ex. 1 and 2)?
- Can we use: GET /api/orders
- Can we do one call to get this or do we need to do multiple calls?
It depends on what kind of status we look for. If it’s about the Status of the order eg. new order, changed on mobile, etc. Then there’s no such filter, but there is a possibility to filter on Active and Completed orders. With Status query parameter, using the following values:
All = 0,
Active = 1,
Completed = 2
What is the difference between these:
- Handyman, Swagger (Netel): https://api.netelgroup.com/swagger/ui/index#/
- Handyman, Swagger (New): https://api.gsgroup.io/swagger/index.html
This is the swagger for the Common Api. Legacy version for the Handyman Api. It was designed to access multiple GSG Handyman products with one Api. Have less functionality than Handyman Api. For Handyman customers we do not recommend using it!
Which filters are working for the APIs we plan to use?
It always depends on the endpoint itself. Some of the GET (list) endpoints have an ExternalId query parameter which can be used to filter items (eg. Orders) on their ERP (IdBackoffice) identifier.
Paging is also supported for various endpoints with pageSize and startIndex query parameters
Note: QA swagger has a wider parameter list for some reason
The Filter is a query parameter, it has an array content, can contains filter clauses and logical relations.
Every filter clause must be an array itself with the following structure:
["field","operator","value"]
Filters for the necessary operations:
- only the active orders:
["Status", "<>", 14]
- s the "Passive" state in HMO, every order with other value is considered as "Active"
- changed in a timeframe
["LastChanged", ">", "2023-04-13 00:00:00"]
The date value could be yesterday
- has a specific category
[["OrderCategory", "contains", "This is an order category"], "or", ["OrderCategory", "contains", "Another order category"]]
or operators could be used for different possible values
The full Filter query string is the following:
Filter=[["Status", "<>", 14], "and", ["LastChanged", ">", "2023-04-13 00:00:00"], "and", [["OrderCategory", "contains", "This is an order category"], "or", ["OrderCategory", "contains", "Another order category"]]]
To reduce the "noise" in the response json, there is an option to project the result with Select query parameter.
We can have a json with OrderId, OrderCategory (for back check) and Secondary customer with query parameter value:
["OrderId", "SecondaryCustomer", "OrderCategory"]
A full query string for this approach looks like this:
api/weboffice/orders?Filter=[["Status","<>",14], "and", ["LastChanged", ">", "2023-04-13 00:00:00"], "and", [["OrderCategory", "contains", "This is an order category"], "or", ["OrderCategory", "contains", "Another order category"]]]&Select=["OrderId", "SecondaryCustomer", "OrderCategory"]
Which operation should we use to post FinancialTransactionId, POST /api/orders/{orderId}/materials?
It depends on what is FinancialTransactionId for.
Which operation can we use to post in the log file in Handyman: POST /api/orders/{orderId}/descriptions
The description endpoint is not equal with the logs for the order. The latter is called messagelog and the endpoint is available on the same name.
for HandymanAPI Connect: 52.18.254.245
Port: 19000/TCP