The Web Service Methods¶
General information¶
The web service methods will populate pre-defined classes, which are then available to use just like other local classes. The use of these methods is mainly to retrieve information from Harmoney or store information in Harmoney. The methods are divided into logical groups - the so-called Services.
The response object¶
Every returning objects include a Response property. It is used for showing transaction status. When using the PCL public methods, it is vital to check the Response object after a call to determine the result of the transaction. The Response object contains information about whether the method was successful or not as well as possible error messages. All calls return a Response object, regardless if the call was successful or not.
There are currently three ways the Response object can be included:
- The web method returns only a Response object. This can be for instance when there only has to be a confirmation that the transaction finished successfully, e.g. DeleteOrder.
- The web method returns an object. The Response object is always included in the object’s properties so you can check the transaction status, e.g. ValidateOrder.
- The web method returns a list of objects, a ListWrapper object. Since the Response object is relevant to the whole transaction and not the individual items in the list it is included in the ListWrapper object, e.g. GetPickupLocations.
If the response status (Response.Success) is false, the call has failed or Harmoney is not responding. The Response object contains a list of error messages, Response.HarmoneyMessages, which describes the error and the severity of the problem. It is also helpful to look at the Response.ErrorLevel field to determine the severity of the message. Response.Success can be true and ErrorLevel still be Warning, as it indicates that something that you should be made aware of.
Please note: In some cases, it is also useful to check other statuses to determine if a call was successful. For example, the Order object and the Customer object has a property called ControlStatus. When saving an Order or Customer you should also check the ControlStatus property to see if the call was accepted as-is or if it needs to be checked by customer services before being accepted. See section Customer and/or section Order for more information
Layout of the Response object¶
| Parameter name | Type | Example value | Description |
|---|---|---|---|
| Success | boolean | true | Indicates if the call was successful or not. Success will be false if critical errors occur |
| Status | Enum | ||
| TransMessage | string | 0100000124 deleted | A description of the error/warning/information |
| TransStatus | string | 00 | Status code to indicate the type of error/warning/information. See Transaction status in the Response object |
| ErrorLevel | Enum | None | None - all is well Warning - information message Error - error that needs handling Critical - error, i.e. trouble reaching WsPCL or the system is closed |
| CallDuration | Long | 403 | How long the call took to complete. Used mainly for support issues. |
| IsCached | boolean | false | Indicates whether the answer from WsPCL is a cached response or not. Default is false. |
| Harmoney-Messages | Contains a list of all HarmoneyError objects, if any. |
Layout of the HarmoneyError object¶
| Parameter name | Type | Example value | Description |
|---|---|---|---|
| Name | string | GEN | Transaction name |
| Id | string | 000049 | Error id code |
| Language | string | EN | Language code |
| Type | string | 01 | Error type |
| Message | string | 0100000124 deleted | Error/warning/information message |
Two examples of response objects¶
Success = true¶
<?xml version="1.0"?>
<Response>
<Success>true</Success>
<TransMessage />
<TransStatus />
<ErrorLevel>None</ErrorLevel>
<CallDuration>32</CallDuration>
<IsCached>True</IsCached>
<HarmoneyMessages>
<HarmoneyError>
<Name>GEN</Name>
<Id>000049</Id>
<Language>EN</Language>
<Type>01</Type>
<Message>0100000124 deleted</Message>
</HarmoneyError>
</HarmoneyMessages>
</Response>
Success = false¶
<?xml version="1.0"?>
<Response>
<Success>false</Success>
<TransMessage>Street address missing</TransMessage>
<TransStatus>98</TransStatus>
<ErrorLevel>Error</ErrorLevel>
<CallDuration>32</CallDuration>
<IsCached>True</IsCached>
<HarmoneyMessages>
<HarmoneyError>
<Name>PXXO3501ORD</Name>
<Id>000015</Id>
<Language>EN</Language>
<Type>01</Type>
<Message>Street address missing</Message>
</HarmoneyError>
</HarmoneyMessages>
</Response>
Transaction status in the response object¶
All calls to WsPCL returns a Response object. Usually it is enough to look at the Response.Success attribute to determine if the transaction was successful. In some cases, it is also needed to check the transaction status and messages, especially when Response.Success returns false. Response.TransStatus returns a code that corresponds with the table below. When needed, Response.TransMessage returns a short message explaining the status. All status codes beginning with a zero can be considered to be successes
| Status | Explanation |
|---|---|
| 00 | Transaction was successful. If call was made to SaveOrder, and something interrupted the transaction, the transaction is saved on the Harmoney Control Page or as an order with a stopping code and applicable error message. |
| 01 | Transaction was successful. Transaction returned a clarifying message in Response.TransMessage. |
| 02 | Transaction was successful. There is an explanatory message in Response.TransMessage. In the Harmoney client this message will be shown as a popup message, which is more critical than status 01, but is still considered to be successful. |
| 90 | Transaction failed. Password has expired. |
| 91 | Transaction failed. Password is incorrect. |
| 96 | Transaction failed. A question about the transaction is raised and needs to be addressed, usually yes/no. E.g. if call should be applied to all Items when updating Product information. |
| 97 | Transaction failed. Harmoney is not available. You are requested to try again later. This is usually because of a scheduled stop in Harmoney, i.e. during a release or service window. |
| 98 | Transaction failed. Transaction was interrupted. Response.TransMessage contains an error message explaining the reason for the interruption. This is usually because of an error in the transaction inbound data. |
| 99 | Transaction failed. Transaction failed because of an unscheduled system error or system stop. Response.TransMessage contains an error message explaining the reason for the failure. You are requested to try again later. |
Offlline Handling¶
In most cases it is required of the web solution to have some form of offline handling, e.g. to be able to handle situations when Harmoney cannot be reached or some other reason that an order cannot be saved in Harmoney. To avoid orders being stuck between systems, and clarify responsibilities, it is important to implement some form of offline handling.
In communication between Harmoney and external system as for example a web solution there are four layers involved; the web solution itself, WsPCL (the outermost web service called by the web solution), WsTransExternal (the web service handling Harmoney’s own internal format) and Harmoney (the ERP/database itself).
Harmoney’s web services has their own offline handling which ensures that in most cases the order will be handled after having reached the web services. Using WsPCL ensures that offline handling in WsTransExternal is automatically switched on. If using older web services, this is not always true. If Harmoney doesn’t respond, the inbound order will be saved by WsTransExternal in an offline table to be sent again at later time. Orders saved in this manner will be resent once per hour for the next 24 hours. If the order still cannot be processed or Harmoney still is unreachable Pulsen will receive a notice.
Generally, in the WsPCL response, if the Response.TransStatus is 97 or 99 on an updating transaction (e.g. SaveOrder, SaveCustomer) the order is taken care of by the offline handling and the web can release control of it. However, it hasn’t reached all the way to Harmoney since some error has occurred. As before the web solution does not get an order number since this is generated in Harmoney. The web solution must therefore have some means of indicating for the end customer that the order is received but the order confirmation will be sent later.
In the rare occasions when the web services themselves are down, either WsPCL or WsTransExternal, the web solutions must have their own offline handling. They should be able to save the order and send it at a later time. It is therefore crucial that the web solution receives and reads the response from WsPCL to understand how the order should be handled.
If WsPCL itself doesn’t respond, no calls will be made to WsTransExternal and Harmoney. If Response.TransStatus is 90 it should be interpreted as WsTransExternal is down and the order could not be saved in the offline handling. If Response.TransStatus is 98 there is something wrong with the inbound data. The order will however be received and saved on the Control Page in Harmoney, and the web solution can thereby release control of the order. The web solution should give some form of message to the end customer, i.e. by checking Response.TransMessage for what kind of error that has occurred.
| Response.Success | TransStatus | Order.ControlStatus | Comment | Resend? |
|---|---|---|---|---|
| True | 00 | False | Everything is OK | No |
| True | 00 | True | Order on Control Page | No |
| False | 90 | Unable to contact WsTransExternal | Yes | |
| False | 97 | System closed, order saved in offline handling | No | |
| False | 98 | False | Error in data. Correct data before resending | Yes |
| False | 98 | True | Error in data. Order in control page | No |
| False | 99 | System error, order in offline handling | No |
The LoginInfo object¶
The LoginInfo object is used to transfer login information and settings for the call to WsPCL. All web methods require this authentication information to be included. This information is provided by Pulsen and does usually not change over time. It is recommended however to not provide the information as literals but rather store them in some secure way.
| Property | Type | Max length | Description | Example |
|---|---|---|---|---|
| SystemName | string | 3 char | The system name abbreviation | PXX |
| Username | string | 5 char | The client-specific username. | pulsen |
| UserPassword | string | 8 char | The client-specific password | akdKabn38 |
| SalesChannel | string | 3 char | The sales channel (försäljningskanal) | 001 |
| Language | Enum | N/A | Defines which language to use in transaction messages. | Language.English |