FieldEZ Integration Specs – API Documentation

The FieldEZ API allows you to interact with our system programmatically from your own application. The FieldEZ API enables FieldEZ to support bi-directional transfer of ticket/work order/lead data with external systems (lead management systems/ERP/CRM etc.).

Integration Modes

There are two ways of integrating an external system with FieldEZ

  • Use web service (REST/SOAP/Simple HTTP). Advantage – real time update. Fastest, reliable and recommended.
  • Use batch file over FTP/SFTP. Since it works on the batch mode (using a schedule script), the updates will have max lag of the scheduled upload/download interval.

Defining the message structure is a crucial point in integration costing and timeline. There are three options in defining message structure.

  • Use FieldEZ defined message structure (XML) for incoming and outgoing messages. There is no change required in FieldEZ. All the changes are in external system. This is the cheapest and the fastest.
  • Use FieldEZ defined message structure (XML) for incoming, for outgoing messages use external system defined message structure. Changes are in both ends – middle path.
  • Use external system defined message structure for both incoming and outgoing messages. The entire development work is in FieldEZ – time consuming.

Web service

If the integration is on web service mode, messages between FieldEZ and the client application is over HTTP/HTTPS. All the APIs take input in key value pair style (not in REST style) and responds to the client in XML format. Authentication is through exchange of a login id/password combination maintained in FieldEZ as well as in customer application.

The payload request parameter in inbound API is XML. The name property of attribute element in payload XML should be configured as Integration Label of the respective workflow form element. This configuration can be done in web application. For example, if you have a workflow by name Maintenance with a form element Contact No, configure integration label as contactNo and pass the corresponding data in payload XML as 67243554423. This way, even if you later decide to change the display label, you could keep the same integration label, so that there is no change in integration client adaptor.

API specs

1.       Save ticket

Type – Inbound

Use – Used to create or update a ticket in FieldEZ

Method – POST

URI – /emob/integration/saveTicket.action

Request parameters

NameDescriptionMandatoryValidationLength
payloadTicket data in XML format. Please refer the sample XML and XSD attached here

(1)Save-ticket.xsd

(2)Save-ticket.txt

Yes
apiKeyLogin id for the client applicationYes
apiTokenPassword for the client applicationYes

Response XML

<fieldez api=”saveTicket”>

<reponseCode>response code</ reponseCode>

<reponseMessage>response message</ reponseMessage>

<validationErrors> (optional)

<validationError>message</validationError> (multiple occurrence possible)

</ validationErrors>

</fieldez>

2. Save Ticket Item

Type – Inbound

Use – Used to create or update a ticket item (Parts/order items etc.) in FieldEZ

Method – POST

URI – /emob/integration/saveTicketItem.action

Request parameters

NameDescriptionMandatoryValidationLength
payloadTicket Item data in XML format. Please refer the sample XML and XSD attached here

(1)Save-ticketItem.xsd

(2)Save-ticketItem.txt

Yes
apiKeyLogin id for the client applicationYes
apiTokenPassword for the client applicationYes

Response XML

<fieldez api=”saveTicketItem”>

<reponseCode>response code</ reponseCode>

<reponseMessage>response message</ reponseMessage>

<validationErrors> (optional)

<validationError>message</validationError> (multiple occurrence possible)

</ validationErrors>

                                </fieldez>

3.  Save Ticket Status – Inbound

Type – Inbound

Use – To update ticket status in FieldEZ

Method – POST

URI – /emob/integration/saveTicketStatus.action

Request parameters

NameDescriptionMandatoryValidationLength
payloadTicket status data in XML format. Please refer the sample XML and XSD attached here

(1)Save-ticketStatus.xsd

(2)Save-ticketStatus.txt

Yes
apiKeyLogin id for the client applicationYes
apiTokenPassword for the client applicationYes

Response XML

<fieldez api=”saveTicketStatus”>

<reponseCode>response code</ reponseCode>

<reponseMessage>response message</ reponseMessage>

<validationErrors> (optional)

<validationError>message</validationError> (multiple occurrence possible)

</ validationErrors>

</fieldez>

4.  Save Ticket Status – Outbound

Type – Outbound

Use – To update ticket status in external system (customer’s CRM)

Method – POST

URI – Customer to provide this URI

Request parameters

NameDescriptionMandatoryValidationLength
payloadTicket status data in XML format. Please refer the sample XML and XSD attached here

(1)OutboundStatusUpdate.xml

(2)OutboundStatusUpdate.xsd

Yes
apiKeyLogin id for the client applicationYes
apiTokenPassword for the client applicationYes

Response XML

<fieldez api=”saveTicketStatus”>

<reponseCode>response code</ reponseCode>

<reponseMessage>response message</ reponseMessage>

<validationErrors> (optional)

<validationError>message</validationError> (multiple occurrence possible)

</ validationErrors>

</fieldez>

Response codes

200 – Success

500 – Server error

501 – Duplicate call/lead/ticket

600 – Duplicate Lead/Ticket/Call

405 – Invalid login credentials (appLoginId/appPassword combination)

406 – Invalid assignee

300 – Invalid input

301 – No such Lead/Ticket/Call