Skip to content

External Search Service

The External Search Service function can be used to retrieve information from other registers or systems. The search service can call an external register, for example the car register, the civil registry, but also an internal register, for example another customer register outside the Easit GO application.

This guide will try to explain how configuration affect the request sent and how to customize this.

Let's say we would like to search an external registry for a persons details, let us start by creating a new external search service in Easit GO.

General

In this section we configure some general information about the service such as name and description.

externalsearchservice-general

Before moving on, we need to create an item view to present the search result with. Create a simple view in the Contact module with the fields First name and Last name.

Query

In the query section we define if we would like to use REST/JSON or SOAP/XML, the URL to the service, authentication details and an identifier. Under mapping we can either define a custom search field or an existing field and use the value from that. In our case we want to use the later.

externalsearchservice-query

This configuration will produce a GET request to the service with a body that looks like this.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    {
        "itemViewIdentifier":"findBySSN",
        "columnFilter": [
            {
                "columnName": "socialSecurityNumber",
                "comparator": "EQUALS",
                "content": "valueFromTheField"
            }
        ]
    }

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>findBySSN</sch:ItemViewIdentifier>
                <sch:ColumnFilter columnName="Status" comparator="IN">Ongoing</sch:ColumnFilter>
            </sch:GetItemsRequest>
        </soapenv:Body>
    </soapenv:Envelope>

Response

View for search result

Here we define how Easit GO will present each search result in a view. Easit GO will automatically populate the section Mapping - View for search result with the fields from the view chosen under View for search result.

externalsearchservice-response

Property represents the name of the property returned by the external service. Field represent what field / column to display what property in.

Mapping - Form

This section defines what property to put in what field in a form, once we have chosen a search result (if many or any).

Based on the example above, Easit GO expects a response with in the following body.

 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
    {
        "columns":{
            "column": [
                {
                    "content": "First name",
                    "datatype": "STRING",
                    "collection": false,
                    "connectiontype": null
                },
                {
                    "content": "Surname",
                    "datatype": "STRING",
                    "collection": false,
                    "connectiontype": null
                }
            ]
        },
        "items": {
            "item":[
            {
                "property": [
                    {
                        "content": "Jane",
                        "name": "First name",
                        "rawValue": null
                    },
                    {
                        "content": "Doe",
                        "name": "Surname",
                        "rawValue": null
                    }
                ],
                "attachment": [],
                "id": "138:2"
            }
            ]
        },
        "requestedPage": 1,
        "page": 1,
        "pageSize" : 100,
        "totalNumberOfPages": 1,
        "totalNumberOfItems": 1,
        }

 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>
            <GetItemsResponse requestedPage="1" page="1" pageSize="100" totalNumberOfPages="1" totalNumberOfItems="1" xmlns="http://www.easit.com/bps/schemas">
            <Columns>
                <Column datatype="STRING" collection="false">First name</Column>
                <Column datatype="STRING" collection="false">Surname</Column>
            </Columns>
            <Items>
                <Item id="138:2">
                    <Property name="First name" rawValue="">Jane</Property>
                    <Property name="Surname" rawValue="">Doe</Property>
                </Item>
            </Items>
            </GetItemsResponse>
        </soapenv:Body>
        </soapenv:Envelope>

Result

With this configuration we can now query the external service from an existing contact in Easit GO. If the query returns more than 1 result, it will be presented in a item view as any other item in Easit GO. If the query returns 1 result, its property values will be mapped to (filled in) the form.