Connecting external Data Sources (e.g. a CRM)

Search…
atfinity allows you to connect external instance data sources so users can copy values from those directly.
To connect an external data source, follow these steps:
1.
Specify your Data Source under Administration -> Data Sources
First, name the data source for a certain ontology and create it. Then specify the urls where atfinity should send list and retrieve requests. A list request should return a selection of instances where users can copy values from. A retrieve request returns values for a single instance. 
2.
Specify the data source for an ontology
Open any ontology under configuration -> ontologies. Under "External Data Source" mention the source you have just created. 
Requirements on your API
List Request
URL
atfinity will append ?q=QUERY to the url specified for the list request and make a GET request to this url. So specifying https://api.yourcrm.com/api/search_person would make a request tohttps://api.yourcrm.com/api/search_person?q=QUERY, where QUERY will be replaced with a url-encoded version of the user entered query.  
Request Header
Key
Value
Content-Type
application/json
From
The email of the user making the request
atfinity-Ontology
The key of the ontology atfinity expects to get data for
Custom
Your specified key and value from Administration -> Data Sources
Response
atfinity expects to receive JSON looking like this. The name will be displayed to the user and the identifier will be used for the retrieve request. Both can be arbitrary strings. 
1
{
2
    "data": [
3
        {
4
            "identifier": "10098",
5
            "name": "Thorben Croisé"
6
        },
7
        {
8
            "identifier": "10099b",
9
            "name": "Alexander Balzer"
10
        }
11
    ],
12
    "meta": {
13
        "pagination": {
14
            "count": 2,
15
            "page": 1,
16
            "pages": 1
17
        }
18
    }
19
}
Copied!
Pagination
atfinity handles pagination of the returned instance list if necessary. At a time, only 20 entries will be displayed. In the meta.pagination part of the response atfinity expects those values:
Key
Value
count
The total count of all instances
page
The currently displayed tuest
pages
The total count of all pages
When used navigate to the next page, these extra query parameters will be included in the request:
Parameter
Value
page
The requested page
page_size
The page size, usually this stays fixed at 20
Retrieve Request
URL
atfinity will append the value of IDENTIFIER acquired in the list request to the url and make a GET request to this url. So specifying https://api.yourcrm.com/api/person/ would make a request tohttps://api.yourcrm.com/api/person/IDENTIFIER . 
Request Header
Key
Value
Content-Type
application/json
From
The email of the user making the request
atfinity-Ontology
The key of the ontology atfinity expects to get data for
Custom
Your specified key and value from Administration -> Data Sources
Response
atfinity expects to receive JSON looking like this. All the values within data will be tried to match to information keys of the ontology of the instance this request has been made for. 
1
{
2
    "data": {
3
        "cid": "1",
4
        "first_name": "Thorben",
5
        "last_name": "Croisé"
6
    }
7
}
Copied!
API - Previous
Calling your APIs within Cases
Next - Deploying
Deploying on-site
Last modified 12d ago
Copy link
Contents
Requirements on your API
List Request
Retrieve Request