API specification
Security
API version
GET /apps HTTP/1.1
X-Accept-Version: v1.3
The API is versioned. This documentation is only for the latest version.
* Mandatory fields.
Limit fields returned by API
GET /daxium-test/any_route?fields=id,created_at HTTP/1.1
Content-Type: application/json
{
"id": 123,
"created_at": 1461761418
}
All APIs that return objects can use query parameters in order to limit return fields.
Authorization
The authorization system is of type OAuth2.
GET /apps HTTP/1.1
Authorization: Bearer QjBBQjM5MEMtQUREOS00NzM0LUJBQUYtRDQ2NjlBRkE3Q0RBX2Zha2U
Each request must be authenticated with an access token (except for authorization requests).
It must be specified in the Authorization header.
For the first time, the tokens are retrievable with username and password. The following times, the tokens can be refreshed with a refresh token.
| Type of token | Description | time validity |
|---|---|---|
access_token |
To authenticate each request | 1 hour |
refresh_token |
To refresh access_token |
30 days |
Retrieve the tokens
The tokens are retrieved via a POST with the login of the user and the login of your application
POST /oauth/v2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
client_id=id_application&
client_secret=secret&
grant_type=password
username=utilsateur%40example.org&
password=mot_de_passe
Request
POST /oauth/v2/token
The parameters must be encoded in Form URL Encoded in the body of the query.
| Property | Type | Description |
|---|---|---|
| client_id * | string | OAuth2 login |
| client_secret * | string | OAuth2 secret key |
| grant_type * | string | Must be password |
| username * | user’s email address | |
| password * | user’s password |
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "QjBBQjM5MEMtQUREOS00NzM0LUJBQUYtRDQ2NjlBRkE3Q0RBX2Zha2U",
"refresh_token": "NDhFNjU5MkEtMTg0RC00REM4LTg2NjUtMEFEQjgyMjFDMUJGX2Zha2U",
"expires_in": 3600,
"token_type": "bearer",
"scope": "user"
}
Response
If the logins are correct, the API answers with a code 200 OK and the tokens.
The answer is encoded in JSON.
| Property | Type | Description |
|---|---|---|
| access_token | string | Access token to use in Authorization |
| refresh_token | string | Token to be kept for refreshing |
| expires_in | integer | Validity period (in seconds) of the access token |
| token_type | string | Always bearer, not used |
| scope | string | Not used |
Refresh the tokens
Refreshing tokens is similar to the first query, only the grant_type changes as well as the identification settings.
POST /oauth/v2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
client_id=id_application&
client_secret=secret&
grant_type=refresh_token
refresh_token=NDhFNjU5MkEtMTg0RC00REM4LTg2NjUtMEFEQjgyMjFDMUJGX2Zha2U
Request
POST /oauth/v2/token
| Property | Type | Description |
|---|---|---|
| client_id | string | Login of app OAuth2 |
| client_secret | string | OAuth2 secret key |
| grant_type | string | Must be refresh_token |
| refresh_token | Jeton de rafraîchissement |
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "MzBGMTFEN0MtQ0MzNy00OUZFLUFEN0ItMjBDRTZCNUZGQzNGX2Zha2U",
"refresh_token": "ODg0QkQ3MjMtQzkzMi00N0Y2LUFFMjAtNkE1MEFFOEM4MkQ1X2Zha2U",
"expires_in": 3600,
"token_type": "bearer",
"scope": "user"
}
Response
If the token is valid, the API will respond the same way as for the first-connection requests.
The 2 tokens (access_token and refresh_token) are changed and heir validity periods are extended.
Response is encoded in JSON format.
| Property | Type | Description |
|---|---|---|
| access_token | string | Access token to use in Authorization |
| refresh_token | string | Token to be kept for refreshing |
| expires_in | integer | Validity period (in seconds) of the access token |
| token_type | string | Always bearer, not used |
| scope | string | not user |
Business apps
Each user has access to one or more instances.
APIs on structures, submissions, lists and tasks require to be prefixed with the short name of the chosen vertical activity line (app_short).
Listing instances
he list of instances accessible by the user can be accessed via the /apps API.
GET /apps HTTP/1.1
Request
GET /apps
No parameters.
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"name": "Test",
"short": "daxium-test",
"description": "Test",
"settings": {...},
"android_map": true
},
{
"name": "Test 2",
"short": "daxium-test-2",
"description": "Test 2",
"settings": {...},
"android_map": false
}
]
Response
The response is always a JSON table with the list of available instances.
| Property | Type | Description |
|---|---|---|
| name | string | Visible name for the user of the instance |
| short | string | Short Name of the instance to be use as prefix |
| description | string | Description of the instance specified by the admin |
| settings | JSON | JSON object containing other parameters |
| android_map | bool | Indicates whether Android maps are activated or not |
Get a specific instance
Request
The /{app_short} API allows you to get a specific instance.
GET /daxium-test HTTP/1.1
Response
The response is a JSON object.
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "Test",
"short": "daxium-test",
"description": "Test",
"settings": {
"icon": "",
"tzdata": "Europe/Paris",
"admin_maxStructures": "0"
},
"android_map": true
}
| Property | Type | Description |
|---|---|---|
| name | string | Visible name for the user of the instance |
| short | string | Short Name of the instance to be use as prefix |
| description | string | Description of the instance specified by the admin |
| settings | JSON | JSON object containing other parameters |
| android_map | bool | Indicates whether Android maps are activated or not |
Files
Send a file
Allows you to send a file to link to a submission. Once the file is used in a submission, it is not possible to link it again to another submission.
Request
POST /daxium-test/files/upload HTTP/1.1
Content-Type: image/png
Content-Length: 8343
....
POST /{app_short}/files/upload
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"uuid": "3001aeaa-600c-4ab8-ad8a-2e14e4d54431",
"mime-type": "image\/png",
"size": 8343
}
| Property | Type | Description |
|---|---|---|
| uuid | UUID | file's identifier |
| mime-type | string | file's MIME type |
| size | inter | file's size in bytes |
Retrieving an error file
GET /daxium-test/files/download_errors/3001aeaa-600c-4ab8-ad8a-2e14e4d54431 HTTP/1.1
GET /{app_short}/files/download_errors/{worker_unique_id}
| Parameter | Type | Description |
|---|---|---|
| worker_unique_id | UUID | Unique worker identifier |
HTTP/1.1 200 OK
Content-Length: 8343
...
Forms
Attributes
{
"id": 490,
"version": 17,
"name": "Structure Test",
"updated_at": 1461153416,
"created_at": 1461153415,
"settings": {
"firstLevel": true,
"functionnalStatus": "list6"
},
"conditions": [],
"fields": [...],
"layout": {
"pages":[],
"fields":[]
},
"workflows":[],
"triggers":[],
}
All forms are identified by their ID id and their number of version version.
| Property | Type | Description |
|---|---|---|
| id | integer | form identifier |
| version | integer | number of version |
| name | string | displayed name |
| created_at | date | date of creation |
| updated_at | date | date of update |
| settings | object | JSON object containing different attributes |
| conditions | array | list of conditions |
| fields | array | list of fields |
| layout | object | list of pages and field positions |
| workflows | array | array containing the workflow (if present) |
| triggers | array | Workflow transitions customization (buttons) |
Fields
{
"fields": [
{
"enable": true,
"label": "Titre 8",
"name": "label8",
"position": 1,
"type": "label"
},
{
"barcodescan": false,
"enable": true,
"externalscan": false,
"format": "0.00",
"label": "Nombre",
"name": "number1",
"position": 2,
"prefill": true,
"readonly": false,
"required": false,
"searchable": false,
"type": "number"
},
{
"enable": true,
"label": "Checkbox",
"name": "boolean2",
"position": 3,
"prefill": false,
"readonly": false,
"required": false,
"searchable": false,
"type": "boolean"
}
]
}
The forms are composed of several fields of different types.
Common properties
| Property | Type | Description |
|---|---|---|
| name | string | System name of the field |
| label | integer | Displayed name |
| position | string | Position of the field |
| type | string | Type of the field |
| enable | boolean | activated or not |
| required | boolean | required or not |
| prefill | boolean | can be prefiled on mobile or not |
| readonly | boolean | can be updated on mobile or not |
Worflows
{
"workflows": [{
"created_at": 1584367529,
"updated_at": 1631095714,
"name": "Validation",
"states": [
{
"id": "21f7af30-457c-11e9-b210-d663bd873d93",
"name": "En cours de création",
"color": "#FF9800",
"end": false
},
{
"id": "21f7b502-457c-11e9-b210-d663bd873d93",
"name": "Fait",
"color": "#0A75E2",
"end": true
}
],
"transitions": [
{
"id": "8ccce2c6-457c-11e9-b210-d663bd873d93",
"from": "21f7af30-457c-11e9-b210-d663bd873d93",
"to": "21f7b502-457c-11e9-b210-d663bd873d93",
"label": "Réalisé"
}
],
"id": "8cccf176-457c-11e9-b210-d663bd873d93",
"start_state": "21f7af30-457c-11e9-b210-d663bd873d93"
}],
"triggers":[{
"id": "1b3f0cf1-9276-4448-9d07-99e9012c53b3",
"type": "change_state",
"transition_id": "8ccce2c6-457c-11e9-b210-d663bd873d93",
"color": "#FF9800",
"label": "Enregistrer"
}]
}
Structures with workflow have custom saving buttons which transition submissions from one state to another. Triggers allow to customize the way transitions appear in buttons. Submissions in a end state cannot be modified.
Retrieve all forms
Request
Returns all the available forms with a pagination
GET /daxium-test/structures?per_page=10&page=0 HTTP/1.1
GET /{app_short}/structures?per_page={per_page}&page={page}&updated_since={updated_since}
| Property | Type | Description |
|---|---|---|
| per_page | integer | Number of forms per par (by default 10) |
| page | integer | Page to return |
| updated_since | integer | Filter to return only the updated forms since the specified date (UNIX timestamp) |
HTTP/1.1 200 OK
Content-Type: application/json
{
"structures": [...],
"total_count": 14,
"total_pages": 2,
"next_page": 1,
"server_time": 1461761418,
"workflows": [],
"required": {
"linked_list_ids": [...],
"structure_ids": [...]
}
}
Response
| Property | Type | Description |
|---|---|---|
| structures | array | List of forms |
| total_count | integer | Total number of forms |
| total_pages | integer | Total number of pages |
| next_page | integer | Number of next page if several pages |
| server_time | date | Current date of server (UNIX timestamp) |
| required | object | JSON object listing all forms and lists linked to results |
| workflows | array | List of workflows used in these structures |
Retrieving a form
Request
Returns one form of the specified version if the attribute is informed or the last version.
GET /daxium-test/structures/100?version=1 HTTP/1.1
GET /{app_short}/structures/{id}?version={version}
| Property | Type | Description |
|---|---|---|
| id | integer | identifier |
| version | integer | version number |
HTTP/1.1 200 OK
Content-Type: application/json
{
"structure": [...],
"server_time": 1461761418
}
Response
| Property | Type | Description |
|---|---|---|
| structure | array | array containg a JSON object representing the form |
| server_time | Current date of the server (UNIX timestamp) |
Retrieving a file linked to a form
Request
Returns a file linked to a form, currently only the images of the Logo fields are recoverable with this API.
GET /daxium-test/structures/100/file/CD1A7F4F-9517-4D2E-A829-84EC4A2B9D20 HTTP/1.1
GET /{app_short}/structures/{id}/file/{file_id}
| Property | Type | Description |
|---|---|---|
| id | integer | identifier |
| file_id | string | file's identifier (UUID) |
Response
HTTP/1.1 200 OK
Content-Type: image/jpeg
...
Submissions
Format of the submissions
The submissions are composed of one or more values (items), in the form of key/values objects, as with for key the system name of the field.
Simple type
{
"stringExampleType": "topsyturn gittern fayles unmicrobic",
"numberExampleType": 90.0751,
"booleanExampleType": true,
"dateExampleType": 1426325213,
"durationExampleType": 42000,
"exampleTypePhone": "+33123456789"
}
| Field type | Value |
|---|---|
| text, email | Text |
| number | Number |
| boolean | Boolean |
| date | Number of seconds since 1970/01/01 (UNIX timestamp) |
| duration | Number of milliseconds |
| phone | Telephone number according to RFC 3966 standard |
location Type
{
"lat":44.339722,
"lng":1.210278,
"address": "Nantes, France"
}
| Property | Type | Description |
|---|---|---|
| lat | float | Latitude of point (WGS84) |
| lng | float | Longitude of point (WGS84) |
| address | string | Geocoded address |
image, signature, file Types
[
{
"id":"c42bafd1-e57a-42b6-83e4-452f5a56e426",
"name":"capture d'écran.png",
"mimeType": "image/png",
"extension": "png",
"size": 12451,
"comment": "Lorem ipsum dolor sit amet, consectetur adipisicing elit"
}
]
These types of values are incoporated in a table
| Property | Type | Description |
|---|---|---|
| id | UUID | unique identifier |
| name | string | file's name |
| mimeType | string | MIME Type |
| extension | string | file's extension |
| size | integer | Size of the file in bytes |
| comment | string | User’s comments (only for image type) |
list Type
[86709,94262,29124,65239,52046,84950,77323,41779]
The list type is an array of list IDs
relation Type
{
"submissions": [
{
"id":"bdc04cb2-85a2-44f2-978f-0184879341c8",
"count":5
},
{
"id":"f172aa21-21dd-4926-9430-6ef08cebc535",
"count": 3
}
]
}
The relations are put in an array of objects, with as key the identifier of the submission. For countable relations, another key should be added (count) in order to specify the quantity.
user type
[
{"id": 546},
{"id": 545}
]
Users are set with an array of objets in which the only important element is the id of the user.
Retrieving submissions of a form
Request
Returns all submissions linked to the form.
GET /daxium-test/submissions?structure_id=1 HTTP/1.1
GET /{app_short}/submissions?structure_id={id}&per_page={per_page}&page={page}&items_expanded=true
| Parameter | Type | Description |
|---|---|---|
| id | string | form identifier (required) |
| per_page | integer | Number of submissions per page |
| page | integer | Number of the requested page |
| updated_since | integer | Filters the results since the updated date (timestamp) |
| items_expanded | Boolean | Retrieve all lists info instead of just their ids |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"submissions": [
{
"created_at": 1466437149,
"updated_at": 1466437180,
"structure_id": 1,
"structure_version": 1,
"channels": [
"SUBMISSION-41/0820b488-3cee-4774-bb8f-3cca754ae8c3"
],
"data_created_at": 1495543307,
"data_updated_at": 1495543307,
"id": "09ad07b5-546a-4b7a-8970-a507525c71eb",
"items": {
"date8": 1466437174,
"number0": 68,
"string4": "Hello",
"boolean9": true
},
"submission_number": 1234,
"number_in_structure": 15,
"settings": [],
"assigned_user": {
"system_groups": [],
"groups": [],
"id": 80,
"email": "john@doe.com",
"first_name": "John",
"last_name": "Doe"
},
"subscribers": [],
"current_state": "c4bf97ba-4599-11e9-b210-d663bd873d93",
"last_updated_user_id": 44,
"latitude": -33.8634,
"longitude": 151.211
},
...
],
"total_count": 4,
"total_pages": 1,
"server_time": 1466694919
}
Properties
| Property | Type | Description |
|---|---|---|
| created_at | date | Creation date (UNIX timestamp) |
| updated_at | date | Update date (UNIX timestamp) |
| structure_id | integer | form identifier |
| structure_version | integer | form version |
| channels | array | Array of conditions matched for the submission |
| user_id | integer | Submission owner |
| data_created_at | date | creation date of data on the server |
| data_updated_at | date | update date of data on the server |
| id | UUID | identifier |
| items | JSON | JSON object with the system name of the field as the key |
| submission_number | integer | sequential number |
| number_in_structure | integer | sequential number |
| latitude | float | Latitude |
| longitude | float | Longitude |
| last_updated_user_id | integer | Id of the last user to modify the submission |
| subscribers | array | List of users subscribed to the submission |
| current_state | UUID | Id of the workflow state of the submission |
| assigned_user | JSON | Object describing the user assigned to this submission. |
Retrieving up to 100 submissions by their identifiers
Request
Returns the submissions corresponding to the sent identifiers.
POST /daxium-test/submissions/byids?items_expanded=false HTTP/1.1
Content-Type: application/json
{
"submission_ids": [
{
"id": "abe01c09-2cbe-412d-98b9-bfb73c4b9765",
"updated_since": 1551795386
},
{
"id": "f815082e-380b-4875-857f-2eee6bcdc90e"
},
{
"id": "771a82da-acfc-4447-8f2d-8c40626b332c",
"updated_since": 1551795386
}
]
}
POST /{app_short}/submissions/byids
| Parameter | Type | Description |
|---|---|---|
| id | Text | Submission identifier (required) |
| updated_since | Number | Filters the results since the updated date (timestamp, optional) |
| items_expanded | Boolean | Retrieve all lists info instead of just their ids |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"submissions": [
{
"created_at": 1580219902,
"updated_at": 1580219902,
"structure_id": 293,
"structure_version": 1,
"channels": [],
"user_id": 219,
"data_created_at": 1576492505,
"data_updated_at": 1576512945,
"id": "abe01c09-2cbe-412d-98b9-bfb73c4b9765",
"items": {
"string0": "rgreg",
"relation1": {
"submissions": [
{
"id": "3551cfdd-9353-4a15-94a9-0db7d9fe3d5f"
},
{
"id": "53589900-70a1-4b51-907a-36301072810b"
}
]
}
},
"settings": [],
"submission_number": 66679,
"number_in_structure": 4,
"subscribers": []
},
{
"created_at": 1579509524,
"updated_at": 1579509524,
"structure_id": 293,
"structure_version": 1,
"channels": [],
"user_id": 219,
"data_created_at": 1576492505,
"data_updated_at": 1576512945,
"id": "f815082e-380b-4875-857f-2eee6bcdc90e",
"items": {},
"settings": [],
"submission_number": 66675,
"number_in_structure": 3,
"subscribers": []
}
]
}
Properties
| Property | Type | Description |
|---|---|---|
| created_at | date | Creation date (UNIX timestamp) |
| updated_at | date | Update date (UNIX timestamp) |
| structure_id | integer | form identifier |
| structure_version | integer | form version |
| channels | array | Array of conditions matched for the submission |
| user_id | integer | Submission owner |
| data_created_at | date | creation date of data on the server |
| data_updated_at | date | update date of data on the server |
| id | UUID | identifier |
| items | JSON | JSON object with the system name of the field as the key |
| submission_number | integer | sequential number |
| number_in_structure | integer | sequential number |
| latitude | float | Latitude |
| longitude | float | Longitude |
| last_updated_user_id | integer | Id of the last user to modify the submission |
| subscribers | array | List of users subscribed to the submission |
| current_state | UUID | Id of the workflow state of the submission |
| assigned_user | JSON | Object describing the user assigned to this submission. |
Potential errors
If the number of submissions identifiers in payload is higher than the maximum allowed (100), an HTTP 400 response is received, with the message: "Too many id of submissions received. Max allowed is 100".
Searching for submissions of a form
Request
Returns all submissions linked to the form and corresponding to the search criteria.
POST /daxium-test/submissions/search?structure_id=1 HTTP/1.1
{
"field1": {
"value": "XXX",
"operator": "YYY"
},
"field2": {
"value": "XXX",
"operator": "YYY"
}
}
POST /{app_short}/submissions/search?structure_id={id}&per_page={per_page}&page={page}
| Parameter | Type | Description |
|---|---|---|
| field * | string | Valid system name of the field |
| value * | string | Researched value |
| operator * | string | Operator to use |
| Operator | Type | Description | Compatible fields |
|---|---|---|---|
| equal | string/number | Search an exact value | Text, number, boolean, date, email, phone |
| notequal | string/number | Search a different value | Text, number, boolean, date, email, phone |
| isNull | -- | Search a null value | All |
| isNotNull | -- | Search a non-null value | All |
| less | number | Search strictly inferior to | Number |
| greater | number | Search strictly superior to | Number |
| lesseq | number | Search inferior or equal to | Number |
| greatereq | number | Search superior or equal to | Number |
| contains | string | Search contains | Text, email, phone |
| notContains | string | Search does not contain | Text, email, phone |
| startWith | string | Search starting by | Text, email, phone |
| endWith | string | Search does not finish by | Text, email, phone |
| in | array | Check if one of the values provided is contained in the field | List, user, text |
| range | array with two values | Search between two boundaries | Number, date |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"submissions": [
{
"created_at": 1466437149,
"updated_at": 1466437180,
"structure_id": 1,
"structure_version": 1,
"channels": [
"SUBMISSION-41/0820b488-3cee-4774-bb8f-3cca754ae8c3"
],
"user_id": 23,
"data_created_at": 1495543307,
"data_updated_at": 1495543307,
"id": "09ad07b5-546a-4b7a-8970-a507525c71eb",
"items": {
"date8": 1466437174,
"number0": 68,
"string4": "Hello",
"boolean9": true
},
"settings": [],
"submission_number": 68693,
"number_in_structure": 2,
"subscribers": [],
"last_updated_user_id": 23
"latitude": -33.8634,
"longitude": 151.211
},
...
],
"total_count": 4,
"total_pages": 1,
"server_time": 1466694919
}
Searching for submissions of a form and by last user who modified them.
Request
Returns all submissions linked to the form and corresponding to the search criteria and by last user who modified them.
POST /daxium-test/submissions/search?structure_id=1&last_updated_user_id=23 HTTP/1.1
{
"field1": {
"value": "XXX",
"operator": "YYY"
},
"field2": {
"value": "XXX",
"operator": "YYY"
}
}
POST /{app_short}/submissions/search?structure_id={id}&last_updated_user_id={last_updated_user_id}&per_page={per_page}&page={page}
last_updated_user_id is an optional search criteria that is sent directly in the search URL (see example below). This parameter accepts an integer value which corresponds to a user id. Using this search criteria filters submissions whose last update was done by the user having the specified id.
| Parameter | Type | Description |
|---|---|---|
| field * | string | Valid system name of the field |
| value * | string | Researched value |
| operator * | string | Operator to use |
| Operator | Type | Description |
|---|---|---|
| equal | string/number | Search an exact value |
| isNull | -- | Search a null value |
| isNotNull | -- | Search a non-null value |
| notequal | string/number | Search a different value |
| less | number | Search strictly inferior to |
| greater | number | Search strictly superior to |
| lesseq | number | Search inferior or equal to |
| greatereq | number | Search superior or equal to |
| contains | string | Search contains |
| notContains | string | Search does not contain |
| startWith | string | Search starting by |
| endWith | string | Search does not finish by |
| in | array | Search contained in an array |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"submissions": [
{
"created_at": 1466437149,
"updated_at": 1466437180,
"structure_id": 1,
"structure_version": 1,
"channels": [
"SUBMISSION-41/0820b488-3cee-4774-bb8f-3cca754ae8c3"
],
"user_id": 23,
"data_created_at": 1495543307,
"data_updated_at": 1495543307,
"id": "09ad07b5-546a-4b7a-8970-a507525c71eb",
"items": {
"date8": 1466437174,
"number0": 68,
"string4": "Hello",
"boolean9": true
},
"settings": [],
"submission_number": 68693,
"number_in_structure": 2,
"subscribers": [],
"last_updated_user_id": 23
"latitude": -33.8634,
"longitude": 151.211
},
...
],
"total_count": 4,
"total_pages": 1,
"server_time": 1466694919
}
Récupérer les données de références
Retourne toutes les données de références, toute structure confondue, pour l'utilisateur connecté.
GET /daxium-test/submissions?reference=true HTTP/1.1
GET /{app_short}/submissions?reference=true&per_page={per_page}&page={page}
| Paramètre | Type | Description |
|---|---|---|
| per_page | Nombre | Nombre de fiches par page |
| page | Nombre | Numéro de la page demandée |
HTTP/1.1 200 OK
Content-Type: application/json
{
"submissions": [
{
"created_at": 1466437149,
"updated_at": 1466437149,
"structure_id": 1,
"structure_version": 1,
"channels": [
"SUBMISSION-41/0820b488-3cee-4774-bb8f-3cca754ae8c3"
],
"data_created_at": 1466437149,
"data_updated_at": 1466437149,
"id": "09ad07b5-546a-4b7a-8970-a507525c71eb",
"items": {
"date8": 1466437174,
"number0": 68,
"string4": "Hello",
"boolean9": true
},
"settings": [],
"latitude": -33.8634,
"longitude": 151.211
},
...
],
"total_count": 4,
"total_pages": 1,
"server_time": 1466694919
}
Récupérer une fiche
Récupère la fiche.
GET /daxium-test/submissions/dd795b8d-f235-4d87-b08f-5cd3566e6795 HTTP/1.1
GET /{app_short}/submissions/{id}
| Paramètre | Type | Description |
|---|---|---|
| id | UUID | Identifiant de la fiche |
HTTP/1.1 200 No Content
Content-Type: application/json
{
"id": "dd795b8d-f235-4d87-b08f-5cd3566e6795",
"structure_id": 1,
"structure_version": 3,
"items": {
...
},
...
}
Créer une fiche
Créer une nouvelle fiche.
POST /{app_short}/submissions
POST /daxium-test/submissions HTTP/1.1
Content-Type: application/json
{
"id": "dd795b8d-f235-4d87-b08f-5cd3566e6795",
"structure_id": 1,
"structure_version": 3,
"created_at": 1581430046,
"updated_at": 1581430046,
"items": {
...
},
...
}
Propriétés dans l'url
| Propriété | Type | Description | Exemple |
|---|---|---|---|
| partial | Booléen | Indique si la fiche doit être enregistrée partiellement et donc ne pas prendre en compte les permissions (champs editables ou requis). Si non indiqué, Les permissions doivent être respectées. | url?partial=true |
| Paramètre | Type | Description |
|---|---|---|
| id | UUID | Identifiant de la fiche (si non fourni, généré par le serveur) |
| structure_id * | integer | Identifiant du formulaire |
| structure_version * | integer | Version du formulaire |
| created_at | Timestamp | Timestamp de la date de création de la fiche. Si non précisé, on utilise la date du jour. |
| updated_at | Timestamp | Cernière modification de la fiche. Si non précisé, on utilise la date du jour. |
| items * | Dictionnaire | Dictionnaire avec pour clé le nom système du champ |
| substitute_user_id | integer | Optionnel. Spécifie l'id de l'utilisateur qui doit être considéré comme créateur de la fiche. Peut être différent de l'utilisateur connecté |
Créer plusieurs fiches
Requête
L'API /{app_short}/submissions/multiple permet de créer plusieurs fiches en une fois.
Il faut envoyer un tableau d'objets fiche dans la requête.
POST /daxium-test/submissions/multiple HTTP/1.1
Content-Type: application/json
[
{
"id": "dd795b8d-f235-4d87-b08f-5cd3566e6795",
"structure_id": 1,
"structure_version": 3,
"created_at": 1581430046,
"updated_at": 1581430046,
"items": {
...
}
},
{
"id": "09ad07b5-546a-4b7a-8970-a507525c71eb",
"structure_id": 2,
"structure_version": 1,
"created_at": 1581430046,
"updated_at": 1581430046,
"items": {
...
}
},
...
]
Réponse
La création multiple des fiches se fait de manière asynchrone.
Dans ce cadre, l'API de création retourne une URL qu'il est possible d'appeler pour avoir les détails de la création des fiches (voir doc API "Multiple fiches callback" ci-dessous).
HTTP/1.1 200 OK
Content-Type: application/json
{
"callbackUrl": "/{vm_short}/submissions/multiple/callback/062218c5-b471-4c23-908b-f514ee7c56f5"
}
Code erreur
Si le nombre des fiches créées dépasse la limite autorisée (100), l'erreur "Trop des fiches reçues" est retournée avec un code HTTP 400.
Si aucune fiche n'est envoyée, la réponse sera un code HTTP 400 avec une erreur indiquant qu'aucune fiche à créer n'a été reçue.
Mettre à jour une fiche
Mettre à jour une fiche par son identifiant. Le format d'envoi est identique à celui de création de fiche.
PUT /daxium-test/submissions/dd795b8d-f235-4d87-b08f-5cd3566e6795 HTTP/1.1
Content-Type: application/json
{
"id": "dd795b8d-f235-4d87-b08f-5cd3566e6795",
"structure_id": 1,
"structure_version": 3,
"created_at": 1581430046,
"updated_at": 1581430046,
"trigger_id": "88b6801f-0db6-4376-a6f2-aef18dda5e77",
"items": {
...
}
}
PUT /{app_short}/submissions/{id}
| Paramètre | Type | Description |
|---|---|---|
| id | UUID | Identifiant de la fiche |
| structure_id * | integer | Identifiant du formulaire |
| structure_version * | integer | Version du formulaire |
| created_at | Timestamp | Timestamp de la date de création de la fiche. Si non précisé, on utilise la date du jour. |
| updated_at | Timestamp | Cernière modification de la fiche. Si non précisé, on utilise la date du jour. |
| items * | Dictionnaire | Dictionnaire avec pour clé le nom système du champ |
| trigger_id | UUID | Dans le cas de fiche avec workflow, indiquer la transition à utiliser. Les transitions se retouvent ici |
| substitute_user_id | integer | Optionnel. Spécifie l'id de l'utilisateur qui doit être considéré comme nouveau propriétaire de la fiche. Peut être différent de l'utilisateur connecté |
Propriétés dans l'url
| Propriété | Type | Description | Exemple |
|---|---|---|---|
| partial | Booléen | Indique si la fiche doit être enregistrée partiellement et donc ne pas prendre en compte les permissions (champs editables ou requis). Si non indiqué, Les permissions doivent être respectées. | url?partial=true |
Réponse
HTTP/1.1 200 OK
Content-Type: application/json
{
"created_at": 1461835418,
"updated_at": 1461835418,
"structure_id": 1,
"structure_version": 3,
"id": "dd795b8d-f235-4d87-b08f-5cd3566e6795",
"items": {...},
"current_state": "37562ff0-05d9-11ea-8d71-362b9e155667",
...
}
Mettre à jour plusieurs fiches
Requête
L'API /{app_short}/submissions/multiple permet de mettre à jour plusieurs fiches en une fois.
Il faut envoyer un tableau d'objets fiche dans la requête.
PUT /daxium-test/submissions/multiple HTTP/1.1
Content-Type: application/json
[
{
"id": "dd795b8d-f235-4d87-b08f-5cd3566e6795",
"structure_id": 1,
"structure_version": 3,
"created_at": 1581430046,
"updated_at": 1581430046,
"items": {
...
}
},
{
"id": "09ad07b5-546a-4b7a-8970-a507525c71eb",
"structure_id": 2,
"structure_version": 1,
"items": {
...
}
},
...
]
Réponse
La mise à jour multiple de fiches se fait de manière asynchrone.
Dans ce cadre, l'API de mise à jour multiple retourne une URL qu'il est possible d'appeler pour avoir les détails de la mise à jour des fiches (voir doc API "Callback fiches multiples" ci-dessous).
HTTP/1.1 200 OK
Content-Type: application/json
{
"callbackUrl": "/{vm_short}/submissions/multiple/callback/062218c5-b471-4c23-908b-f514ee7c56f5"
}
Code erreur
Si le nombre d'fiches à mettre à jour dépasse la limite autorisée (100), l'erreur "Trop de fiches reçues" est retournée avec un code HTTP 400.
Si aucune fiche n'est envoyée, la réponse sera un code HTTP 400 avec une erreur indiquant qu'aucune fiche à mettre à jour n'a été reçue.
Supprimer une fiche
Supprime la fiche.
DELETE /daxium-test/submissions/dd795b8d-f235-4d87-b08f-5cd3566e6795 HTTP/1.1
DELETE /{app_short}/submissions/{id}
| Paramètre | Type | Description |
|---|---|---|
| id | UUID | Identifiant de la fiche |
HTTP/1.1 204 No Content
Envoyer un fichier
Permet d'envoyer un fichier afin de pouvoir le lier à une fiche. Une fois le fichier utilisé dans une fiche, il n'est pas possible de le lier à nouveau à une autre fiche.
POST /daxium-test/submissions/upload HTTP/1.1
Content-Type: image/png
Content-Length: 8343
....
POST /{app_short}/submissions/upload
HTTP/1.1 200 OK
Content-Type: application/json
{
"uuid": "3001aeaa-600c-4ab8-ad8a-2e14e4d54431",
"mime-type": "image\/png",
"size": 8343
}
Reponse
| Propriété | Type | Description |
|---|---|---|
| uuid | UUID | Identifiant du fichier |
| mime-type | Texte | Type MIME du fichier |
| size | Nombre | Taille en octets du fichier |
Envoyer un fichier avec son id et la fiche
Permet d'envoyer un fichier en précisant son id et celui de la fiche
POST /daxium-test/submissions/upload/{submissionId}/{fileId} HTTP/1.1
Content-Type: image/png
Content-Length: 8343
....
POST /{app_short}/submissions/upload/{submissionId}/{fileId}
| Paramètre | Type | Description |
|---|---|---|
| submissionId | UUID | Identifiant de la fiche |
| fileId | UUID | Identifiant du fichier |
HTTP/1.1 200 OK
Content-Type: application/json
{
"uuid": "3001aeaa-600c-4ab8-ad8a-2e14e4d54431",
"mime-type": "image\/png",
"size": 8343
}
Reponse
| Propriété | Type | Description |
|---|---|---|
| uuid | UUID | Identifiant du fichier |
| mime-type | Texte | Type MIME du fichier |
| size | Nombre | Taille en octets du fichier |
Récuperer un fichier
Retourne le fichier lié à la fiche.
GET /daxium-test/submissions/dd795b8d-f235-4d87-b08f-5cd3566e6795/file/3001aeaa-600c-4ab8-ad8a-2e14e4d54431 HTTP/1.1
GET /{app_short}/submissions/{id}/file/{file_id}
| Paramètre | Type | Description |
|---|---|---|
| id | UUID | Identifiant de la fiche |
| file_id | UUID | Identifiant du fichier |
HTTP/1.1 200 OK
Content-Length: 8343
...
Callback fiches multiples
Requête
L'API /{app_short}/submissions/multiple/callback/{callback_id} permet de récupérer le statut d'une création ou mise à jour multiple de fiches.
L'URL de cette API, et donc l'ID "callback_id" sont fournis par les services de création et mise à jour de fiches multiples (voir ci-avant).
GET /daxium-test/submissions/multiple/callback/bd49010b-fea7-4cd4-9ff2-c99679827ab9 HTTP/1.1
Réponse
La réponse contient tous les détails qui concernent la création ou la mise à jour des fiches. Voir exemple ci-contre.
HTTP/1.1 200 OK
Content-Type: application/json
{
"callbackDetails": {
"status": "Finished with errors",
"nbRecordsTodo": 2,
"nbRecordsDone": 2,
"nbSuccess": 1,
"nbErrors": 1,
"success": [
"dd795b8d-f235-4d87-b08f-5cd3566e6795"
],
"errors": [
{
"09ad07b5-546a-4b7a-8970-a507525c71eb": [
"Unknown structure id"
]
}
]
}
}
| Propriété | type | Description | Valeurs potentielles |
|---|---|---|---|
| status | string | Statut de la demande asynchrone | Voir les statuts possibles ci-après |
| nbRecordsTodo | int | Nombre des fiches à traiter | 1, 25, 72, .. |
| nbRecordsDone | int | Nombre des fiches déjà traitées sur le nombre total | 1, 25, 72, .. |
| nbSuccess | int | Nombre des fiches traitées sans erreur | 1, 25, 72, .. |
| nbErrors | int | Nombre des fiches n'ayant pas pu être traitées à cause d'erreurs | 1, 25, 72, .. |
| success | object | JSON représentant la liste des fiches traitées sans erreur au format "<submission identifier>" |
voir exemple ci-contre |
| errors | object | JSON représentant la liste des fiches rencontrées au format {"<submission identifier>" => ["<error_1>", "<error_2>", ...]} |
voir exemple ci-contre |
Statuts possibles
| Status | Description |
|---|---|
| Planned | La demande de création ou mise à jour a bien été reçue et est planifiée, mais pas encore lancée |
| Running | La demande de création ou mise à jour est en cours |
| Finished | La demande de création ou mise à jour s'est terminée sans erreur |
| Finished with errors | La demande de création ou mise à jour s'est terminé mais des erreurs ont été relevées |
| Failed | Le process a rencontré une erreur technique et n'a pas pu se dérouler normalement |
| In timeout | Le process a rencontré une erreur technique et n'a pas pu se dérouler normalement |
Custom applications
Properties
{
"app": {
"created_at": 1495463112,
"updated_at": 1495463128,
"id": 3,
"name": "My custom app",
"banner": {...},
"splash": {...},
"menus": [...],
"screens": [...],
"settings": [...],
"groups": [...],
"widget_spacing": 1,
"button_type": "standard",
"label_overlay": true,
"grant_all": true
},
"total_count": 1,
"total_pages": 1,
"server_time": 1497950623,
"required": {
"files_uuid": [
"73fc5a59-d9b7-492b-a666-21205031aa74",
"b3efec90-c7cf-4989-b118-e70d7c21ed5e"
]
}
}
Custom apps are identified by an id attribute. It is possible to retrieve several custom applications for a business app.
| Property | Type | Description |
|---|---|---|
| created_at | date | Date of creation (UNIX timestamp) |
| updated_at | date | Date of update (UNIX timestamp) |
| id | integer | Identifier |
| name | string | Name |
| banner | JSON | Banner |
| splash | JSON | Splash screen |
| menus | array | Array of items composing a menu |
| screens | array | Array of screens composing the app |
| settings | array | Array of parameters |
| groups | array | Arrays of group ids with access to the app |
| widget_spacing | integer | relative space between buttons. 0 corresponding to flat mode, 1 to standard configuration |
| button_type | string | buttons type: standard (font-awesome icons), mix (image icons), full (backgrouns images) |
| label_overlay | boolean | Displays a benner under buttons label |
| grant_all | boolean | Accessible to all users or not |
Splash
{
"splash": {
"created_at": 1495463112,
"updated_at": 1497950593,
"active": true,
"image": "73fc5a59-d9b7-492b-a666-21205031aa74",
"color": "#5084C4",
"aspect": "fit"
}
}
| Property | Type | Description |
|---|---|---|
| created_at | date | Date of creation (UNIX timestamp) |
| updated_at | date | Date of modification (UNIX timestamp) |
| active | boolen | Indicates whether the splash screen should be displayed when launching the app |
| image | string | image identifier |
| color | string | background color (hexadecimal) |
| aspect | string | fit to the available splace, fill the available splace |
Menu
{
"menus": [
{
"created_at": 1495463112,
"updated_at": 1495463120,
"index": 0,
"target": "daxium-air://app/home",
"label": {
"en": "Home",
"es": "Inicio",
"fr": "Accueil"
},
"icon": {
"type": "font-awesome",
"value": "fa-home"
}
},
{
"created_at": 1495463112,
"updated_at": 1495463120,
"index": 1,
"target": "daxium-air://app/new_submission",
"label": {
"en": "New submission",
"es": "Nuevo registro",
"fr": "Nouvelle fiche"
},
"icon": {
"type": "font-awesome",
"value": "fa-pencil"
}
},
...
]
}
| Property | Type | Description |
|---|---|---|
| created_at | date | Date of creation (UNIX timestamp) |
| updated_at | date | Date of update (unix timestamp) |
| index | integer | Display order position of the different menu entries |
| target | string | Action to launch during interaction with this menu entry |
| label | JSON | Displayed text in the menu. JSON Object containing each local (identified by the key) |
| icon | JSON | Displayed icon in the menu. Icon object containing one type and one value. Only font Awesome is supported for the moment. |
Screens
A custom app is made up with different configurable screens according to the attributes below :
{
"screens": [
{
"created_at": 1495463112,
"updated_at": 1495463120,
"name": "daxium_home",
"pages": [...]
}
]
}
| Property | Type | Description |
|---|---|---|
| created_at | date | Date of creation (UNIX timestamp) |
| updated_at | date | Date of update (UNIX timestamp) |
| name | string | Name identifying the screen |
| pages | array | Array of pages in the screen |
Pages
A screen is made of one or numbers of pages.
{
"pages": [
{
"created_at": 1495463112,
"updated_at": 1495463120,
"system_name": "home_page",
"title": {
"fr": "Page d'accueil",
"en": "Home page",
"es": "Inicio"
},
"side_menu": true,
"widgets": [...],
"layout": {...}
}
]
}
| Property | Type | Description |
|---|---|---|
| created_at | date | Date of creation (UNIX timestamp) |
| updated_at | date | Date of update (UNIX timestamp) |
| system_name | string | System name |
| title | string | Title. JSON object with each translation (identified by their keys) |
| side_menu | boolean | Indicates whether the left menu should be displayed on the page or not |
| widgets | array | Array of widgets displayed in the page |
| layout | array | Type of layout chosen for this page |
Layout
{
"layout": [
{
"x": 0,
"y": 0,
"width": 2,
"height": 1
},
{
"x": 1,
"y": 0,
"width": 1,
"height": 1
},
{
"x": 1,
"y": 1,
"width": 1,
"height": 1
},
{
"x": 2,
"y": 0,
"width": 2,
"height": 1
}
]
}
| Property | Type | Description |
|---|---|---|
| x | string | X coordinate of the widget in the layout |
| y | string | Y coordinate of the widget in the layout |
| width | string | Relative length |
| height | string | Relative height |
Widgets
A widget is materialized by a button on a page?
{
"widgets": [
{
"created_at": 1495463112,
"updated_at": 1495463120,
"type": "button",
"index": 0,
"label": {
"en": "New submission",
"es": "Nuevo registro",
"fr": "Nouvelle fiche"
},
"color": "#2ecc71",
"target": "daxium-air://app/new_submission",
"icon": {
"type": "font-awesome",
"value": "fa-pencil"
}
},
{
"created_at": 1495463112,
"updated_at": 1495463120,
"type": "button",
"index": 1,
"label": {
"en": "My submissions",
"es": "Mis registros",
"fr": "Mes fiches"
},
"color": "#f39c12",
"target": "daxium-air://app/my_submission",
"icon": {
"type": "font-awesome",
"value": "fa-tags"
}
},
...
]
}
| Property | Type | Description |
|---|---|---|
| created_at | date | Date of creation (UNIX timestamp) |
| updated_at | date | Date of modification (UNIX timestamp) |
| type | string | Button type |
| index | integer | Position in the order in which the different widgets are displayed on the page |
| label | JSON | Displayed text on the widget. JSON object containing each translation (identified by their key) |
| color | string | background color of the widget (hexadecimal) |
| target | string | Action to launch during interaction with this menu entry |
| icon | JSON | Type and value of the icon represented by a JSON object |
Standard
{
"icon": {
"type": "font-awesome",
"value": "fa-tags"
}
}
Custom icon
{
"icon": {
"type": "image",
"value": "49cb243f-d0f2-4aec-901e-89a8281e7a0"
}
}
Background image
{
"icon": [],
"background": "f0af27de-fbfb-41f8-948d-57612ca05e91"
}
Retrieving all custom apps
Returns all custom apps in a short format for the given line of business. if any custom app is configured, returns the default application in full format.
Request
GET /daxium-test/customapps HTTP/1.1
GET /{app_short}/customapps
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"apps": [
{
"created_at": 1497952660,
"updated_at": 1497952711,
"id": 13,
"name": "Image buttons"
},
{
"created_at": 1497952574,
"updated_at": 1497952653,
"id": 12,
"name": "Custom icons"
}
],
"total_count": 2,
"total_pages": 1,
"server_time": 1497953611
}
| Property | type | Description |
|---|---|---|
| apps | array | Array of all avaible custom apps with their id, name and create/update date |
| total_count | integer | Number of retrieved results |
| total_pages | integer | Number of total of result pages |
| server_time | date | Current date of the server (UNIX timestamp) |
Retrieving a custom app
Returns a custom app according to an ID
Request
GET /daxium-test/customapps/10 HTTP/1.1
GET /{app_short}/customapps/{app_id}
| Parameter | Type | Description |
|---|---|---|
| app_id | integer | Custom app identifier |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"app": {
"created_at": 1495463112,
"updated_at": 1495463128,
"id": 3,
"name": "My custom app",
"banner": {...},
"splash": {...},
"menus": [...],
"screens": [...],
"settings": [...],
"groups": [...],
"widget_spacing": 1,
"button_type": "standard",
"label_overlay": true,
"grant_all": true
},
"total_count": 1,
"total_pages": 1,
"server_time": 1497950623,
"required": {
"files_uuid": [
"73fc5a59-d9b7-492b-a666-21205031aa74",
"b3efec90-c7cf-4989-b118-e70d7c21ed5e"
]
}
}
| Property | Type | Description |
|---|---|---|
| app | JSON | The custom app |
| total_count | integer | Number of retrieved results |
| total_pages | integer | Number of total of result pages |
| server_time | date | Current date of the server (UNIX timestamp) |
| required | JSON | Array of files identifier linked to the app |
Retrieving a custom app file
Returns a custom app file.
Request
GET /daxium-test/customapps/10/file/f0af27de-fbfb-41f8-948d-57612ca05e91 HTTP/1.1
GET /{app_short}/customapps/{app_id}/file/{file_uuid}
| Parameter | Type | Description |
|---|---|---|
| file_uuid | UUID | identifier of the file to retrieve |
Response
HTTP/1.1 200 OK
Lists
The lists have a tree structure, each list item can contain one or more sub-items
List item :
{
"id": 19620,
"root_id": 19618,
"parent_id": 19618,
"created_at": 1449840918,
"updated_at": 1450789764,
"name": "Chat",
"has_image": true,
"level": 1,
"position": 2,
"external_id": "cat",
"functionnal_status_color": "#8e44ad",
"url": "https:\/\/fr.wikipedia.org\/wiki\/Chat"
}
| Property | Type | Description |
|---|---|---|
| id | integer | List identifier |
| root_id | integer | Root node identifier |
| parent_id | integer | Parent identifier |
| created_at | date | Date of creation (UNIX timestamp) |
| updated_at | date | Date of update (UNIX timestamp) |
| deleted_at | date | Date of removal (UNIX timestamp) |
| name | string | Displayed name |
| has_image | boolean | Indicates if the list includes an image |
| level | integer | Depth level, 0 as known as the root node |
| position | integer | Position of the list by its depth level |
| external_id | string | External identifier |
| url | string | URL |
| functionnal_status_color | string | Color of the list (hexadecimal) |
Retrieve all lists
Returns all existing
Request
GET /daxium-test/lists HTTP/1.1
GET /{app_short}/lists?per_page={per_page}&page={page}
| Paramètre | Type | Description |
|---|---|---|
| per_page | Number | The number of elements per page (10 by default, maximum 1000) |
| page | Number | Page to be returned |
| updated_since | Date | Filter to return only lists updated after the specified date |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"lists": [
{
"root_id": 5,
"name": "testList",
"created_at": 1528374700,
"list_last_updated": 1601471925
},
...
],
"total_count": 14,
"total_pages": 2,
"next_page": 1,
"server_time": 1461761418
}
| Paramètre | Type | Description |
|---|---|---|
| lists | [Objects] | Array of lists |
| total_count | Number | Total number of lists |
| total_pages | Number | Total number of pages to display |
| next_page | Number | Index of next page (if any) |
| server_time | Date | Server date |
| list_last_updated | Date | Date of the last update of an element in this list |
Retrieve a list
Returns the list and all its sub-items within a pagination
Request
GET /daxium-test/lists/19618?per_page=100&page=0 HTTP/1.1
GET /{app_short}/lists/{list_id}?per_page={per_page}&page={page}&updated_since={updated_since}
| Parameter | Type | Description |
|---|---|---|
| per_page | integer | The number of elements per page (10 by default, maximum 1000) |
| page | integer | Page to be returned |
| updated_since | date | Filter to return only lists updated after the specified date |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"lists": [...],
"total_count": 14,
"total_pages": 2,
"next_page": 1,
"server_time": 1461761418
}
| Property | Type | Description |
|---|---|---|
| lists | [List] | List of sorted items |
| total_count | integer | Total number of lists |
| next_page | integer | Number of the next page if several pages |
| server_time | date | Current date of the server (UNIX timestamp) |
Create a list
Creates a list sub-items hierarchically with the items attribute.
Request
POST /daxium-test/lists HTTP/1.1
Content-Type: application/json
{
"name": "Région - France",
"external_id": "fr",
"items":[
{
"name": "Pays de la loire",
"external_id": "fr.pdl",
"items":
[
{
"name": "Loire-Atlantique",
"external_id": "fr.pdl.44"
},
{
"name": "Vendée",
"external_id": "fr.pdl.88"
}
]
}
]
}
POST /{app_short}/lists
| Parameter | Type | Description |
|---|---|---|
| name * | string | Name of the list (required) |
| external_id | string | Identifiant Externe |
| items | [List] | List of sub-items |
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"created_at": 1579510167,
"updated_at": 1579510167,
"has_image": false,
"id": 66310,
"name": "Région - France",
"position": 0,
"level": 0
}
| Property | Type | Description |
|---|---|---|
| id | integer | identifier of the created root node |
Edit items of the list
Edits the name of one or more items of a list according to its ID id.
Request
PATCH /daxium-test/lists/35384 HTTP/1.1
Content-Type: application/json
[
{
"id": 35385,
"name": "Grand Ouest"
}
]
PATCH /{app_short}/lists/{root_id}
| Parameter | Type | Description |
|---|---|---|
| root_id | integer | root node identifier |
A list of changes must be sent as a list of JSON objects, with the ID of the element to be modified.
Response
| Paramètre | Type | Description |
|---|---|---|
| lists | [liste] | Table of modified list items |
HTTP/1.1 200 OK
Content-Type: application/json
{
"lists": [
{
"created_at": 1579512259,
"updated_at": 1579512402,
"parent_id": 35384,
"root_id": 35384,
"has_image": false,
"id": 35385,
"name": "Grand Ouest",
"position": 1,
"level": 1,
"external_id": "fr.pdl"
}
],
"total_count": 1,
"total_pages": 1,
"server_time": 1579512402
}
Delete a list
Removes completely a list with all the elements, must be a root node.
Request
DELETE /daxium-test/lists/19618 HTTP/1.1
DELETE /{app_short}/lists/{root_id}
| Paramter | Type | Description |
|---|---|---|
| root_id | integer | root node identifier |
Response
HTTP/1.1 204 No Content
Delete an item from a list
Removes the list, including all the sub-items.
Request
DELETE /daxium-test/lists/19618/19624 HTTP/1.1
DELETE /{app_short}/lists/{root_id}/{list_id}
| Parameter | Type | Description |
|---|---|---|
| root_id | integer | root node identifier |
| list_id | integer | list identifier |
Response
HTTP/1.1 204 No Content
Retrieve an image linked to a list
Returns the image linked to the image, only if attribute has_image is true.
Request
GET /daxium-test/lists/19618/19620/image HTTP/1.1
GET /{app_short}/lists/{root_id}/{list_id}/image
| Parameter | Type | Description |
|---|---|---|
| root_id | integer | Root node identifier |
| list_id | integer | List identifier |
Response
HTTP/1.1 200 OK
Content-Type: image/jpeg
...
Retrieve lists’ IDs and accessSets that have been modified
Returns the ID list of all the lists and accessSet that have been modified and require updating on an external system.
Request
POST /daxium-test/lists/updated HTTP/1.1
Content-Type: application/json
{
"list_states": [
{
"list_id": 123456,
"list_updated_since": 1579887264,
"access_set_updated_since": 1579887264
},
...
]
}
POST /{app_short}/lists/updated
| Parameter | Type | Description |
|---|---|---|
| list_id | integer | List identifier |
| list_updated_since | date | Filter to detect if the list has been updated since the specified date (UNIX timestamp) |
| access_set_updated_since | date | Filter to detect if the accessSet has been updated since the specified date (UNIX timestamp) |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"lists_to_update": [
XXX,
YYY
],
"lists_with_access_set": [
XXX,
YYY
], "access_set_to_update": [
XXX,
YYY
]
}
| Property | Type | Description |
|---|---|---|
| lists_to_update | [ids] | Array of IDs of edited lists |
| lists_with_access_set | [ids] | Array of IDs of lists with accessSet |
| access_set_to_update | [ids] | Array of IDs of edited accessSet |
Retrieve IDs of selectable items
Returns the list of all selectable IDs for a given list (list of nodes allowed by accessSet).
Request
GET /daxium-test/lists/19618/selectables HTTP/1.1
GET /{app_short}/lists/{list_id}/selectables
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"selectable_ids": [
XXX,
YYY
],
"server_time": 1469461670
}
| Property | Type | Description |
|---|---|---|
| selectable_ids | [ids] | Array of selectable IDs for the user |
| server_time | date | Current date of the server (UNIX timestamp) |
Update a list
Updates an item of the list
Request
PUT /daxium-test/lists/19618/19619 HTTP/1.1
Content-Type: application/json
{
"name": "xxxxx",
"latitude": "xxxx",
"longitude": "xxxx",
"external_id": "xxx",
"functionnal_status_color": "xxx",
"url": "xxx"
}
PUT /{app_short}/lists/{root_id}/{list_id}
| Parameter | Type | Description |
|---|---|---|
| name | string | Name of the list |
| latitude | float | Latitude |
| longitude | float | Longitude |
| external_id | string | External ID |
| functionnal_status_color | string | Color of the item (hexadecimal) |
| url | string | Url of the item |
Response
HTTP/1.1 200 OK
Content-Type: application/json
[]
Add numerous items
Add several items in a list
Request
PATCH /daxium-test/lists/19618/19619 HTTP/1.1
Content-Type: application/json
[
{
"name": "xxxxx",
"latitude": "xxxx",
"longitude": "xxxx",
"external_id": "xxx",
"functionnal_status_color": "xxx",
"url": "xxx"
}
]
PATCH /{app_short}/lists/{root_id}/{parent_id}
| Property | Type | Description |
|---|---|---|
| liste | [List] | Array of lists |
Response
HTTP/1.1 200 OK
Content-Type: application/json
[]
Retrieve all sub-items of a node
Retrieve all children directly from a node
Request
GET /daxium-test/lists/19618/child/19619 HTTP/1.1
GET /{app_short}/lists/{root_id}/child/{parent_id}
Response
| Property | Type | Description |
|---|---|---|
| list | [list] | Array of lists |
| total_count | integer | Total number of items |
| total_pages | integer | Total number of pages |
| server_time | integer | Current date of the server (UNIX timestamp) |
HTTP/1.1 200 OK
Content-Type: application/json
{
"lists": [
...
],
"total_count": XX,
"total_pages": YY,
"server_time": 1479742896
}
Recherche
Search a list in relation to its external_id
Request
POST /daxium-test/lists/13339835/search HTTP/1.1
{
"external_id": "0012"
}
| Parameter | Type | Description |
|---|---|---|
| external_id | string | Searched external id |
POST /{app_short}/lists/{root_id}/search
Response
| Property | Type | Description |
|---|---|---|
| list | [list] | Array of lists |
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": 13339835,
"name": "Créé",
"external_id": "0012",
"functionnalStatusColor": "blue",
"level": 1,
"position": 1,
"parent_id": 13339834,
"root_id": 13339834,
"vm_id": 204,
"url": ""
}
]
Change position of a node
Changes the position of one node relative to another
Request
PUT /daxium-test/lists/13897339/13899509/after/13899530 HTTP/1.1
PUT /{app_short}/lists/{root_id}/{node_to_move_id}/{direction}/{node_position_id}
Possible directions :
child: move the node to move as fist child of the reference node;before: position the node just before the reference node (within the same parent node);after: position the node just after the reference node (within same parent node);
| Parameter | Type | Description |
|---|---|---|
| root_id | integer | Root ID of the list to be modified |
| node_to_move_id | integer | ID of the node to move |
| direction | string | Where to move the node relative to another |
| node_position_id | integer | ID of the reference node for the placement |
Response
HTTP/1.1 200 OK No Content
Importing a list in csv
Import a list via a CSV file
Request
POST /daxium-test/lists/import HTTP/1.1
Content-Type: application/json
{
"list_id": 12345,
"separator": ";",
"mode": "DIFF",
"encoding": "UTF-8",
"file_id": "dd795b8d-f235-4d87-b08f-5cd3566e6795"
}
| Parameter | Type | Description |
|---|---|---|
| list_id * | Integer | List identifier |
| file_id * | UUID | File identifier |
| separator | Text | Any character to indicate the separation between 2 columns. ";" by default |
| mode | Text | Indicates the import mode. Accepted values "APPEND", "DIFF". |
| encoding | Text | Indicates the encoding of the file. Accepted values : "UTF-8", "WINDOWS-1252", "WINDOWS-1256". "UTF-8" par défaut. |
file_id comes from the API call "Send a file"
Response
The list import is done asynchronously.
In this case, the API returns a URL that can be called to get the details of the list import (see API doc "List callback" below).
HTTP/1.1 200 OK
Content-Type: application/json
{
"callbackUrl": "/{vm_short}/lists/callback/062218c5-b471-4c23-908b-f514ee7c56f5"
}
Error code
| Message | Code |
|---|---|
| file_id is missing | 400 |
| file_id must be an uuid | 400 |
| Bad encoding | 400 |
| File not found | 400 |
| A technical error occurred while executing submission import job | 400 |
List callback
Request
The /{app_short}/lists/callback/{callback_id} API allows to retrieve the status of some list APIs :
lists/import
The URL of this API, and thus the "callback_id" are provided by the above APIs.
GET /daxium-test/lists/callback/bd49010b-fea7-4cd4-9ff2-c99679827ab9 HTTP/1.1
Response
The answer contains all the details that concern the above APIs. See example on the right. In the case of the import API only the status is currently returned
The response contains all the details regarding the creation or update of multiple submissions. Please see example beside.
HTTP/1.1 200 OK
Content-Type: application/json
{
"callbackDetails": {
"status": "Finished with errors",
"nbRecordsTodo": 1,
"nbRecordsDone": 1,
"nbSuccess": 0,
"nbErrors": 0,
"success": [],
"errors": [
"error xxx",
"error yyy"
]
}
}
| Property | type | Description | Potential values |
|---|---|---|---|
| status | string | Current status of the query | Please check the possible status below |
| nbRecordsTodo | int | Number of list elements to process. For now will be 1 | 0, 1 |
| nbRecordsDone | int | Number of list elements already processed. For now will be 0 while job is running and 1 once it's done. | 0, 1 |
| nbSuccess | int | Number of list elements processed succesfully | 0 |
| nbErrors | int | Number of list elements which process failed because of error(s) | 0 |
| success | object | Empty array | |
| errors | object | JSON containing the list of errors that occured by submission. Format: {"<list id>" => ["<error_1>", "<error_2>", ...]} |
Please check example on right side |
Possible status
| Status | Description |
|---|---|
| Planned | The treatment has been sent to the job queuing system and is waiting for an available worker to start |
| Running | The treatment is in progress |
| Finished | The treatment was completed without error |
| Finished with errors | Processing was completed but errors were found |
| Failed | The process encountered a technical error and could not run normally |
List Access Set
The list access sets enables you to restrict some elements from the lists
Retrieve all available access sets
Returns the list of all defined access sets
Request
GET /daxium-test/list/accessset HTTP/1.1
GET /{app_short}/list/accessset
HTTP/1.1 200 OK
Content-Type: application/json
{
"listaccesssets": [
{
"id": "672da115-72f2-4448-8e97-dfc080467e96",
"name": "bride",
"users": [
"143"
],
"groups": [],
"root_id": 189457,
"lists": [
189542,
189557,
189555
]
}
],
"total_count": 1,
"total_pages": 1,
"server_time": 1469542453
}
Response
| Property | Type | Description |
|---|---|---|
| listaccesssets | [las] | List of access sets elements |
| total_count | integer | Total number of lists |
| next_page | integer | Number of next page if multiple pages |
| server_time | date | Current date of server (UNIX timestamp) |
Retrieve all access sets for a list and a user
Returns the list all defined authorizations for a list and a particular user
Request
GET /daxium-test/list/42/accessset/user/42 HTTP/1.1
GET /{app_short}/list/{list_id}/accessset/user/{user_id}
| Parameter | Type | Description |
|---|---|---|
| list_id | integer | list identifier |
| user_id | integer | user identifier |
HTTP/1.1 200 OK
Content-Type: application/json
[
"672da115-72f2-4448-8e97-dfc080467e96"
]
Response
| Property | Type | Description |
|---|---|---|
| listaccesssets | [las] | array of list of access sets ids |
Retrieve access set information
Returns all access set information
Request
GET /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96 HTTP/1.1
GET /{app_short}/list/{list_id}/accessset/{list_access_set_id}
| Parameter | Type | Description |
|---|---|---|
| list_access_set_id | Uuid | list access set identifier |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "672da115-72f2-4448-8e97-dfc080467e96",
"name": "bride",
"users": [
{
"id": 143,
"email": "v.ramona@daxium.com",
"active": true,
"first_name": "Vincent",
"last_name": "Ramona",
"last_login_at": "2015-12-11T16:11:53+0100",
"settings": {
"locale": "fr"
}
}
],
"groups": [],
"root_id": {
"has_image": false,
"id": 189457,
"name": "Fournitures",
"position": 210,
"level": 0
},
"lists": [
{
"created_at": "2016-07-21T10:34:00+0200",
"updated_at": "2016-07-21T10:34:09+0200",
"vertical_metier_id": 27,
"vertical_metier": {
"created_at": "2016-02-18T17:27:18+0100",
"updated_at": "2016-02-18T17:27:22+0100",
"id": 27,
"name": "frob",
"short": "pictbase-frob",
"description": "frob",
"active": true,
"settings": []
},
"parent_id": 189541,
"root_id": 189457,
"has_image": false,
"id": 189542,
"name": "de réduction",
"position": 1,
"level": 2,
"list_access_set": [
{
"created_at": "2016-07-26T14:01:36+0200",
"updated_at": "2016-07-26T14:01:36+0200",
"vertical_metier_id": 27,
"vertical_metier": {
"created_at": "2016-02-18T17:27:18+0100",
"updated_at": "2016-02-18T17:27:22+0100",
"id": 27,
"name": "frob",
"short": "pictbase-frob",
"description": "frob",
"active": true,
"settings": []
}
}
]
},
{
"created_at": "2016-07-21T10:34:00+0200",
"updated_at": "2016-07-21T10:34:10+0200",
"vertical_metier_id": 27,
"vertical_metier": {
"created_at": "2016-02-18T17:27:18+0100",
"updated_at": "2016-02-18T17:27:22+0100",
"id": 27,
"name": "frob",
"short": "pictbase-frob",
"description": "frob",
"active": true,
"settings": []
},
"parent_id": 189541,
"root_id": 189457,
"has_image": false,
"id": 189557,
"name": "vissée",
"position": 3,
"level": 2,
"list_access_set": [
{
"created_at": "2016-07-26T14:01:36+0200",
"updated_at": "2016-07-26T14:01:36+0200",
"vertical_metier_id": 27,
"vertical_metier": {
"created_at": "2016-02-18T17:27:18+0100",
"updated_at": "2016-02-18T17:27:22+0100",
"id": 27,
"name": "frob",
"short": "pictbase-frob",
"description": "frob",
"active": true,
"settings": []
}
}
]
},
{
"created_at": "2016-07-21T10:34:00+0200",
"updated_at": "2016-07-21T10:34:09+0200",
"vertical_metier_id": 27,
"vertical_metier": {
"created_at": "2016-02-18T17:27:18+0100",
"updated_at": "2016-02-18T17:27:22+0100",
"id": 27,
"name": "frob",
"short": "pictbase-frob",
"description": "frob",
"active": true,
"settings": []
},
"parent_id": 189553,
"root_id": 189457,
"has_image": false,
"id": 189555,
"name": "Test2",
"position": 2,
"level": 5,
"list_access_set": [
{
"created_at": "2016-07-26T14:02:38+0200",
"updated_at": "2016-07-26T14:21:17+0200",
"vertical_metier_id": 27,
"vertical_metier": {
"created_at": "2016-02-18T17:27:18+0100",
"updated_at": "2016-02-18T17:27:22+0100",
"id": 27,
"name": "frob",
"short": "pictbase-frob",
"description": "frob",
"active": true,
"settings": []
}
}
]
}
]
}
| Property | Type | Description |
|---|---|---|
| listaccessset | [las] | access authorization |
Retrieve an access set type info
Returns the list corresponding to the required entity for access sets
Request
| GET /{app_short}/list/{list_id}/accessset/{list_access_set_id}/[users | groups | lists] |
| | | |
| Parameter | Type | Description |
| --------------------- | ------- | ----------- |
| users/groups/lists | string | requested entity |
GET /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96/users HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": 143,
"email": "v.ramona@daxium.com",
"active": true,
"first_name": "Vincent",
"last_name": "Ramona",
"last_login_at": "2015-12-11T16:11:53+0100",
"settings": {
"locale": "fr"
}
}
]
GET /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96/groups HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
[]
GET /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96/lists HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"created_at": "2016-07-21T10:34:00+0200",
"updated_at": "2016-07-21T10:34:09+0200",
"vertical_metier_id": 27,
"vertical_metier": {
"created_at": "2016-02-18T17:27:18+0100",
"updated_at": "2016-02-18T17:27:22+0100",
"id": 27,
"name": "frob",
"short": "pictbase-frob",
"description": "frob",
"active": true,
"settings": []
},
"parent_id": 189541,
"root_id": 189457,
"has_image": false,
"id": 189542,
"name": "de réduction",
"position": 1,
"level": 2,
"list_access_set": [
{
"created_at": "2016-07-26T14:01:36+0200",
"updated_at": "2016-07-26T14:01:36+0200",
"vertical_metier_id": 27,
"vertical_metier": {
"created_at": "2016-02-18T17:27:18+0100",
"updated_at": "2016-02-18T17:27:22+0100",
"id": 27,
"name": "frob",
"short": "pictbase-frob",
"description": "frob",
"active": true,
"settings": []
}
}
]
},
{
"created_at": "2016-07-21T10:34:00+0200",
"updated_at": "2016-07-21T10:34:10+0200",
"vertical_metier_id": 27,
"vertical_metier": {
"created_at": "2016-02-18T17:27:18+0100",
"updated_at": "2016-02-18T17:27:22+0100",
"id": 27,
"name": "frob",
"short": "pictbase-frob",
"description": "frob",
"active": true,
"settings": []
},
"parent_id": 189541,
"root_id": 189457,
"has_image": false,
"id": 189557,
"name": "vissée",
"position": 3,
"level": 2,
"list_access_set": [
{
"created_at": "2016-07-26T14:01:36+0200",
"updated_at": "2016-07-26T14:01:36+0200",
"vertical_metier_id": 27,
"vertical_metier": {
"created_at": "2016-02-18T17:27:18+0100",
"updated_at": "2016-02-18T17:27:22+0100",
"id": 27,
"name": "frob",
"short": "pictbase-frob",
"description": "frob",
"active": true,
"settings": []
}
}
]
},
{
"created_at": "2016-07-21T10:34:00+0200",
"updated_at": "2016-07-21T10:34:09+0200",
"vertical_metier_id": 27,
"vertical_metier": {
"created_at": "2016-02-18T17:27:18+0100",
"updated_at": "2016-02-18T17:27:22+0100",
"id": 27,
"name": "frob",
"short": "pictbase-frob",
"description": "frob",
"active": true,
"settings": []
},
"parent_id": 189553,
"root_id": 189457,
"has_image": false,
"id": 189555,
"name": "Test2",
"position": 2,
"level": 5,
"list_access_set": [
{
"created_at": "2016-07-26T14:02:38+0200",
"updated_at": "2016-07-26T14:21:17+0200",
"vertical_metier_id": 27,
"vertical_metier": {
"created_at": "2016-02-18T17:27:18+0100",
"updated_at": "2016-02-18T17:27:22+0100",
"id": 27,
"name": "frob",
"short": "pictbase-frob",
"description": "frob",
"active": true,
"settings": []
}
}
]
}
]
Response
| Property | Type | Description |
|---|---|---|
| users/groups/lists | [array] | List of users/groups/lists of access sets |
Delete an access set
Delete an access set
Request
DELETE /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96 HTTP/1.1
DELETE /{app_short}/list/{list_id}/accessset/{list_access_set_id}
| Parameter | Type | Description |
|---|---|---|
| list_access_set_id | Uuid | list identifier |
Response
HTTP/1.1 204 No Content
Delete an access set entity
Delete an access set entity
Request
DELETE /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96/users/42 HTTP/1.1
DELETE /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96/groups/42 HTTP/1.1
DELETE /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96/lists/42 HTTP/1.1
DELETE /{app_short}/list/{list_id}/accessset/{list_access_set_id}/{entity}/{entity_id}
| Parameter | Type | Description |
|---|---|---|
| list_access_set_id | Uuid | list identifier |
| entity | [users/groups/lists] | type of entity |
| entity_id | Uuid | entity identifier |
Response
HTTP/1.1 204 No Content
Create an access set
Create an access set
Request
POST /daxium-test/list/42/accessset HTTP/1.1
Content-Type: application/json
{
'name': 'bli',
'groups': [],
'users': [],
'lists': []
}
POST /{app_short}/list/{root_id}/accessset
| Parameter | Type | Description |
|---|---|---|
| root_id | Entier | id of the list racine |
| Parameter | Type | Description |
| ---------- | ---------- | ----------- |
| name * | string | Name of the access set |
| groups | [ids] | Array of group ids |
| users | [ids] | Array of user ids |
| lists | [ids] | Array of list ids |
Response
| Property | Type | Description |
|---|---|---|
| list_access_set_id | Uuid | access set identifier |
HTTP/1.1 200 OK
{
"id": "672da115-72f2-4448-8e97-dfc080467e96"
}
Editing an access set
Editing access set (use PUT to add and DELETE to remove some elements)
Request
PUT /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96/users/42 HTTP/1.1
PUT /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96/groups/42 HTTP/1.1
PUT /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96/lists/42 HTTP/1.1
DELETE /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96/users/42 HTTP/1.1
DELETE /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96/groups/42 HTTP/1.1
DELETE /daxium-test/list/42/accessset/672da115-72f2-4448-8e97-dfc080467e96/lists/42 HTTP/1.1
PUT /{app_short}/list/{list_id}/accessset/{list_access_set_id}/{entity}/{entity_id}
DELETE /{app_short}/list/{list_id}/accessset/{list_access_set_id}/{entity}/{entity_id}
| Parameter | Type | Description |
|---|---|---|
| list_access_set_id | Uuid | access set identifier |
| entity | [users/groups/lists] | type of element |
| entity_id | integer | element identifier |
Response
HTTP/1.1 200 OK
Generating internal dependence
Generates all dependency of access sets. To be launched once all changes are done. Launched automatically every 5 minutes
Resquest
POST /daxium-test/list/42/accessset/generate/672da115-72f2-4448-8e97-dfc080467e96 HTTP/1.1
POST /{app_short}/list/{list_id}/accessset/{list_access_set_id}/generate
| Parameter | Type | Description |
|---|---|---|
| list_access_set_id | Uuid | access set identifier |
Response
HTTP/1.1 200 OK
Tasks
Retrieving tasks
Request
Enables to retrieve tasks by user, structure and dates.
GET /{app_short}/tasks
GET /daxium-test/tasks HTTP/1.1
Content-Type: application/json
| Parameter | Type | Description |
|---|---|---|
| structure_id | string | Form identifier |
| greater_start_date | date | Starting date greater or equal to |
| lower_start_date | date | Starting date lower or equal to |
| greater_due_date | date | Due date greater or equal to |
| lower_due_date | date | Due date lower or equal to |
| user_id | integer | ID of the user |
| me | Tasks of the connected user | |
| page | integer | Number of the page |
| per_page | integer | Number of tasks per page |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"tasks": [
{
"id": "6e7ae869-af80-4d31-aa2b-483ebd0f9078",
"created_at": 1472828179,
"updated_at": 1472828179,
"start_date": 1473890400,
"due_date": 1473899400,
"submission": {
"structure_id": 353,
"structure_version": 4,
"id": "1f8e89f4-ba40-461e-a8b0-f4a88d29dfb3",
"items": {
...
},
"previous_items": [],
"settings": []
},
"user_id": 418,
"duration": 3600,
"delay_before": 300,
"delay_after": 300
},
...
],
"total_count": 4,
"total_pages": 1,
"server_time": 1466694919
}
Properties
| Property | Type | Description |
|---|---|---|
| id | UUID | task identifier |
| start_date | date | Starting date of the task (UNIX timestamp) |
| due_date | date | Due date of the task (UNIX timestamp) |
| duration | integer | Duration of the task in seconds |
| delay_before | integer | Indicative display delay in seconds before the task begins |
| delay_after | integer | Indicative display delay in seconds after task completion time |
| created_at | date | Creation date (UNIX timestamp) |
| updated_at | date | Update date (UNIX timestamp) |
| submission | Submission | Submission for the task |
| user_id | integer | ID of the assigned user or null |
Creation of a simple task
Request
Creation of a simple task
POST /{app_short}/tasks
POST /{app_short}/tasks HTTP/1.1
Content-Type: application/json
{
"start_date": 1473890400,
"due_date": 1473899400,
"submission_model_id": "xxxx-xxxx-xxxx-xxxx",
"user_id": 418,
"duration": 3600,
"delay_before": 300,
"delay_after": 300
}
OR
{
"start_date": 1473890400,
"due_date": 1473899400,
"submissions": [
"xxxx-xxxx-xxxx-xxxx", "xxxx-xxxx-xxxx-xxxx"
],
"user_id": 418,
"duration": 3600,
"delay_before": 300,
"delay_after": 300
}
Properties
| Property | Type | Description |
|---|---|---|
| id | UUID | task identifier |
| start_date | date | starting date of the task (UNIX timestamp) |
| due_date | date | due date of the task (UNIX timestamp) |
| duration | integer | duration of the task in seconds |
| delay_before | integer | indicative display delay before the task starts |
| delay_after | integer | indicative display after due hour of the task |
| submission_model_id | UUID | ID of a submission model |
| submissions | array | array of submissions IDS |
| user_id | integer or Null | ID of the user |
Creating a Recurring Task
The properties are the same as a simple task, however, the due_date property is not required.
POST /{app_short}/tasks HTTP/1.1
Content-Type: application/json
{
"start_date": 1473890400,
...,
"delay_after": 300,
"recurrency": {
"type": "daily",
"days": {
"mon": {
"start": "00:00",
"end": 1800
},
"tue": {
"start": "02:00",
"end": 1800
},
"wed": {
"start": "04:00",
"end": 1800
},
"thu": {
"start": "06:00",
"end": 1800
},
"fri": {
"start": "08:00",
"end": 1800
},
"sat": {
"start": "10:00",
"end": 1800
},
"sun": {
"start": "12:00",
"end": 1800
}
},
"end": {
"type": "occurrence",
"value": 5
},
"interval": 1
}
}
Properties
| Proprerty | Type | Description |
|---|---|---|
| id | UUID | task identifier |
| start_date | date | starting date of the task (UNIX timestamp) |
| duration | integer | duration of the task in seconds |
| delay_before | integer | indicative display delay before the task starts |
| delay_after | integer | indicative display after due hour of the task |
| submission_model_id | UUID | ID of a submission model |
| submissions | array | array of submissions IDS |
| user_id | Nombre or Null | user identifier |
| recurrency | Recurrency | See below |
Daily recurrence
| Property | Type | Description |
|---|---|---|
| type | string | set as "daily |
| interval | integer | Interval between each task, minimum 1 |
| days | JSON | Days of Week (first 3 letters of days in English) with start properties for the start time and theend property for the duration of the task in seconds |
| end | JSON | An object with a type property that can have as an instance or date value, and avalue property that has a date value in the case of a date type, a number in the case of an instance type |
POST /{app_short}/tasks HTTP/1.1
Content-Type: application/json
{
"start_date": 1473890400,
...,
"delay_after": 300,
"recurrency": {
"type": "weekly",
"days": {
"wed": {
"start": "04:00",
"end": 1800
},
"thu": {
"start": "06:00",
"end": 1800
}
},
"end": {
"type": "date",
"value": 1475890400
},
"interval": 1
}
}
Weekly recurrence
The properties are the same as the daily recurrence, but every day of the days property is not required.
Publipostages
Publipostage templates by structure
Request
Get list of publipostage templates available for the structure
GET /daxium-test/report_templates?structure=1213 HTTP/1.1
GET /{app_short}/report_templates?structure={structure_id}
| Property | Type | Description |
|---|---|---|
| structure_id | integer | Structure id [0-9]+ |
HTTP/1.1 200 OK
Content-Type: application/json
{
"templates": [
{
"id": 68,
"name": "Gestion PHMR.xlsx",
"listingMode": false,
"templateEngine": "xlsxaspose"
},
{
"id": 62,
"name": "Gestion PHMR2.docx",
"listingMode": false,
"templateEngine": "docxopenxml"
},
{
"id": 60,
"name": "test 53 en.docx",
"listingMode": false,
"templateEngine": "docxopenxml"
},
{
"id": 59,
"name": "Gestion PHMR.docx",
"listingMode": true,
"templateEngine": "docxopenxml"
}
],
"total_count": 4,
"total_pages": 1,
"server_time": 1487251538
}
Response
Json array with available pp templates info for the structure
| Property | Type | Description |
|---|---|---|
| id | integer | Template id |
| name | string | Template name |
| listingMode | boolean | Template listing mode flag |
| templateEngine | string | Template generation engine |
Publipostage templates by submission
Request
Get list of publipostage templates available for the submission
GET /daxium-test/report_templates?submission=9641083e-4235-427d-90a8-4d46207d46c7 HTTP/1.1
GET /{app_short}/report_templates?submission{submission_id}
| Property | Type | Description |
|---|---|---|
| submission_id | GUID | Submission id [0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12} |
HTTP/1.1 200 OK
Content-Type: application/json
{
"templates": [
{
"id": 68,
"name": "Gestion PHMR.xlsx",
"listingMode": false,
"templateEngine": "xlsxaspose"
},
{
"id": 62,
"name": "Gestion PHMR2.docx",
"listingMode": false,
"templateEngine": "docxopenxml"
},
{
"id": 60,
"name": "test 53 en.docx",
"listingMode": false,
"templateEngine": "docxopenxml"
},
{
"id": 59,
"name": "Gestion PHMR.docx",
"listingMode": true,
"templateEngine": "docxopenxml"
}
],
"total_count": 4,
"total_pages": 1,
"server_time": 1487251538
}
Response
Json array with available pp templates info for the submission
| Property | Type | Description |
|---|---|---|
| id | Number | Template id |
| name | Text | Template name |
| listingMode | Boolean | Template listing mode flag |
| templateEngine | Text | Template generation engine |
Publipostage info
Request
Get publipostage info by id
GET /daxium-test/reports/1846 HTTP/1.1
GET /{app_short}/reports/{report_id}
| Property | Type | Description |
|---|---|---|
| report_id | Number | Publipostage id [0-9]+ |
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1846,
"status": "finished",
"original_document": {
"file_uuid": "17e66387-276d-49c5-a5dc-d609f7e1543d",
"file_name": "133357-Gestion PHMR.docx"
},
"pdf_document": {
"file_uuid": "",
"file_name": ""
},
"errorMessage": ""
}
Response
Json object with the publipostage info
| Property | Type | Description |
|---|---|---|
| id | Number | Publipostage id |
| status | Text | Publipostage status |
| file_uuid | UUID | Publipostage generated result file UUID |
| file_name | Text | Publipostage generated result file name |
| errorMessage | Text | Error message, if any |
Publipostages by submission
Request
Get list of all publipostages by submission
GET /daxium-test/reports?submission=9641083e-4235-427d-90a8-4d46207d46c7 HTTP/1.1
GET /{app_short}/reports?submission={submission_id}&per_page={per_page}&page={page}&updated_since={updated_since}
| Property | Type | Description |
|---|---|---|
| submission * | UUID | Submission id [0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12} |
| per_page | Number | Number of publipostage per page (default value 10, maximum 1000). Optional. |
| page | Number | Page number to get. Optional. |
| updated_since | Date | Date filter to get publipostage updated after date provided. Optional. |
HTTP/1.1 200 OK
Content-Type: application/json
{
"reports": [
{
"id": 375,
"status": "error",
"original_document": {
"file_uuid": "",
"file_name": ""
},
"pdf_document": {
"file_uuid": "",
"file_name": ""
},
"errorMessage": "(-300) The remote server returned an error: (404) Not Found."
},
{
"id": 1890,
"status": "finished",
"original_document": {
"file_uuid": "17e66387-276d-49c5-a5dc-d609f7e1543d",
"file_name": "133357-Gestion PHMR.docx"
},
"pdf_document": {
"file_uuid": "",
"file_name": ""
}
}
],
"total_count": 2,
"total_pages": 1,
"server_time": 1487251538
}
Response
Json object with publipostages info for submission
| Property | Type | Description |
|---|---|---|
| reports | [Array] | Array of publipostage objects info |
| total_count | Number | Total number of publipostage |
| next_page | Number | Next page number (if any) |
| server_time | Date | Current server time |
Publipostage result file by uuid
Request
Get publipostage generated file by uuid
GET /daxium-test/reports/1861/results/78669621-5cc9-40cd-a961-988da6102384 HTTP/1.1
GET /{app_short}/reports/{report_id}/results/{file_uuid}
| Property | Type | Description |
|---|---|---|
| report_id | Number | Publipostage id [0-9]+ |
| file_uuid | UUID | Publipostage generated result file UUID [0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12} |
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="Gestion PHMR.xlsx";, attachment; filename="Gestion PHMR.xlsx";
Response
Return publipostage generated file
Start publipostage
Request
Start publipostage generation for the submission
POST /{app_short}/reports
POST /daxium-test/reports HTTP/1.1
Content-Type: application/json
{
"template_id": 62,
"submission_id": "9641083e-4235-427d-90a8-4d46207d46c7",
"api_callback": "http://your.endpoint.com/report_callback/{publipostage_id}"
}
| Property | Type | Description |
|---|---|---|
| template_id * | Number | Template id. Mandatory. |
| submission_id * | String | Submission id. Mandatory. |
| api_callback * | String | Url to call when publipostgae generation done. Mandatory. |
| header_name | String | Header name to be set while callback. Optional. |
| header_value | String | Header value to be use while callback. Optional. |
| join_format | string | Output format of the generated report. Valid values are : |
original : original format of the template (.doc, .xlsx, ...) |
||
pdf : PDF format |
||
original,pdf : two reports generated : original format and PDF |
api_callback will be called after report generation using PUT method. {publipostage_id} in url will be replaced by corresponding pp id value. Aditional header with header_name and header_value will be sent (if were defined).
HTTP/1.1 200 OK
Content-Type: application/json
{
"report_id": 1887
}
Response
Json with newly created publipostage id
| Property | Type | Description |
|---|---|---|
| report_id | Number | Created publipostage id |
Context
Subscribe to a submission
Request
Add submission to user context
POST /{app_short}/contexts/3163a2b2-fb3b-4802-9920-4c271abe519b HTTP/1.1
or
POST /{app_short}/contexts/3163a2b2-fb3b-4802-9920-4c271abe519b HTTP/1.1
Content-Type: application/json
{
"user_id": 62
}
POST /daxium-test/contexts/{submission_id}
| Parameter | Type | Description |
|---|---|---|
| submission_id | GUID | Submission id [0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12} |
If json content is sent while POST, submission will be added to the user context with provided user_id. Otherwise submission will be added to the current user context.
HTTP/1.1 204 OK
Response
Empty page with 204 response code.
Unsubscribe from a submission
Request
Remove submission from current user context
DELETE /daxium-test/contexts/9641083e-4235-427d-90a8-4d46207d46c7 HTTP/1.1
DELETE /{app_short}/contexts/{submission_id}
| Parameter | Type | Description |
|---|---|---|
| submission_id | GUID | Submission id [0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12} |
HTTP/1.1 204 OK
Response
Empty page with 204 response code.
Unsubscribe all users from a submission
Request
Remove submission from all users contexts
DELETE /daxium-test/contexts/9641083e-4235-427d-90a8-4d46207d46c7/allusers HTTP/1.1
DELETE /{app_short}/contexts/{submission_id}/allusers
| Parameter | Type | Description |
|---|---|---|
| submission_id | GUID | Submission id [0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12} |
HTTP/1.1 204 OK
Response
Empty page with 204 response code.
Subscriptions
A user to log in must have a web and/or mobile license. These licenses are attached to a subscription.
List all subscription of an account
Request
list of subscriptions linked to an account is available with the API /subscriptions.
GET /subscriptions HTTP/1.1
Response
The response is a JSON array with the list of all available subscriptions.
HTTP/1.1 200 OK
Content-Type: application/json
{
"subscriptions": [
{
"start": 1483225200,
"end": 1672527599,
"users_max": {
"web": 9999,
"mobile": 9999
},
"id": "d4ea01d1-b18a-434d-90e4-1b939d7dba65",
"name": "infinite",
"sequence": 1,
"active": true
},
{
"start": 1514761200,
"end": 1546297199,
"users_max": {
"web": 5,
"mobile": 10
},
"id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"name": "Renouvellement Daxium 2018",
"sequence": 2,
"active": true
}
],
"total_count": 2,
"total_pages": 1,
"server_time": 1496328911
}
| Propriété | Type | Description |
|---|---|---|
| start | int | Start date |
| end | int | End date |
| users_max | JSON | number max of mobile and web users |
| id | UUID | identifier |
| name | string | displayed name |
| sequence | int | sequential number |
| active | bool | status |
Groups
Retrieve all application groups from a business app
Request
List of groups linked to a business app is available with:
GET /{app_short}/groups
GET /daxium-test/groups HTTP/1.1
Response
The response is a JSON objet with an array of all available groups.
HTTP/1.1 200 OK
Content-Type: application/json
{
"groups": [
{
"is_system": false,
"id": 6,
"name": "Group A",
"description": "Group A",
"user_ids":[219, 230],
"structure_ids":[408]
},
{
"is_system": false,
"id": 7,
"name": "Group B",
"description": "Group B",
"user_ids":[219],
"structure_ids":[406, 789]
}
],
"total_count": 2,
"total_pages": 1,
"server_time": 1496329957
}
| Property | Type | Description |
|---|---|---|
| is_system | bool | system group or not |
| id | int | identifier |
| name | string | displayed name |
| description | string | description added by the administrator |
Create a group
Create a new group.
POST /{app_short}/group
POST /daxium-test/group HTTP/1.1
Content-Type: application/json
{
"name": "My group",
"description": "Group description",
"user_ids":[219, 230],
"structure_ids":[408]
}
| Parameter | Type | Description |
|---|---|---|
| name * | String | Group name |
| description * | String | Group description |
| user_ids | array(int) | Array of identifiers corresponding to users in the group |
| structure_ids | array(int) | Array of identifiers corresponding to structures in the group |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"is_system": false,
"id": 100,
"name": "My group",
"description": "Group description",
"user_ids": [
219, 230
],
"structure_ids": [
408
]
}
Update a group
Request
Update an existing group.
PUT /{app_short}/group/{group_id}
PUT /daxium-test/group/100 HTTP/1.1
{
"name": "My modified group",
"description": "Group description",
"user_ids":[123],
"structure_ids": [123]
}
| Parameter | Type | Description |
|---|---|---|
| name * | String | Group name |
| description * | String | Group description |
| user_ids | array(int) | Array of identifiers corresponding to users in the group |
| structure_ids | array(int) | Array of identifiers corresponding to structures in the group |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"is_system": false,
"id": 100,
"name": "My modified group",
"description": "Group description",
"user_ids": [
123
],
"structure_ids": [
123
]
}
Users
Properties of the users
| Propriété | Type | Description |
|---|---|---|
| username * | string | email address of the user (username). Must be unique |
| active | bool | status (active / inactive) |
| firstName | string | First name of the user |
| lastName | string | Last name of the user |
| locale | string | Language (locale) of the user ("en" or "fr") |
| subscription_id | string | UUID of the subscription the user is linked to. The list of available subscriptions IDs can be retrieved by calling the API /subscriptions |
| system_groups * | array | array of system group IDs (int). 1 for administrator, 2 mobile access, 3 for web access. |
| groups | array | array of group IDs (int). The list of available groups can be retrieved using this API /{app_short]/groups} |
| id | int | [Ony in Response / GET] Unique ID of the user (generated by the system) |
| settings | JSON object | [Ony in Response / GET] JSON object containting some user settings, such as language (locale) |
| plainPassword | JSON object | [Ony in Request / POST / PUT / PATCH] The keys "first" and "second" are mandatory (see examples in below APIs) and their values must be identical. Rules to respect: 1 uppercased char minimum, 1 lowedcased minimum, 1 integer minimum, 8 chars minimum |
| force_login_password | int | [Only for companies using SSO authentication] 0 to deactivate, 1 to activate. In case of SSO connexion availability on the company, can force the user to use Daxium login/password authentication instead of the SSO connexion if configured as so. |
| ssoProvider | int | [Only for companies using SSO authentication] unique "id" of the SSO provider that the user should use as authentication method. Password is no more necessary in this case. This id is communcated by Daxium's team |
Exemple de requête
Check on the right side.
# EXAMPLE OF A REQUEST OF CREATION / MODIFICATION (POST/PUT/PATCH)
HTTP/1.1 200 OK
Content-Type: application/json
...
{
"subscription_id": "ce3759fc-fad9-4a70-2822-4eaf1bba925f",
"system_groups": [
1,
2
],
"groups": [
253,
254
],
"email": "user@daxium.com",
"active": true,
"first_name": "Super",
"last_name": "User",
"settings": {
"locale": "en"
},
"plainPassword": {
"first": "MySecurePassword123",
"second": "MySecurePassword123"
},
"force_login_password": 0,
"ssoProvider": null
}
...
Exemple de réponse
Check on the right side.
# EXAMPLE OF A RESPONSE FOR ONE USER
HTTP/1.1 200 OK
Content-Type: application/json
...
{
"id": 1763,
"subscription_id": "ce3759fc-fad9-4a70-2822-4eaf1bba925f",
"system_groups": [
1,
2
],
"groups": [
253,
254
],
"email": "user@daxium.com",
"active": true,
"first_name": "Super",
"last_name": "User",
"settings": {
"locale": "en"
}
}
...
List all users
Request
The list of all users is available via the / users API.
GET /users HTTP/1.1
Response
The answer is a JSON array with the list of users.
HTTP/1.1 200 OK
Content-Type: application/json
{
"users": [
{
"subscription_id": "",
"system_groups": [
1
],
"groups": [],
"id": 1,
"email": "superuser@daxium.com",
"active": true,
"first_name": "Super",
"last_name": "User",
"settings": {
"locale": "fr"
}
},
{
"subscription_id": "d4ea01d1-b18a-434d-90e4-1b939d7dba65",
"system_groups": [
2
],
"groups": [
8
],
"id": 3,
"email": "mobile.user@daxium.local",
"active": true,
"first_name": "Mobile",
"last_name": "User",
"settings": {
"locale": "fr"
}
},
{
"subscription_id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"system_groups": [
3
],
"groups": [],
"id": 4,
"email": "web.user@daxium.local",
"active": true,
"first_name": "Web",
"last_name": "User",
"settings": {
"locale": "fr"
}
}
],
"total_count": 3,
"total_pages": 1,
"server_time": 1496331477
}
Get current user
Request
The current user is available via the / users / me API.
GET /users/me HTTP/1.1
Response
The response is a JSON object containing the current user and the current user's company account
HTTP/1.1 200 OK
Content-Type: application/json
{
"user": {
"created_at": 1495442958,
"updated_at": 1496332388,
"id": 2,
"email": "user.mobile@daxium.local",
"email_canonical": "user.mobile@daxium.local",
"active": true,
"first_name": "User",
"last_name": "Mobile",
"last_login_mobile_at": "2017-06-01T17:53:08+0200",
"settings": {
"locale": "fr"
}
},
"company": {
"created_at": 1495201223,
"updated_at": 1495201223,
"id": 1,
"title": "Daxium"
}
}
User object
Check user object in the "User properties" above.
Company object
| Propriété | Type | Description |
|---|---|---|
| created_at | int | timestamp of date of creation |
| updated_at | int | timestamp of date of last update |
| id | int | identifier |
| title | string | displayed name |
Send a push key
Request
The / users / pushkey API is used to send a push key.
POST /users/pushkey HTTP/1.1
Content-Type: application/json
{
"id": "uniqueDeviceId",
"key": "a key",
"os": "android",
"os_version": "7.0",
"app_version": "1.7.1",
"name": "My phone"
}
| Property | Type | Description |
|---|---|---|
| id | string | unique identifier of the device |
| key | string | key |
| os | string | device's OS (Android or iOS) |
| os_version | string | OS' version |
| app_version | string | Daxium-Air's version |
| name | string | device's name |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{}
List users of a business app
Request
The list of users of a business app is avaible via the /{app_short}/users API.
GET /daxium-test/users HTTP/1.1
Response
The answer is a JSON array with the list of users.
HTTP/1.1 200 OK
Content-Type: application/json
{
"users": [
{
"subscription_id": "d4ea01d1-b18a-434d-90e4-1b939d7dba65",
"system_groups": [
2
],
"groups": [
8
],
"id": 3,
"email": "mobile.user@daxium.local",
"active": true,
"first_name": "Mobile",
"last_name": "User",
"settings": {
"locale": "fr"
}
},
{
"subscription_id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"system_groups": [
3
],
"groups": [],
"id": 4,
"email": "web.user@daxium.local",
"active": true,
"first_name": "Web",
"last_name": "User",
"settings": {
"locale": "fr"
}
}
],
"total_count": 2,
"total_pages": 1,
"server_time": 1496331477
}
Get a user by its identifier
Request
/{app_short}/users/{user_id} API allows you to retrieve a user by it's identifier.
GET /daxium-test/users/5 HTTP/1.1
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"subscription_id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"system_groups": [
2
],
"groups": [],
"id": 5,
"email": "mynewuser@daxium.com",
"active": true,
"first_name": "Daxium",
"last_name": "New user",
"settings": {
"locale": "fr"
}
}
Get a user by its username (email)
Request
/{app_short}/users?username=xxx@xxx.xx API allows you to retrieve a user by its username (email).
GET /daxium-test/users?username=user@daxium.com HTTP/1.1
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"subscription_id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"system_groups": [
2
],
"groups": [],
"id": 5,
"email": "user@daxium.com",
"active": true,
"first_name": "Daxium",
"last_name": "New user",
"settings": {
"locale": "fr"
}
}
Create a user
Request
/{app_short}/users API allows you to create a user.
# CREATE A USER WHO WILL NOT USE A SSO PROVIDER BUT A DAXIUM PASSWORD AUTHENTICATION
POST /daxium-test/users HTTP/1.1
Content-Type: application/json
{
"username": "mynewuser@daxium.com",
"active": true,
"firstName": "Daxium",
"lastName": "New user",
"locale": "fr",
"subscription_id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"system_groups": [2],
"groups": [],
"plainPassword": {
"first": "MySecurePassword123",
"second": "MySecurePassword123"
},
"force_login_password": 1,
"ssoProvider": null
}
# CREATE A USER WHO WILL CONNECT USING A COMPANY SSO PROVIDER
POST /daxium-test/users HTTP/1.1
Content-Type: application/json
{
"username": "mynewuser@daxium.com",
"active": true,
"firstName": "Daxium",
"lastName": "New user",
"locale": "fr",
"subscription_id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"system_groups": [2],
"groups": [],
"force_login_password": 0,
"ssoProvider": 123
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"subscription_id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"system_groups": [
2
],
"groups": [],
"id": 5,
"email": "mynewuser@daxium.com",
"active": true,
"first_name": "Daxium",
"last_name": "New user",
"settings": {
"locale": "fr"
}
}
Error codes
If some information are not filled in as they should, the server's response will be a HTTP 400 (bad request) error.
If the "username" (email) is already existing, the server's response will be a HTTP 409 (conflict) error.
If the "ssoProvider" provided is invalid, the server's response will be a HTTP 400 (validation failure) error.
If the information "force_login_password" and "ssoProvder" are sent while the company doesn't have any SSO provider configured, the request will fail (HTTP 400).
Create multiple users
Request
The endpoint /{app_short}/users/multiple aims at creating several users at once.
The payload consists of an array of user objects as they are designed for the single user creation API (see above).
POST /daxium-test/users/multiple HTTP/1.1
Content-Type: application/json
[
{
"username": "user1@daxium.com",
"active": true,
"firstName": "Daxium",
"lastName": "New user",
"locale": "fr",
"subscription_id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"system_groups": [2],
"groups": [],
"plainPassword": {
"first": "MySecurePassword123",
"second": "MySecurePassword123"
},
"force_login_password": 0,
"ssoProvider": null
},
{
"username": "user2@daxium.com",
"active": true,
"firstName": "Daxium",
"lastName": "New user",
"locale": "fr",
"subscription_id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"system_groups": [2],
"groups": [],
"plainPassword": {
"first": "MySecurePassword123",
"second": "MySecurePassword123"
},
"force_login_password": 0,
"ssoProvider": null
},
...
]
Response
Creating multiple use is done asynchronously.
So to know how the creation goes, this creation API returns a callback URL that has to be called in order to get the details of the creation process (are they OK, is there any error, ...). Please check the API "Multiple users callback" below for details.
HTTP/1.1 200 OK
Content-Type: application/json
{
"callbackUrl": "/{vm_short}/users/multiple/callback/062218c5-b471-4c23-908b-f514ee7c56f5"
}
Potential errors
If the number of users sent is higher than the maximum authorized (100), an error is returned with HTTP 400 code.
If no user is sent (empty payload / array), the response will be HTTP 400 code with an error explaining at least one user should be sent.
Update a user
Request
/{app_short}/users/{user_id} API allows you to update a user.
PATCH /daxium-test/users/5 HTTP/1.1
{
"username": "mynewuser@daxium.com",
"active": true,
"firstName": "Daxium 2",
"lastName": "New user 2",
"locale": "fr",
"subscription_id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"system_groups": [2],
"groups": [],
"plainPassword": {
"first": "MySecurePassword123",
"second": "MySecurePassword123"
}
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"subscription_id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"system_groups": [
2
],
"groups": [],
"id": 5,
"email": "mynewuser@daxium.com",
"active": true,
"first_name": "Daxium 2",
"last_name": "New user 2",
"settings": {
"locale": "fr"
}
}
Update multiple users
Request
The endpoint /{app_short}/users/multiple aims at creating several users at once.
The payload consists of an array of user objects as they are designed for the single user creation API (see above).
PUT /daxium-test/users/multiple HTTP/1.1
Content-Type: application/json
[
{
"username": "user1@daxium.com",
"active": true,
"firstName": "Daxium",
"lastName": "New user",
"locale": "fr",
"subscription_id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"system_groups": [2],
"groups": [],
"plainPassword": {
"first": "MySecurePassword123",
"second": "MySecurePassword123"
}
},
{
"username": "user2@daxium.com",
"active": true,
"firstName": "Daxium",
"lastName": "New user",
"locale": "fr",
"subscription_id": "b1e3588f-70d7-409e-abf7-3634f9dab3a7",
"system_groups": [2],
"groups": [],
"plainPassword": {
"first": "MySecurePassword123",
"second": "MySecurePassword123"
}
},
...
]
Response
Updating multiple use is done asynchronously.
So to know how the update goes, this update API returns a callback URL that has to be called in order to get the details of the update process (are they OK, is there any error, ...). Please check the API "Multiple users callback" below for details.
HTTP/1.1 200 OK
Content-Type: application/json
{
"callbackUrl": "/{vm_short}/users/multiple/callback/062218c5-b471-4c23-908b-f514ee7c56f5"
}
Potential errors
If the number of users sent is higher than the maximum authorized (100), an error is returned with HTTP 400 code.
If no user is sent (empty payload / array), the response will be HTTP 400 code with an error explaining at least one user should be sent.
Multiple users callback
Request
The API /{app_short}/users/multiple/callback/{callback_id} returns the status of an asynchronous creation / update of multiple users.
The URL of this API, including the "callback_id" UUID are given in response of the create and update multiple users APIs (see above).
GET /daxium-test/users/multiple/callback/bd49010b-fea7-4cd4-9ff2-c99679827ab9 HTTP/1.1
Response
The response contains all the details regarding the creation or update of multiple users. Please see example beside.
HTTP/1.1 200 OK
Content-Type: application/json
{
"callbackDetails": {
"status": "Finished with errors",
"nbRecordsTodo": 2,
"nbRecordsDone": 2,
"nbSuccess": 1,
"nbErrors": 1,
"success": [
{
"user_ok@daxium.com": {
"id": 248
}
}
],
"errors": [
{
"user_ko@daxium.com": {
"username": [
"Email is already used"
]
}
}
]
}
}
| Property | type | Description | Potential values |
|---|---|---|---|
| status | string | Current status of the query | Please check the possible status below |
| nbRecordsTodo | int | Number of users to process | 1, 25, 72, .. |
| nbRecordsDone | int | Number of users already processed | 1, 25, 72, .. |
| nbSuccess | int | Number of users processed succesfully | 1, 25, 72, .. |
| nbErrors | int | Number of users which process failed because of error(s) | 1, 25, 72, .. |
| success | object | JSON containing the list of users successfully created/updated. Format {"<username>" => {"id" => "<user_id>"}} |
Please check example on right side |
| errors | object | JSON containing the list of errors that occured by user. Format : {"<username>" => {"<field_name>" => ["<error_1>", "<error_2>", ...]}} |
Please check example on right side |
Statuts possibles
| Status | Description |
|---|---|
| Planned | Creation / Update has been received and planned. Not launched yet |
| Running | Creation / Update is being currently processed |
| Finished | Creation / Update finished with no errors |
| Finished with errors | Creation / Update finished but some errors were found (see example on right side) |
| Failed | A technical error occured and process couldn't be run normally |
| In timeout | A technical error occured and process couldn't be run normally |
Usual errors
- Try to create a user with an already existing email address
- Try to update a user which email address is not existing yet
- Invalid password :
- "first" / "second" are different
- rules not respected (number of chars, upper/lower cased chars...)
- Groupd or system group ID invalid
- Subscription ID invalid
Webhooks
Webhooks allow to send automatically a submission to an HTTP endpoint in a JSON format at some key moments of the submission lifecycle. Webhooks are configured in automations. The documentation here will describe de JSON format that will be sent out to the HTTP URL configured in the webhook automations.
Sending a submission via webhooks
Request
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "32dd0789-38bf-40a1-9b9e-0e5f40ec8018",
"type": "simple",
"submissionNumber": 65723,
"vmShort": "LEJALLEC",
"title": null,
"isTaskModel": false,
"latitude": null,
"longitude": null,
"items": [
{
"name": "label0",
"type": "label",
"label": "Titre 0"
},
{
"name": "logo1",
"type": "logo",
"image": "378180d3-0466-4404-bbef-e22b74e0b7e0",
"label": "Logo 1",
"banner": false,
"hiddenOnWeb": false
},
{
"name": "file2",
"type": "file",
"label": "Fichier 2",
"value": [
{
"id": "631b2b6b-9588-45d8-a77f-3f5228c83436",
"name": "Tests Action Builder.pdf",
"size": 74617,
"mimeType": "application\\/pdf",
"extension": "pdf"
}
]
},
{
"max": 2,
"name": "image3",
"type": "image",
"label": "Image 3",
"format": "medium",
"value": [
{
"id": "fa5affcd-152d-4e3b-8f9c-f034999b45ed",
"name": "waiting-meme.png",
"size": 73401,
"mimeType": "image\\/png",
"extension": "png"
},
{
"id": "a6d45e93-1cb2-41e1-91ad-fd2f158ccc06",
"name": "tinyrick.png",
"size": 151443,
"mimeType": "image\\/png",
"extension": "png"
}
]
},
{
"add": true,
"edit": true,
"grid": false,
"name": "relation4",
"type": "relation",
"label": "Relation 4",
"select": true,
"multiple": true,
"countable": false,
"structure": [
{
"structureId": 299
}
],
"positioningSupport": false,
"send_child_on_create": false,
"value": {
"submissions": [
{
"id": "6ebb2a58-0214-4586-8a9d-70ccc0d7f712",
"structure_id": 299
},
{
"id": "3a0f0421-a320-455c-b031-ced7a833daab",
"structure_id": 299
}
]
}
},
{
"name": "list5",
"type": "list",
"label": "Liste 5",
"display": "default",
"prefill": false,
"multiple": true,
"linkedlist": 15167973,
"searchable": false,
"barcodescan": false,
"externalscan": false,
"displayMobile": "default",
"value": {
"ids": [
15168005,
15168027
],
"lists": [
{
"id": 15168005,
"rootId": 15167973,
"name": "Arcueil",
"url": null,
"color": null,
"imageId": null,
"externalId": null
},
{
"id": 15168027,
"rootId": 15167973,
"name": "Gennevilliers",
"url": null,
"color": null,
"imageId": null,
"externalId": null
}
]
}
}
],
"createdAt": 1571836536,
"updatedAt": 1571925824,
"dataCreatedAt": 1571836536,
"dataUpdatedAt": 1571925824,
"structure": {
"id": 302,
"version": 2,
"name": "PARENT Form with file and image",
"hasTriggers": true,
"isLastVersion": true
},
"user": {
"id": 193,
"active": true,
"email": "c.lejalle@daxium.com",
"username": "CEDRIC LE JALLE",
"first_name": "CEDRIC",
"last_name": "LE JALLE",
"name": "CEDRIC LE JALLE",
"text": "CEDRIC LE JALLE",
"groups": [
63,
64
],
"state": {
"checked": false
}
},
"defaultImage": "fa5affcd-152d-4e3b-8f9c-f034999b45ed",
"settings": {
"tags": [],
"task": {
"enable": false
},
"color": "#5084C4",
"assignedAt": null,
"firstLevel": true
},
"currentState": {
"id": "4425a7c4-584d-47ca-a48b-08714d43845b",
"name": {
"en": "START en",
"fr": "START fr"
},
"color": "#00FF00",
"end": false
}
}
Daxium-Air is the requester and will call the URL in HTTP protocol. Hence there's no endpoint available for the webhooks.
The request is sent out with :
- The headers specified in the automation
- The full JSON content of the submission
If headers are specified in the webhook automation, these will be sent out with the request in the HTTP headers.
Here is an example of a header specified in the automation :
- Key : apitoken
- Value : api-token-secret-value`
In that case, the headers sent by the webhook will be :
apitoken: "api-token-secret-value"
Response
The response is received by Daxium-Air from the partner API.
If the response has a HTTP 2xx code, then Daxium-Air will consider that the submission sent via webhook is successful. For any other HTTP code (4xx, 5xx, ...), Daxium-Air will consider that the call failed. In that case the error returned by the partner API will be stored into Daxium-Air and can be viewed in the backoffice, and can be relaunched. The HTTP timeout is set to 30 seconds, so after this delay the webhook will be considered as failed.
Only the HTTP code for success cases is important as no content sent by the partner API will be read and stored.
Additional informations
The submission JSON content includes not only submission data but also some dependencies data.
But, elements of type relation are not fully sent.
Lists (included)
List items are fully included with their data and not only their IDs as in other submission APIs. Please check the "list5" item in the JSON aside.
Current state (included)
The submission workflow current state is also included with all its data if the submission belongs to a structure with a workflow. Please check the "currentState" node in the JSON aside.
Files and images (non included)
Files and images will be sent out with their IDs and some additional information (like the mime-type). Please check the "file2" and "image3" items in the aside JSON. The partner will have to call the files APIs in order to retrieve the files and images contents.
Relations (not included)
Elements of type "relation" are sent as in other submission APIs, it means with the related submission ID and its structure ID. Please check the exemple "relation4" in the aside JSON.
That being said, it will be necessary for the partner to call the GET submission APIs in order to retrieve the relations content.
Views
Get a view
Request
The /{app_short}/submissions_views/{view_id} API allows to get a view.
GET /daxium-test/submissions_views/53a20873-3935-4547-829f-bc4269ec297a HTTP/1.1
| Parameter | Type | Description |
|---|---|---|
| view_id | UUID | view identifier (required) |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "53a20873-3935-4547-829f-bc4269ec297a",
"name": "View with Normal string",
"icon": {
"type": "font-awesome",
"value": "fa-pencil"
},
"view_mode": "table",
"view_options": {
"ordered_fields": [
"user16",
"string3",
"date6",
"number4"
]
},
"assigned_to_user": true,
"filters": [
{
"item_filters": [
{
"name": "stringO",
"type": "string",
"operator": "EQUALS",
"values": ["Normal"]
},
{
"name": "user1",
"type": "user",
"operator": "EQUALS",
"values": [
786876
]
},{
"name": "user1",
"type": "user",
"operator": "IN_GROUPS",
"values": [
78776
]
},
{
"name": "user2",
"type": "user",
"operator": "EQUALS"
"values": [
"@current_user"
]
}
],
"structure_id": 278,
"metadata_filters": [
{
"name":"workflow_state",
"operator":"EQUALS",
"values" : [
"2CA5B9BF-4ED7-41B1-82AE-FD38F122FA02",
"6EB6CACD-3D8C-42CB-A036-5053BC59F971"
]
}
]
}
]
}
| Property | Type | Description |
|---|---|---|
| id | UUID | unique identifier |
| name | string | The user-localised name of the view |
| icon | JSON | Type and value of the icon represented by a JSON object |
| view_mode | string | The way the view will be displayed |
| view_options | JSON | JSON object containing the options of the view |
| ordered_fields | array | The list of fields to display in the given order, only applicable if view_mode = table |
| assigned_to_user | bool | A nullable boolean indicating if the view restricts submissions to those assigned to the current user or not |
| filters | JSON | An array of filtering rules for the view to apply |
| structure_id | int | The structure identifier of the submissions to be displayed |
| item_filters | array | An array of filtering rules for the items |
| name (item_filters) | string | The system name of the field |
| type (item_filters) | string | The Daxium-Air type of the field |
| operator (item_filters) | string | The operator to apply |
| values (item_filters) | array | A list of values to confront the value of the field to through the operator |
| metadata_filters | array | An array of filtering rules for the metadata |
| name (metadata_filters) | string | The system name of the metadata |
| operator (metadata_filters) | string | The operator to apply |
| values (metadata_filters) | array | A list of values to confront the value of the field to through the operator |