Obtaining the data model structure

A data model is typically made of several custom data tables gravitating around a profile table.

You can obtain the list of every custom table stored on an entity through the operation GET/entity/{e}/customTable

This method will yield the characteristics of every custom table linked to an entity, not to a particular profile table.

It will give you the following information for each table:

• its auto-generated technical id, which you can use to call and submit data
  

• its technical name, which you can use to call and submit data

• its display name, as it appears in ACTITO

• its category: 'read only' or 'read and write'

• the capabilities of the table: for additional information on this subject, see 'Understanding table Capabilities'

Obtaining the structure of a table

ACTITO gives you the possibility to define the content or your custom tables during their set-up, in order to adapt it to the specific needs of your activity.

After its creation in ACTITO, a custom table will be characterized by:

• A name "t", for example 'DemoDocTickets'

• An entity "e", which define the access rights. In this example : 'actito'

You can use the operation GET/entity/{e}/customTable to obtain the structure of this table.

This will allow you to understand how the structure of your table is transposed in the API. Thanks to this information, you will be able to more easily program POST or PUT methods to import data by correctly using every component of your custom table.

To do so, enter the name of the entity and of the table as parameters.

Example of response to this request: (Download this example)

This response is characterized by:

• Information about the type of table

• The list of attributes and their characteristics:

• "Field name" is the technical name of the field, which will be used to submit data

  • "type": The expected field type

  • "unique": Whether the attribute is unique or not

  • "required": Whether the attribute is mandatory or not

  • "description": The description of the attribute

• Technical information related to the table:

  • "primaryKey": This is the technical id of the table, which will always be an auto-generated technical attribute called "id". This technical attribute is used to identify each table record. You will never have to supply this field to submit data in your calls.

  • "businessKey": The business key of the table will act as the key to identify each record when submitting data in your calls. You always need to specify it.

  • "creationMoment" and "updateMoment": These indicate when the table was created and last updated. They will never have to be supplied in your calls.

Obtaining information on a specific record

It might prove very useful to obtain information related to records that already exist in your table. This will give you a practical example of the information expected for your data creation calls, especially when it comes to the characteristics of its components.

You can retrieve the details related to a record through the operation GET/entity/{e}/customTable/{t}/record/{r)

The specified parameters are as follows:

• the entity on which the custom table is stored

• the custom table containing the record: you can use either its technical name or its technical id

• the record to be retrieved: to do so, you will need to use the business key, which you could identify by obtaining the table structure. The auto-generated technical id cannot be used here.

  

Example of result for this request: (Download this example)

Please note that some technical attributes are automatically given in the answer. These attributes cannot be modified:

• "id": the auto-generated technical id

• "creationMoment": the creation date and time

• "updateMoment": the latest update date and time

Obtaining information on records based on a query

The operation GET/entity/{e}/customTable/{t}/record will allow you to obtain information on records on the basis of specific query parameters. For example, obtaining every ticket of a particular customer.

It is first necessary to specify the given entity and custom table. You can thereafter specify the following query parameters:

• "searchField": it is the technical name of the field on which the request will be based. This field must be indexed

• "searchValue": specify the value of the search field for which you want to obtain the records. This is a strict equality criterion.

• "sortedField": specify the field used to sort the obtained records. By default, it is the creation date. This field must be indexed

• "ascending": choose whether records must be displayed in ascending (true) or descending order (false)

• "number": choose the amount of records displayed (the maximum and default value is 200).

Example of a request based on a client number query: (Download this example)

Creating or updating a single record

One by one calls are preferred when the data are used to trigger a workflow or that they must be immediately synchronized with the database.

It is possible to create or update a custom record through the operation POST/entity{e}/customTable{t}/record

This method involves using a JSON code block in order to submit the data associated to the given profile. It is therefore advised to get to know the structure of the custom table beforehand, as explained at the top of this page.

The following parameters must be provided:

• The entity to which the table belongs:

• The name of the profile table to which the profile will be added, or the containing the profile to be updated

• "allowUpdate": This parameter allows you to choose whether you want to update a profile should it exist already. Indeed, POST is above all a creation method, but it can be used for updates

• "record": Characteristics of the given record, inserted as JSON code. The schema to the right of the Swagger technical documentation provides you with a model of the expected structure of this code. It is an array made of pairs of the properties technical names ("name") and the values that they must take ("value")

Example of request including the JSON code submitted in the "record" parameter: (Download this example)

The response will be the business key of the record that you just created or updated.

Creating or updating records in bulk

Populating custom tables in bulk is possible through the ACTITO APIs. They allow mass imports based on ZIP files containing table data. The mass import process for custom tables is exactly the same as for profiles mass imports.

For additional information about the expected format of the file, the result of the import or any error potentially encountered, we invite you to read the page on profiles mass imports.

The ACTITO public APIs allow you to import custom table records in bulk through the operation POST/entity/{e}/customTable{t}/import

This call can be used to submit a ZIP file containing a CSV file with the new table data.

The following parameters must be provided:

• the name of entity to which the profile table belongs

• the name of the custom table in which you want to import data

• the format of the CSVfile. 3 formats of CSV files are allowed:

  • COMMA_SEPARATED_VALUES (',' and line-break separator)

  • TAB_SEPARATED_VALUES (tab and line-break separator)

  • SEMI_COLON_SEPARATED_VALUES (';' and line-break separator)

• "charset": Encoding of the CSV file. Default value is UTF-8.

• the import mode. There are 3 possible values:

  • CREATE_ONLY: Load data only if they do not match any existing record in the table. In other words, the line value for the selected "headerKeyColumn" cannot exist in the database.

  • UPDATE_ONLY: Load data only if they match an existing profile in the table. It consists exclusively in updating existing profiles.

  • CREATE_UPDATE: Create a new profile if no matching profile is found in the database and update already existing profiles.

• "headerKeyColumn": Name of the column of the CSV file that will used as unique data identification key. It must correspond to a unique field from the table in which data will be loaded.

After launching your import, a code 200 will state that the import was successful. The response body will give you the technical id of the import.

This technical id can be used to obtain the status of the import and to identify potential errors, as explained in the page on mass profile imports.