Retrieving entities and related data

info

To streamline the documentation, we've made a decision to disregard pagination. All examples will feature a fixed pagination set to 10. To obtain a comprehensive dataset, it's necessary to incorporate iteration through the pages in your implementation.

Retrieving entities

Retrieve a list of entities with related entity extensions. This request will return a list of Entity objects which contains basic information such as name, entity id, contact information etc. Please see OpenAPI specification for complete models.

Use offset and size for controlling pagination.

curl 
  --request GET \
  --url 'http://<endpoint>/rest/itxems/entity?getExtensions=true&offset=0&size=10' \
  --header 'ccntrl: xxx' \
  --header 'rcntrl: xxx' \
  --header 'tokenv2: xxx'

This is a simplified response that involves a private (entityType 1) entity named "John Doe". Additionally, there exists a single entity extension categorized as a customer of type (extType 10). The sequence number, commonly referred to as the customer number, is 187961. The most import property here is the primary id eeexId. This value will be used in further requests when retrieving activities.

tip

Store the eeexId in a list for batch retrieval of activities. This approach significantly decreases both the number of requests made and the overall duration of the export process.

HTTP response header totalfound will show the total amount of entities. Use this value to handle pagination.

[
    ...
    {
        "emenId": 3231573,
        "name1": "John",
        "name2": "Doe",
        "corporation": {...},
        "entityType": 1,
        "extensions": [
            {
                "eeexId": 3242113,
                "extType": 10,
                "seqNo": 187961,
                "extensionLinks": [...]
            }
        ],
        "numbers": [...]
    }
    ...    
]

Retrieving activities

Utilizing the outcome from the preceding step, we can now move forward with the retrieval of activities. Initially, you can fetch activities for 10 entity extensions per batch. Modify this number based on the volume of data and response times. Use the query parameter eeexId with a list of values separated by commas.

See Activity API and/or OpenAPI specification for more complete examples and a list of the available Activity Types.

Use limitFrom and limitTo for controlling pagination.

curl 
  --request GET \
  --url 'http://<endpoint>/rest/itxems/activities?getMembers=true&getFiles=true&getEmsTags=true&eeexId=xxx,xxx,xxx,xxx,xxx,xxx&limitFrom=0&limitTo=1000' \
  --header 'ccntrl: xxx' \
  --header 'rcntrl: xxx' \
  --header 'tokenv2: xxx'

HTTP response header itx-total-found will show the total amount of activities. Use this value to handle pagination.

Handling activity types

Certain activity types might necessitate additional handling before attaining the desired outcome. Here is an overview of the most prevalent scenarios you might encounter. Many of these are associated with ITX Tickets.

Emails

info

Email activities are identified by activity type 11.

Files

Within the activity, the coreFileReferences property holds a comprehensive list of all associated files. The purpose of each file is determined by its type property. cfreId is the primary identifier and should be stored for later use.
Below is a list outlining the various file types:

Type	Description
1	Inline image
2	Attachment
17	Email content

The email content itself is stored as a file and, as a result, needs to be fetched from our file server in a separate query.

curl 
  --request GET \
  --url 'http://<endpoint>/rest/itxems/emailcontent?eactId=<eact_id>' \
  --header 'ccntrl: xxx' \
  --header 'rcntrl: xxx' \
  --header 'tokenv2: xxx'

Core file reference type 1 and 2 must be retrieved from this

curl 
  --request GET \
  --url 'http://<endpoint>/rest/core/corefile?cfreId=<cfreId>' \
  --header 'ccntrl: xxx' \
  --header 'rcntrl: xxx' \
  --header 'tokenv2: xxx'

Activity links

Activities can be linked to each other by the links list. In this context we are only interested in links of type 13 (conversation link). Links are created from email to Conversation. A conversation in simply a group of emails from the same email thread.

The conversation is then linked to a case by link type 14 (case link). This link is missing for emails that does not belong to any case.