Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: ted.  If the "Enforce address validation when using web service" global option for enforcing address validation

...

Panel
titleImportant Items to Note
  • Authentication is needed for most endpoints. You will need to send an authorization token or do a basic authentication with the call.
  • Dates entered should be in milliseconds in UTC for JSON requests (e.g. 1559651878000) and ISO-8601 standard for XML requests (e.g. 2019-06-04T07:36:53).
  • Dates returned are formatted according to X Dispatch the Operations App global options settings and localized to where the order was picked up/delivered with the timezone noted.
  • When entering the workOrderId parameter it must be in the following format:

    • route stop: r<stopID>
    • on demand pickup: p<orderID>
    • on demand delivery: d<orderID>

How will versioning be handled?

CXT Software will support the latest version, plus one previously 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 Operations App 21.0 or newer.
  • TLS 1.2
    • When calling the web services for CXT Cloud 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

...

  • If the "Enforce Address Validation" global option is checked inside X Dispatchthe Operations App, an order/stop will be successfully placed only if the address is validated; the order will fail if the address cannot be validated. If "Enforce Address Validation" is unchecked, the order placement will succeed regardless of validation.
  • Only the geocode (lat/lon) is updated when the addresses can be validated. 
  • If the "Enforce address validation when using web service" global option is checked inside the Operations App, route stops created through the web service will have address validation enforced.

Attachments

Requirements for uploading a file (attachment creation/update):

...

Attachment Permissions > Maintenance > Permissions.

TypeList/ViewAddEditDelete
OrderMust have permissions enabled for X Dispatch Functions > Orders

If the order is Invoiced

  • Must have X Dispatch Functions > Orders > Edit Invoiced Orders > Edit Invoiced Attachments permission enabled

If an order is Settled

  • Must have X Dispatch Functions > Orders > Edit Settled Orders > Edit Settled Attachments permission enabled

For uninvoiced and unsettled orders

  • Must have X Dispatch Functions > Orders > Edit Orders permission enabled
Same as Add permissionSame as Add permission
CustomerMust have permissions enabled for X Dispatch Functions > CustomersMust have X Dispatch Functions > Customers > Edit Customers permission enabledSame as Add permissionMust 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 permissionSame as Add permission
Customer ContractMust have X Route Functions > ContractsMust have Contracts > Add Contracts permission enabled
Must have Contracts > Edit Contracts permission enabled
Same as Edit permission

...

  • Driver
  • Internet User
  • Human Resource
  • X Dispatch Operations App User

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.  

...

  • Driver endpoint: /v2/Authentication/Drivers 

    Div

    Valid duration of an authentication token: 30 days  

    Note
    titleX Dispatch User Note

    "Allow web access" must be enabled on the driver record in the X Dispatch Operations App application. See Drivers (Classic Operations App).



  • Internet User endpoint: /v2/Authentication/InetUser 

    Div

    Valid duration of an authentication token: 20 minutes

    Note
    titleX Dispatch User Note

    "Allow Web Service API" must be enabled on the internet user record in the X Dispatch Operations App application. See Internet Users (Classic Operations App).



  • Human Resources endpoint: /v2/Authentication/Worker  

    Div

    Valid duration of an authentication token: 30 days

    Note

    See Human Resources - New / Edit Human Resource



  • X Dispatch Operations App User endpoint: /v2/Authentication/XdUser 

    Div

    Valid duration of an authentication token: 3 hours 


...

  • Driver prefix: DRIVER
  • Internet User prefix: INET
  • Human Resources prefix: WORKER
  • X Dispatch Operations App User prefix: XDISPATCH

An example of an internet user with the username "cxtsupport" is "INET-cxtsupport".

...

Creating a new order creates a new on demand order in X Dispatch the Operations App and requires an internet user authorization token. Use this endpoint if a static order type is provided. Order types in X Dispatch the Operations App define the timing and level of service for on demand orders. 

...

You can use the /v2/Orders endpoint to create new on demand order in X Dispatchthe Operations App.

Endpoint URLhttps://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/index.html?url=/CxtWebService/CXTWCF.svc/v2/swagger.json#!/Orders/CxtSoftware_MiddleTier_WebService_CXTWCF_OnDemandOrder_CreateV2 

...

Creating a new route stop creates a new route stop in X Dispatch the Operations App and requires an Operations App (X Dispatch user [XDUser]) user authentication token.

How to Create a Route Stop

...