The purpose of this website is to fully describe the ServiceDesk API of Wello: how it works, what you can do with it, the restrictions and some example code.
ServiceDesk is a complete online solution that provides access on your services data (task,work order) to your customers.
In the case your customer has already a system in place to manage his "Service Request" and don't want to use the interface of ServiceDesk, then they can use this API to directly access the data.
With ServiceDeskAPI, you can mainly :
The ServiceDeskAPI is using the same structure as the full Wello API.
Please visit his website https://developers.wello.solutions for all the information.
This website is composed of 2 parts :
- Help GuideAll information required to understand how this API works.
- ReferenceGenerated documentation about the entities (objects), their properties (fields names and types) and their methods.
As a first quick exercise, let's build a request to the API together. Imagine you want to add a Service Request (in Wello, it's a Task).
A request to the API is always composed of 3 parts: 1) Request URL, 2) Header and 3) Body.
1) Request URL
To work on the tasks use the following request Url :https://v1servicedeskapi.wello.solutions/api/Task
As we are adding a created task, use the method POST
You need authentication to communicate with the API. (Go to "Authentification" for more info)
For this example we will use the following credentials :
Domain=TESTAPI , Contact E-Login=test@wello.solutions, Password=123456
Using the following format:
elogin:epassword@domain
filled with the above mentioned credentials, we get:
test@wello.solutions:123456@TESTAPI
If we then encode it in Base 64, we get:
dGVzdEB3ZWxsby5zb2x1dGlvbnM6MTIzNDU2QFRFU1RBUEk=
Finally the line on the header for authentification will be :
Authorization: Basic dGVzdEB3ZWxsby5zb2x1dGlvbnM6MTIzNDU2QFRFU1RBUEk=
Accept / Content-type : XML or JSON
The API support the 2 formats. By default and if nothing is found on the HTTP REQUEST, API will uses JSON.
If you want to receive data in XML format, use the following on the header
Accept: application/xml
If you want to send data (POST/PUT) in XML format, use the following on the header
Content-Type: application/xml
XML format is more easy to read, and used on this tutorial, let's use it.
Request Header
Authorization: Basic dGVzdEB3ZWxsby5zb2x1dGlvbnM6MTIzNDU2QFRFU1RBUEk= Accept: application/xml Content-Type: application/xml
For optimization, we can use the tag prefer: return=minimal on the request header to only receive the "ID" (Guid) on Post/Put but for debugging it's easier to have the full object.
See Wello API for more information.
By browsing the Reference documentation of the API, you can determine the fields you need/want to use.
For this exercise we will fill the following:subject
Request body
<task> <subject>My first Task created using ServiceDeskAPI!</subject> </task>
Let's test this URL, Header and Body and check the response message...
HTTP Response 201.(Entity Created) with the object
Because we specify that we want to have the full entity created, the result contains all the fields of the entity and not just his id.
<task> <archived>false</archived> <company_id>4b2f9a4a-e6cb-4284-af46-dec586b4f816</company_id> <contact_id>37c136cc-cabe-4232-ac55-e52f98c8e08a</contact_id> <customer_reference></customer_reference> <date_create>2013-09-07T13:09:39.080Z</date_create> <id>8de3a297-2122-41b0-a4cf-3507561f6eb7</id> <id2>22</id2> <modified_dateutc>2013-09-07T13:09:39.080Z</modified_dateutc> <subject>My first Task created using ServiceDeskAPI!</subject> ... <task_priority_id>329ad9ec-42b2-44d5-8fe8-c049d1327711</task_priority_id> <task_status_id>f3507920-d746-4d1c-b81b-c2bf291830c5</task_status_id> <task_type_id>0e246b0e-6bfa-4836-917e-e26e879e7d04</task_type_id> </task>
As we can see, just filling one field (suject) was enough!
All the other fields are filled via the credentails used (like contact_id,company_id) and the default values are used (task_type_id,task_status_id,task_priority_id).
Let's now list all the task we have access
Request URL
/api/TaskView
<arrayoftask_view> <task_view> <archived>false</archived> <company_code></company_code> <company_id>4b2f9a4a-e6cb-4284-af46-dec586b4f816</company_id> <company_name>Test Company</company_name> <contact_db_address_email></contact_db_address_email> <contact_db_address_phone></contact_db_address_phone> <contact_fullname>John Doe</contact_fullname> <contact_id>37c136cc-cabe-4232-ac55-e52f98c8e08a</contact_id> <date_closed>2013-09-07T14:01:46.030Z</date_closed> <date_create>2013-09-07T13:09:39.080Z</date_create> <db_address_email>test@wello.solutions</db_address_email> <db_address_phone>02/513.48.19</db_address_phone> <id>8de3a297-2122-41b0-a4cf-3507561f6eb7</id> <id2>22</id2> <remark></remark> <subject>My first Task created using ServiceDeskAPI!</subject> <task_priority_id>329ad9ec-42b2-44d5-8fe8-c049d1327711</task_priority_id> <task_priority_name>Normal Priority</task_priority_name> <task_status_description>This is the default task status</task_status_description> <task_status_id>f3507920-d746-4d1c-b81b-c2bf291830c5</task_status_id> <task_status_name>Open</task_status_name> <task_type_id>0e246b0e-6bfa-4836-917e-e26e879e7d04</task_type_id> <task_type_name>Task from ServiceDesk</task_type_name> </task_view> </arrayoftask_view>
As you can see, this kind of response is very easy to make a list of result.
Mainly fields will be : task_status_name, subject
In this example we have created a company in the Wello database using an API call and then verified it was well created by our first call.
Congratulations, you have now done your 2 first API calls!
That's all !
In this example we have created a company in the Wello database using an API call and then verified it was well created by our first call.
Congratulations, you have now done your 2 first API calls!
Optimalization
Even if these calls are working, we encourage you to optimize your client, using for example compression,JSON and ODATA $select
Please visit Wello API Website for more information.