Anchor | ||||
---|---|---|---|---|
|
Table of Contents | ||
---|---|---|
|
...
Panel | ||
---|---|---|
| ||
How will versioning be handled?CXT Software will support the latest version, plus one previous published version. Response and Request objects, in addition to URLs, may have properties added with new releases. Business logic within the endpoints may change, and/or permission hardening may be applicable to existing endpoints with new releases |
Requirements
- X Dispatch 18.0 or newer.
- TLS 1.2
- When calling the web services for CXT hosted customers (designated by a domain in the format <CXTID>0.cxtsoftware.net), the calling system must connect with TLS 1.2
- TLS 1.2 is not supported on Windows 2008 R2 or below. The calling system can run Windows 7, 8.1 or 2012 or newer, all of which support TLS 1.2
Info | |||||
---|---|---|---|---|---|
|
Getting Started
Our web service is documented with Swagger UI and you can find a list of field definitions to help explain certain API fields. All customers can view this by going to https://<domain>/CxtWebService/CXTWCF.svc/api-docs/. For cloud customers, <domain> would be <CXTID>0.cxtsoftware.net, where <CXTID> is the 4 digit CXT Software account id. For example, if the CXT Software account id is 987, then the endpoint documentation is https://09870.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/
...
- Navigate to URL: https://<domain>/CxtWebService/CXTWCF.svc/api-docs
Authenticate by either getting an authentication token or using basic authentication. See Authenticate. Depending on the user type allowed to access the endpoint, you may need different tokens.
If getting an authorization token, place token in the Authorization Token box at the top.
Div - Make endpoint requests in JSON or XML
Address Validation
Info |
---|
For X Dispatch 19.0 or newer. |
...
Type | List/View | Add | Edit | Delete |
---|---|---|---|---|
Order | Must have permissions enabled for X Dispatch Functions > Orders | If the order is Invoiced
If an order is Settled
For uninvoiced and unsettled orders
| Same as Add permission | Same as Add permission |
Customer | Must have permissions enabled for X Dispatch Functions > Customers | Must have X Dispatch Functions > Customers > Edit Customers permission enabled | Same as Add permission | Must have X Dispatch Functions > Customers > Delete Customers permission enabled |
Human Resource | Must have permission enabled for Maintenance Functions > Human Resources > View Contractor Maintenance Functions > Human Resources > View Employees Maintenance Functions > Human Resources > View HR Advanced Information | Must have Maintenance Functions' -> Human Resources > Edit Human Resources permissions enabled | Same as Add permission | Same as Add permission |
Customer Contract | Must have X Route Functions > Contracts | Must have Contracts > Add Contracts permission enabled | Must have Contracts > Edit Contracts permission enabled | Same as Edit permission |
Authenticate
Most endpoints require authentication from the following user types:
...
You can see which user type(s) are required for an endpoint under "Implementation Notes". For example, "Allowed requestors: [Inet user]" requires an authenticated internet user and "Allowed requestors: [Mobile Users]" requires an authenticated driver user.
To authenticate, select sending an authorization token or doing a basic authentication with the call.
...
Driver endpoint: /v1/Authentication/Drivers
Div Valid duration of an authentication token: 30 days
Note title X Dispatch User Note "Allow web access" must be enabled on the driver record in the X Dispatch application. See Drivers - New / Edit Driver.
Internet User endpoint: /v1/Authentication/InetUser
Div Valid duration of an authentication token: 20 minutes
Note title X Dispatch User Note "Allow Web Service API" must be enabled on the internet user record in the X Dispatch application. See Internet Users - New / Edit Internet User.
Human Resources endpoint: /v1/Authentication/Worker
Div Valid duration of an authentication token: 30 days
Note X Dispatch User endpoint: /v1/Authentication/XdUser
Div Valid duration of an authentication token: 60 minutes
...
Paste code macro | ||
---|---|---|
| ||
curl -X GET --header "Accept: application/json" --header "Authorization: Token b1661ab49e5d42139b99a4a0ee741f0a" "https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/v1/Orders/9876" |
Basic Authentication
Basic authentication credentials must be sent with every request, base64 encoded and the username must be prefixed with 1 or 4 values to distinguish user type:
...
Paste code macro | ||||
---|---|---|---|---|
| ||||
System.Net.ServicePointManager.SecurityProtocol = System.Net.SecurityProtocolType.Tls12 | (SecurityProtocolType)3072; //TLS1.2 for for Windows 2012+, and 3072 is for Windows 2008 R2; Both can be left in place here without problem string url = "url" var request = System.Net.WebRequest.Create(url); request.Method = HttpMethod.Get.ToString(); string username = "username"; string password = "password"; string encoded = System.Convert.ToBase64String(System.Text.Encoding.ASCII.GetBytes(username + ":" + password)); request.Headers.Add("Authorization", "Basic " + encoded); ((System.Net.HttpWebRequest)request).Accept = "application/json"; return request; |
Examples
The following are examples to help you get started and is not an inclusive list. Use the endpoint URL examples to find documentation in the Swagger UI for details and testing.
...
Parameter | Description | Parameter Type | Data Type |
---|---|---|---|
workOrderId | The unique identifier of the work order on which the status will be updated. | path | string |
status | The updated work order status to be persisted. | body | JSON/XML |
Troubleshooting
If you are experiencing connection issues and need CXT Software to help troubleshoot, add the following to the Web.config file, within the <configuration> tag and adjust the log name/location in the 'initializeData' attribute of the snippet below. Make the problematic call. Then include the resulting log as part of the information provided to CXT for troubleshooting.
Paste code macro |
---|
<system.diagnostics> <trace autoflush="true" /> <sources> <source name="System.Net" maxdatasize="1024"> <listeners> <add name="MyTraceFile"/> <add name="MyConsole"/> <add name="MyText"/> </listeners> </source> </sources> <sharedListeners> <add name="MyTraceFile" type="System.Diagnostics.TextWriterTraceListener" initializeData="System.Net.trace.log" /> <add name="MyConsole" type="System.Diagnostics.ConsoleTraceListener" /> <add name="MyText" type="System.Diagnostics.TextWriterTraceListener" initializeData="C:\Temp\RequestTrace.log"></add> </sharedListeners> <switches> <add name="System.Net" value="Verbose" /> </switches> </system.diagnostics> |