Skip to content

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

1
2
3
4
{
  "itemViewIdentifier":"identifierOfWebserviceView",
  "page": 4
}

1
2
3
4
5
6
7
8
9
<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>

1
2
3
4
5
6
7
$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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
  "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,
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<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>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "itemViewIdentifier":"identifierOfWebserviceView",
  "columnFilter": [
    {
      "columnName": "Status",
      "comparator": "IN",
      "content": "Ongoing"
    }
  ]
}

1
2
3
4
5
6
7
8
9
<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>

1
2
3
4
5
6
7
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).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "itemViewIdentifier":"allRequest",
  "page": 1,
  "columnFilter": [
    {
      "columnName": "Status",
      "comparator": "EQUALS",
      "content": "Ongoing"
    }
  ],
  "sortColumn": {
    "content": "Created",
    "order": "Ascending"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<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>

1
2
3
4
5
6
7
8
9
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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "importHandlerIdentifier": "identifierOfImportHandlerIdentifier",
  "itemToImport": [
    {
      "property": [
        {
          "content": "value1",
          "name": "property1"
        },
        {
          "content": "value2",
          "name": "property2"
        }
      ],
      "uid": 1,
      "id": 1
    }
  ]
}
- itemToImport: List of objects representing items to send to EasitGO.
- property: For each object in itemToImport. List of objects representing the items properties and its values we would like to send to EasitGO.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<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>
- ItemToImport: One or more occurrence each with a unique id and UID. Each occurrence represents an item.
- Property: The items property or properties.

1
2
3
4
5
6
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "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
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
<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>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "importItemResult": [
    {
      "skippedOrExceptionMessage": null,
      "returnValues": null,
      "uid": "1",
      "result": "OK"
    },
    {
      "skippedOrExceptionMessage": null,
      "returnValues": null,
      "uid": "2",
      "result": "OK"
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
<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>

1
2
3
4
5
6
7
8
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "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"
    }
]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
<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>

1
2
3
4
5
6
7
8
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "importItemResult": [
    {
      "result": "Exception",
      "returnValues": null,
      "skippedOrExceptionMessage": "java.lang.IllegalArgumentException: [fullStacktrace]",
      "uid": "2"
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<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>

1
2
3
4
5
PS C:\Users\me> Import-GOCustomItem @importEasitItem -ImportHandlerIdentifier 'importHandlerIdentifier' -CustomProperties $CustomProperties

Exception: java.lang.IllegalArgumentException: [fullStacktrace]

PS C:\Users\me>