LogoLogo
User DocsAPI Docsatfinity.swiss
  • 🚀Atfinity: No-Code Process Automation
  • Guides
    • Getting Started
      • Introduction
      • 1. Create Ontologies and Roles
      • 2. Create Information
      • 3. Create and Configure a Document
      • 4. Create a Rule
      • 5. Create a Process
      • 6. Put Live
      • Summary and Next Steps
    • Advanced Topics
      • Extending a Workflow
      • Customizing Names of Cases and Instances
      • Automatically Calculating Information Values
      • Using Built in Integrations
    • Troubleshooting
      • Why is a question not asked?
      • Why is a question asked?
      • The value of my calculated field has a strange format
      • Why is my Proof never asked for?
      • Why is my Rule not executed?
      • Why are some options missing in a dropdown?
      • Case Errors
    • Glossary
      • Case
      • Process
      • Workflow
      • Ontology
      • Instance
      • Role
      • Information
      • Document
      • Document Section
      • Document Template
      • Rules
      • Scheduled Rules
      • Information Types
      • Tab
      • Category
      • Taxonomy
      • Proof
      • RuLa Functions
      • Constants
  • Rule Language (RuLA)
    • ℹ️What is RuLa?
    • Declarations
      • is
      • is with where
      • is all
      • is all with min max
      • Role Choices
    • Expressions
    • Operators
      • Boolean Operators
        • =
        • !=
        • >
        • >=
        • <
        • <=
        • and
        • and then
        • not
        • or
        • or else
        • matches (~=)
      • Date Operators
        • NOW
        • IS_DATE
        • TODAY
        • FORMAT_DATE
        • DAYS
        • WEEKDAYS
        • ADD_DAYS
        • ADD_WEEKDAYS
        • ADD_MONTH
        • ADD_YEARS
        • SUBTRACT_YEARS
        • AFTER
        • DATE_EQUAL
        • DATETIME_EQUAL
        • AFTER_EQUAL
        • BEFORE
        • BEFORE_EQUAL
        • DAYS_AGO
        • MONTHS_AGO
        • YEARS_AGO
      • Known Operators
        • unknown
        • known
        • SNEAKY
        • AVG_OF_ANY
        • LIST_OF_ANY
        • MAX_OF_ANY
        • MIN_OF_ANY
        • SUM_OF_ANY
        • CONCAT_OF_ANY
        • UNION_OF_ANY
        • JOIN_OF_ANY
      • List Operators
        • [ , ] (create)
        • [] (access)
        • in
        • not in
        • contains
        • contains any
        • contains only
        • COUNT
        • SORT
        • CUSTOM_MAX
        • REVERSE
        • FIRST_ELEMENT
        • ALL
        • SOME
        • UNION (or |)
        • SET_DIFFERENCE
        • INTERSECTION
        • MAP
        • FILTER
        • FILTER_FALSE
        • FILTER_UNKNOWN
        • SET
      • Dictionary Operators
        • {} (create)
        • [] (access)
        • in
        • keys()
        • FLATTEN
      • Mathematical Operators
        • + - / *
        • %
        • **
        • //
        • AVG
        • CEIL
        • FLOOR
        • MAX
        • MIN
        • ROUND
        • SUM
        • SUM_PRODUCT
        • SQRT
      • String Operators
        • LEN
        • LOWER
        • UPPER
        • TRIM
        • TRIM_LEFT
        • LEFT
        • RIGHT
        • SLICE
        • REPLACE
        • REPLACE_CHARS
        • format
        • calculated_name
        • CONCAT
        • markdown_table
        • make_filename
        • JOIN
        • uuid
      • Special Operators
        • :=
        • ensure
        • get_attr
        • get_translated_attr
        • has_attr
        • get_properties
        • instances
        • instances_exist
        • is
        • ontology
        • Translate (.$)
        • translate_string
        • roles
        • self
        • name_and_log (debug)
    • Conditional Expressions
      • case
      • if-then-else
      • switch
    • Comments
    • Information about the case
    • Accessing the outcome instance
    • Information about documents
    • Recipes
  • Document XML (ADX)
    • ℹ️What is ADX?
    • ADX Elements
      • Body
      • Text
      • Image
      • Columns
      • Field
      • Checkbox
      • Table
      • Rect
      • Line
      • Space
      • KeepTogether
      • Template
      • Style
      • Page Number
      • QR Code
      • HR Code
    • Jinja Templating
      • Instances
      • Case Meta Information
      • Custom Translations
      • Functions
      • Jinja filters
    • Font support
  • API
    • ℹ️What is the Atfinity API?
    • Generate API Keys
    • API Documentation
    • Calling your APIs within Cases
    • External Data Sources (e.g. CRM)
  • Deploying
    • Deploying on-site
      • Kubernetes
      • Docker Compose
    • Management commands
    • Security Logging
    • LDAP User Backend
    • Single Sign On
  • Integrations
    • Avaloq
    • Worldcheck
  • Releases
    • Release Notes
      • Version 11.x
      • Version 10.x
      • Version 9.x and earlier
    • Release Schedule
Powered by GitBook
On this page
  • Requirements on your API
  • List Request
  • Retrieve Request
  • Errors

Was this helpful?

  1. API

External Data Sources (e.g. CRM)

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. The details part needs to be provided only if "Enable Detail Column" is set to "Yes". All three can be arbitrary strings.

{
    "data": [
        {
            "identifier": "10098",
            "name": "Thorben Croisé",
            "details": "Located in Zurich, Engineering Department"
        },
        {
            "identifier": "10099b",
            "name": "Alexander Balzer",
            "details": "Located in Zurich, Business Department"
        }
    ],
    "meta": {
        "pagination": {
            "count": 2,
            "page": 1,
            "pages": 1
        }
    }
}

Pagination

atfinity handles pagination of the returned instance list if necessary. At a time, usually 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

If you would not like to handle pagination, you could just always return less than page_size (usually 20) elements and fix page and pages to 1.

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.

{
    "data": {
        "cid": "1",
        "first_name": "Thorben",
        "last_name": "Croisé"
    }
}

Serialisation

  • Text, Number, Boolean: Default JSON format

  • Enum: Provide the key of the chosen value as a string, e.g. germany

  • Multi Enum: Provide the ticked possible values in an array (either json encoded or not), like this: ["inherited", "real_estate_sale"]

  • Unit, Unit per Item: Provide a dictionary with three entries like so: {"decimal_value": 1000, "item": null, "unit": "chf"}

Errors

Errors resulting from atfinity sending you values that you cannot or do not want to process should be handled mostly via HTTP Status Codes. atfinity will try to give users nice message for the following status codes:

Code
Description

401 UNAUTHORIZED

If the request from atfinity was not authorised for any reason, e.g. the provided API-KEY was invalid or the user in the FROM header is not allowed to make the request.

404 NOT FOUND

If the provided URL is not valid on your server. Do not use this if no results are returned in a search

5xx SERVER ERROR

Return this if your server encounters an error

PreviousCalling your APIs within CasesNextDeploying on-site

Last updated 1 year ago

Was this helpful?

Provided values need to be serialised in the same manner as values provided via our . For most types using the default JSON format serialisation is just enough, so e.g. {"firstname": "string"}, {"number_of_children": 2}, {"weight": 73.4} or {"has_been_screened": true}.

API