Request and response examples
Views (itemViewIdentifier)
In Easit GO, as an example, we have an item view with a large number of items, all kind of requests, and we have configured the item view in such a way that id, status and created is available for the view (itemViewIdentifier). Lets say we would like to get all items from page 4 of that view, the GET requests body would looks like this.
More info on how to configure a view
Request
{
"itemViewIdentifier":"identifierOfWebserviceView",
"page": 4
}
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://www.easit.com/bps/schemas">
<soapenv:Header/>
<soapenv:Body>
<sch:GetItemsRequest>
<sch:ItemViewIdentifier>identifierOfWebserviceView</sch:ItemViewIdentifier>
<sch:Page>4</sch:Page>
</sch:GetItemsRequest>
</soapenv:Body>
</soapenv:Envelope>
$params = @{
url = ''
apikey = ''
importViewIdentifier = 'identifierOfWebserviceView'
page = 4
}
$items = Get-GOItem @params
Response
To save space, we have edited the response to only display 1 item in the response.
{
"columns":{
"column": [
{
"content": "Id",
"datatype": "INTEGER",
"collection": false,
"connectiontype": null
},
{
"content": "Created",
"datatype": "DATETIME",
"collection": false,
"connectiontype": null
},
{
"content": "Status",
"datatype": "CONNECTION",
"collection": false,
"connectiontype": "PROPERTY"
}
]
},
"items": {
"item":[
{
"property": [
{
"content": "201",
"name": "Id",
"rawValue": "201"
},
{
"content": "2020-03-16 15:30",
"name": "Created",
"rawValue": "2020-03-16T14:30:08.000Z"
},
{
"content": "Open",
"name": "Status",
"rawValue": "74:1"
}
],
"attachment": [],
"id": "138:2"
}
]
},
"requestedPage": 4,
"page": 4,
"pageSize" : 100,
"totalNumberOfPages": 10,
"totalNumberOfItems": 1000,
}
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<GetItemsResponse requestedPage="4" page="4" pageSize="100" totalNumberOfPages="10" totalNumberOfItems="1000" xmlns="http://www.easit.com/bps/schemas">
<Columns>
<Column datatype="INTEGER" collection="false">Id</Column>
<Column datatype="DATETIME" collection="false">Created</Column>
<Column datatype="CONNECTION" collection="false" connectiontype="PROPERTY">Status</Column>
</Columns>
<Items>
<Item id="138:2">
<Property name="Id" rawValue="201">201</Property>
<Property name="Created" rawValue="2020-03-16T14:30:08.000Z">2020-03-16 15:30</Property>
<Property name="Status" rawValue="74:1">Open</Property>
</Item>
</Items>
</GetItemsResponse>
</soapenv:Body>
</soapenv:Envelope>
PS C:\Users\me> $items[0]
TypeName: System.Management.Automation.PSCustomObject
requestedPage : 4
totalNumberOfPages : 10
totalNumberOfItems : 100
databaseId : 138:2
Id : 201
Id_rawValue : 201
Created : 2020-03-16 15:30
Created_rawValue : 2020-03-16T14:30:08.000Z
Status : Open
Status_rawValue : 74:1
- Columns -> Column: List with specification for each column (field in EasitGO) present in the view.
- items -> item: List of all items returned by the view.
- requestedPage: The page specified in the request.
- page: Received page from view.
- pageSize: How many items for each page.
- totalNumberOfPages: How many pages the view contains.
- totalNumberOfItems: How many items the view contains.
Request - columnFilter
Lets say we would like to get a subset of those items, perhaps all ongoing request. Then we can use something called column filters and the GET requests body would looks like this. Note that the column that you would like to filter on need to be in the item view. Also note that columnFilter is an array or list and can hold as many filters as you need. Read more about comparators here.
{
"itemViewIdentifier":"identifierOfWebserviceView",
"columnFilter": [
{
"columnName": "Status",
"comparator": "IN",
"content": "Ongoing"
}
]
}
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://www.easit.com/bps/schemas">
<soapenv:Header/>
<soapenv:Body>
<sch:GetItemsRequest>
<sch:ItemViewIdentifier>identifierOfWebserviceView</sch:ItemViewIdentifier>
<sch:ColumnFilter columnName="Status" comparator="IN">Ongoing</sch:ColumnFilter>
</sch:GetItemsRequest>
</soapenv:Body>
</soapenv:Envelope>
PS C:\Users\me> $params = @{
url = ''
apikey = ''
importViewIdentifier = 'identifierOfWebserviceView'
ColumnFilter = "Status,IN,Waiting customer"
}
PS C:\Users\me> $items = Get-GOItems @params
Request - sortColumn
Lets say that we also want to sort the data by creation (oldest first).
{
"itemViewIdentifier":"allRequest",
"page": 1,
"columnFilter": [
{
"columnName": "Status",
"comparator": "EQUALS",
"content": "Ongoing"
}
],
"sortColumn": {
"content": "Created",
"order": "Ascending"
}
}
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://www.easit.com/bps/schemas">
<soapenv:Header/>
<soapenv:Body>
<sch:GetItemsRequest>
<sch:ItemViewIdentifier>identifierOfWebserviceView</sch:ItemViewIdentifier>
<sch:ColumnFilter columnName="Status" comparator="IN">Ongoing</sch:ColumnFilter>
<sch:SortColumn order="Ascending">Created</sch:SortColumn>
</sch:GetItemsRequest>
</soapenv:Body>
</soapenv:Envelope>
PS C:\Users\me> $params = @{
url = ''
apikey = ''
importViewIdentifier = 'identifierOfWebserviceView'
ColumnFilter = "Status,IN,Waiting customer"
sortField = 'Created'
sortOrder = 'Ascending'
}
PS C:\Users\me> $items = Get-GOItems @params
Importhandler (importHandlerIdentifier)
Regardless if you are updating existing or creating new items, the requests body for looks the same and follows this structure.
{
"importHandlerIdentifier": "identifierOfImportHandlerIdentifier",
"itemToImport": [
{
"property": [
{
"content": "value1",
"name": "property1"
},
{
"content": "value2",
"name": "property2"
}
],
"uid": 1,
"id": 1
}
]
}
- property: For each object in itemToImport. List of objects representing the items properties and its values we would like to send to EasitGO.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://www.easit.com/bps/schemas">
<soapenv:Header/>
<soapenv:Body>
<sch:ImportItemsRequest>
<sch:ImportHandlerIdentifier>importHandlerIdentifier</sch:ImportHandlerIdentifier>
<sch:ItemToImport id="1" UID="1">
<sch:Property name="property1">value1</sch:Property>
<sch:Property name="property2">value2</sch:Property>
</sch:ItemToImport>
</sch:ImportItemsRequest>
</soapenv:Body>
</soapenv:Envelope>
- Property: The items property or properties.
PS C:\Users\me> $importEasitItem = @{
url = ''
api = ''
}
PS C:\Users\me> $CustomProperties = @{'property1' = 'value1';'property2' = 'value2'}
PS C:\Users\me> Import-GOCustomItem @importEasitItem -ImportHandlerIdentifier 'importHandlerIdentifier' -CustomProperties $CustomProperties
More info on how to configure a importhandler
In the example below we are sending two items with the properties 'property1' and 'property2'. Since we are sending multiple items we need to add 'uid' and 'id'. These are used for troubleshooting and could be found in the logs for Easit GO.
Request
{
"importHandlerIdentifier": "importHandlerIdentifier",
"itemToImport": [
{
"property": [
{
"content": "value1",
"name": "property1"
},
{
"content": "value2",
"name": "property2"
}
],
"uid": 1,
"id": 1
},
{
"property": [
{
"content": "value1",
"name": "property1"
},
{
"content": "value2",
"name": "property2"
}
],
"uid": 2,
"id": 2
}
]
}
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://www.easit.com/bps/schemas">
<soapenv:Header/>
<soapenv:Body>
<sch:ImportItemsRequest>
<sch:ImportHandlerIdentifier>importHandlerIdentifier</sch:ImportHandlerIdentifier>
<sch:ItemToImport id="1" UID="1">
<sch:Property name="property1">value1</sch:Property>
<sch:Property name="property2">value2</sch:Property>
</sch:ItemToImport>
<sch:ItemToImport id="2" UID="2">
<sch:Property name="property1">value1</sch:Property>
<sch:Property name="property2">value2</sch:Property>
</sch:ItemToImport>
</sch:ImportItemsRequest>
</soapenv:Body>
</soapenv:Envelope>
PS C:\Users\me> $importEasitItem = @{
url = ''
api = ''
}
PS C:\Users\me> $items = @(
@{
property1 = 'value1'
property2 = 'value2'
},
@{
property1 = 'value1'
property2 = 'value2'
}
)
PS C:\Users\me> foreach ($item in $items) {
Import-GOCustomItem @importEasitItem -ImportHandlerIdentifier 'importHandlerIdentifier' -CustomProperties $item
}
Response without return values
{
"importItemResult": [
{
"skippedOrExceptionMessage": null,
"returnValues": null,
"uid": "1",
"result": "OK"
},
{
"skippedOrExceptionMessage": null,
"returnValues": null,
"uid": "2",
"result": "OK"
}
]
}
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<ImportItemsResponse xmlns="http://www.easit.com/bps/schemas">
<ImportItemResult UID="1" result="OK">
<ReturnValues/>
</ImportItemResult>
<ImportItemResult UID="2" result="OK">
<ReturnValues/>
</ImportItemResult>
</ImportItemsResponse>
</soapenv:Body>
</soapenv:Envelope>
PS C:\Users\me> Import-GOCustomItem @importEasitItem -ImportHandlerIdentifier 'importHandlerIdentifier' -CustomProperties $CustomProperties
ImportItemResult
----------------
OK
OK
PS C:\Users\me>
The default response will have a property named 'result' with OK if no error occurred during the process. It is possible to configure a importhandler to return values. A response from a importhandler with return values looks like this.
Response with return values
{
"importItemResult": [
{
"skippedOrExceptionMessage": null,
"returnValues": {
"returnValue": [
{
"content": "true",
"name": "returnOK"
}
]
},
"uid": "1",
"result": "OK"
},
{
"skippedOrExceptionMessage": null,
"returnValues": {
"returnValue": [
{
"content": "true",
"name": "returnOK"
}
]
},
"uid": "2",
"result": "OK"
}
]
}
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<ImportItemsResponse xmlns="http://www.easit.com/bps/schemas">
<ImportItemResult UID="1" result="OK">
<ReturnValues>
<ReturnValue name="returnOK">true</ReturnValue>
</ReturnValues>
</ImportItemResult>
<ImportItemResult UID="2" result="OK">
<ReturnValues>
<ReturnValue name="returnOK">true</ReturnValue>
</ReturnValues>
</ImportItemResult>
</ImportItemsResponse>
</soapenv:Body>
</soapenv:Envelope>
PS C:\Users\me> Import-GOCustomItem @importEasitItem -ImportHandlerIdentifier 'importHandlerIdentifier' -CustomProperties $CustomProperties
ImportItemResult returnOK
---------------- --------
OK true
OK true
PS C:\Users\me>
Response with exception message
{
"importItemResult": [
{
"result": "Exception",
"returnValues": null,
"skippedOrExceptionMessage": "java.lang.IllegalArgumentException: [fullStacktrace]",
"uid": "2"
}
]
}
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<ImportItemsResponse xmlns="http://www.easit.com/bps/schemas">
<ImportItemResult UID="1" result="Exception">
<SkippedOrExceptionMessage>java.lang.IllegalArgumentException: [fullStacktrace]"</SkippedOrExceptionMessage>
</ImportItemResult>
</ImportItemsResponse>
</soapenv:Body>
</soapenv:Envelope>
PS C:\Users\me> Import-GOCustomItem @importEasitItem -ImportHandlerIdentifier 'importHandlerIdentifier' -CustomProperties $CustomProperties
Exception: java.lang.IllegalArgumentException: [fullStacktrace]
PS C:\Users\me>