Skip to content

API

This document introduces the Web API for eLegere.

The eLegere Web API enables the web clients to request data from eLegere's applications. The returned data depends on the level of authorized access from the user's session: if the user hasn't a specific authorization, the API won't return some data.

Note

The API returns all the responses as either JSON objects or content stream.

Every time your third-party integration requests data through the API, the returned JSON objects encodes the different data types according to specific formats. Check the eLegere Data Types reference to learn about the eLegere data types' format.

Tip

If a method requires the Application Id, check the section Retrieve Application's ID to learn how to retrieve an application's Id.

Other Id types: recover the necessary Id by checking the eLegere's meta-data database.

Note

There are limitations for both the URL requests and the requests' Body in POST:

  • URL String for the request has the maximum length of 2048 characters.
  • The API accepts Body size for the request up to 60 Mb.

These limitations are independent from eLegere.

Info

Check the Conventions and HTTP Status Codes to learn about terms conventions and HTTP Status Codes responses.

Warning

In the Header description, SessionToken stands for the access_token in the Request.

Authentication

Authentication

The method enables the user to authenticate to the eLegere's environment. The service returns a Session Token with everything required for the access.

Request

Method POST
URL {base_url}/identityprovider/connect/token
Protocols HTTPS
ContentType application/x-www-form-urlencoded
Headers no headers required
Return JSON Object
Body:
1
client_id=elegereapiv1&username={email}&password={user password}&grant_type=password&scope=openid apiv1 nosession

Examples

Create a WEB request to authorize a user's access and obtain a Session Token for them. The JSON contains the Session Token, the expiration time in milliseconds, the type, and the scope.

Raw Request:

1
2
3
POST /identityprovider/connect/token
Content-Type: application/x-www-form-urlencoded
client_id=elegereapiv1&username={email}&password={user password}&grant_type=password&scope=openid apiv1 nosession

Raw Response:

1
2
3
4
5
6
7
8
//HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZC...",
    "expires_in":3600,
    "token-type": "",
    "scope": ""
}

Get Items

Data

The method queries an application through the WorkspaceId, ApplicationId, and Session Token to obtain an application's data. Check Filters' Query Composition for more info about the operators and options eLegere supports for the items' queries.

Request

Method POST
URL {base_url}/SmartExplorerApi/api/items
Protocols HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return Array of JSON Objects
Body:
1
{"query":"$top=200&$skip=0&$orderby=DT_CREATION desc&$filter=fieldName ODATA_Operator 'value'"}

Examples

The request provides the Session Token for the access, the response file's format, the workspace Id (i.e the Domain) and application's Id for the the API to retrive the data. The body contains the string with the query. The query provides the parameters for the top, exceptions, and the order and field for the sorting.

Raw Request:

1
2
3
4
5
6
7
8
// POST /SmartExplorerApi/api/items
// Content-Type: application/json
// ApplicationId: "49ed-b7f3-ef6a2d3177f2"
// SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
// WorkspaceId: "3a98b7ec-8f6c-49ed-b7f3-ef6a2d3177f2"


{"query":"$top=200&$skip=0&$orderby=DT_CREATION desc$filter=fieldForRequest eq 'API_TEST_RB_1'"}

Raw Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

[
  {
    "Id": 1,
    "Field1": "Value 1",
    "Field2": 2,
    "Field3": true,
    "CT_ATTACHMENTS": null,
    "DT_CREATION": null,
    "DT_LAST_UPDATE": null,
    "ROW_ORDER": null,
    "TIMESTAMP": "AAAAAQ==",
    "USER_ID_CREATION": null,
    "USER_ID_LAST_UPDATE": null
  }
]

Get Items Count

Data

The method queries an application through the WorkspaceId, ApplicationId, and Session Token to count the exact number of items in the application satisfying the criteria.

Request

Method POST
URL {base_url}/SmartExplorerApi/api/items
Protocols HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return JSON Object
Body:
1
{"query":"$inlinecount=allpages"}

Examples

The request provides the Session Token for the access, the response file's format, the workspace Id (i.e the Domain) and application's Id for the the API to retrive the info. The response reports the number of items according to the criteria specified in the body.

Raw Request:

1
2
3
4
5
6
7
// POST /SmartExplorerApi/api/items
// Content-Type: application/json
// ApplicationId: "49ed-b7f3-ef6a2d3177f2"
// SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
// WorkspaceId: "3a98b7ec-8f6c-49ed-b7f3-ef6a2d3177f2"

{ "query": "$inlinecount=allpages" }

Raw Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

{
  "Timestamp": 637534770772767600,
  "Items": [
    {
      "_FieldCount_": 876
    }
  ]
}

Save

Data

The method queries an application through the WorkspaceId, ApplicationId, and Session Token to create or update a row on the application's table.

If you want to create a new row, insert a negative progressive number as row's Id.

E.g. If you save three new rows, insert -1 as Id of the first row, -2 for the second, and so on. The service will assign a proper database Id after the save.

If you want to update an item:

1) Call the Get Items API method to retrive the information of the rows to update.

2) Recover the TIMESTAMP key value from the retrieved objects for the rows to be updated.

3) Call the Save method; insert in TIMESTAMP keys the values from step (2) in the objects to save the rows.

Request

Method POST
URL {base_url}/SmartExplorerApi/api/items/save
Protocols HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return Array of JSON Objects
Body:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "Rows": [
    {
      "Row": {
        "Name": "John",
        "Surname": "Doe",
        "Id": -1,
        "IdRow": 22,
        "TIMESTAMP": null
      },
      "Details": []
    }
  ]
}

Examples

The request contains the row's information as object: each row's field and value corresponds to an object's key. The response provides an object detailing if the saving process was successful (i.e. the key "IsSaveSuccesfully"), what has been saved, created, edited or deleted, and a link to the Master's row (i.e. the key "MasterRowLink" in the object).

Raw Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// POST /SmartExplorerApi/api/save
// Content-Type: application/json
// ApplicationId: "65abe727-93bc-47e0-a372-21f399c37e69"
// SessionToken: "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM..."
// WorkspaceId: "87bab64d-f1ad-4496-b66a-25748206458c"

{
  "Rows": [
    {
      "Row": {
        "Name": "John",
        "Surname": "Doe",
        "Id": -1,
        "IdRow": 11,
        "TIMESTAMP": null
      },
      "Details": [
        {
          "RelationKey": "a5637422-8d21-48e7-a032-c9eba7713d9f",
          "Rows": [
            {
              "Address:": "via Fratelli Cuzio 42",
              "City:": "Pavia",
              "ZIP": "27100",
              "IdRow": 20,
              "Id": -1,
              "TIMESTAMP": null
            }
          ]
        }
      ]
    }
  ]
}

Raw Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

{
  "IsSaveSuccesfully": true,
  "ReturnStates": [],
  "ReturnData": {
    "PrimaryKeyData": {
      "-1": {
        "newKeys": {
          "7acaf2c9-aa5b-424b-88f1-018d30d867e9": "12"
        }
      }
    }
  },

  "MasterToRecalculate": [],
  "CreatedItems": 1,
  "UpdatedItems": 0,
  "DeletedItems": 0,
  "LockedItems": 0,
  "MasterRowLink": "https://...",
  "RowIdentifier": "IdRow",
  "StorageName": "sStorageExample",
  "SavedItems": null
}

Delete

Data

The method queries an application through the WorkspaceId, ApplicationId, and Session Token to delete a row from the application's table.

Delete a row by inserting its Id in the object's Id key and its Timestamp in the TIMESTAMP key.

The method deletes the row with that particular Id and Timestamp.

Request

Method POST
URL {base_url}/SmartExplorerApi/api/items/delete
Protocols HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return Array of JSON Objects
Body:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
[
  {
    "Rows": [
      {
        "Row": {
          "Id": 1,
          "TIMESTAMP": 638333257746117400
        },
        "Details": []
      }
    ]
  }
]

Examples

The request contains the row's Id and its Timestamp. These two values are essential to identify the row to be deleted.

After the deletion, the Response object reports if the operation has been successful through the IsSaveSuccesfully key's value.

Raw Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// POST /SmartExplorerApi/api/delete
// Content-Type: application/json
// ApplicationId: "65abe727-93bc-47e0-a372-21f399c37e69"
// SessionToken: "eyJhbGciOiJSUzI1NiIsImtpZCI6IjM..."
// WorkspaceId: "87bab64d-f1ad-4496-b66a-25748206458c"

{
  "Rows": [
    {
      "Row": {
        "Id": 55,
        "TIMESTAMP": 638333257746117400
      },
      "Details": []
    }
  ]
}

Raw Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

{
    "IsSaveSuccesfully": true,
    "ReturnStates": [],
    "MasterToRecalculate": [],
    "CreatedItems": 0,
    "UpdatedItems": 0,
    "DeletedItems": 1,
    "LockedItems": 0,
    "MasterRowLink": "https://...",
    "RowIdentifier": "IdRow",
    "StorageName": "sStorageExample",
    "SavedItems": null
}

Get Attachments List

Data

The method retrieves the attachments list of a row in an application starting from the row's Id and attachments' folder Id.

Note

You can obtain a row's Id through the Get Items method. Replace it in the URL to identify the row's attachments list.

Info

The last part of the URL and FolderId eq FOLDERID is optional. You need the FOLDERID only to retrive the attachment list if the attachment is nested in a folder within the row's attachments folders' tree. Check Filters' Query Composition for more info about the operators and options eLegere supports for the items' queries.

Request

Method GET
URL {base_url}/SmartExplorerApi/api/attachments?$filter=ParentId eq ROWID and FolderId eq FOLDERID
Protocols HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return Array of JSON Objects

Examples

The method retrieves the row's attachments list starting from the row's Id. The array object contains an object for each row's attachment. Each object details the individual attachment's information.

Raw Request:

1
2
3
4
5
GET /SmartExplorerApi/api/attachments?$filter=ParentId eq 1 and FolderId eq 4
Content-Type: application/json
ApplicationId: "49ed-b7f3-ef6a2d3177f2"
SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
WorkspaceId: "3a98b7ec-8f6c-49ed-b7f3-ef6a2d3177f2"

Raw Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8

[
  {
    "Description": "file.xml",
    "DT_CREATION": 20220713125300,
    "DT_LAST_UPDATE": null,
    "Id": 1242,
    "FolderId": null,
    "IsFolder": false,
    "Name": "file.xml",
    "ParentId": 1,
    "TypeImage": "text/xml",
    "USER_ID_CREATION": "vesenda@elegere.com",
    "USER_ID_LAST_UPDATE": 20230405133245
  }
]

Download Attachment

Data

The method accesses through a Session Token and retrieves the desired attachment through its Id on the database.

Note

You can download both individual attachments and folders. If the request points a folder, the API returns a .zip archive with all the folder's attachments.

Note

In the request, the rk is the parent key of the Master-Detail relation. rk is optional in the request. You must specify rk in the request if and only if you download an attachment from a Detail's row. Otherwise, the request refers to a row on the Master table.

Request

Method POST
URL {base_url}/SmartExplorerApi/api/attachments/download
Protocols HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return File Stream

Examples

The method retrieves an attachment starting from the row's Id. In the example below, the method retrieves an attached XML file from a row.

Raw Request:

1
2
3
4
5
6
7
// GET /SmartExplorerApi/api/attachment/download
// Content-Type: application/json
// ApplicationId: "49ed-b7f3-ef6a2d3177f2"
// SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
// WorkspaceId: "3a98b7ec-8f6c-49ed-b7f3-ef6a2d3177f2"

{ "ids": [1, 2], "rk": "" }

Raw Response:

1
2
3
4
5
// HTTP/1.1 200 OK
// Content-Type: application/xml;


Content-Disposition: attachment; filename="file.xml"

Run Action

Data

The method launches one of the Custom Actions designed for the chosen application. The method identifies the Custom Action to launch through the action's actionId.

Request

Method POST
URL {base_url}/SmartExplorerApi/api/action/run
Protocols HTTPS
ContentType application/json
Headers ApplicationId, SessionToken, WorkspaceId
Return JSON Object
Body:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "actionId": "GUID",
  "parametersMap": [
    {
      "Name": "ProcedureName",
      "Value": "name of stored procedure"
    },
    {
      "Name": "Parameters",
      "Value": [
        {
          "key": "p1",
          "value": "p1 value"
        },
        {
          "key": "p2",
          "value": "p2 value"
        },
        {
          "key": "pn",
          "value": "pn value"
        }
      ]
    }
  ]
}

Examples

The method executes the specified Custom Actions and returns the object reporting the operation's result. If the key IsSuccessful in the object has value true, the Custom Action has run successfully.

Raw Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
// POST /SmartExplorerApi/api/action/run
// Content-Type: application/json
// ApplicationId: "49ed-b7f3-ef6a2d3177f2"
// SessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."
// WorkspaceId: "b5b1a6ae6b314c4593c112d8d079d6d0"

{
  "actionId": "710333fc-7098-48e4-bb94-008d260a514f",
  "parametersMap": [
    {
      "Name": "Parameters",
      "Value": [
        {
          "key": "Quantity",
          "value": "10"
        }
      ]
    }
  ]
}

Raw Response:

1
2
3
4
5
6
7
8
9
// HTTP/1.1 200 OK
// Content-Type: application/xml;

{
  "Message": "Operation success",
  "IsSuccessful": true,
  "Result": "",
  "IsAsync": false
}

Send Email

Utility

The method queries the service to send an email containing the specified recipients, subject, body, and the providerId (optional) in the request. The providerId is a GUID identifying an eLegere installation's email provider configured in the settings. If the request doesn't contain any providerId, the Send Email API uses the default eLegere providerId configured during the installation.

Request

Method POST
URL {base_url}/ewebaggregator/api/v1/email/queue
Protocols HTTPS
ContentType application/json
Headers Authorization, WorkspaceId
Return No Object Returned
Body:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// POST {base_url}/ewebaggregator/api/v1/email/queue

// Content-Type: application/json
// WorkspaceId: [WORKSPACEID]
// Authorization: Bearer [SESSIONTOKEN]

{
  "providerId": "string",
  "to": ["string"],
  "subject": "string",
  "body": "string"
}

Examples

The service receives the request with the recipients, subject, and the body information. In the example, the request doesn't contain a providerId: it will use the default eLegere installation's provider.

Raw Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// POST myinstallation.elegereapp.com/ewebaggregator/api/v1/email/queue

// Content-Type: application/json
// WorkspaceId: "b5b1a6ae6b314c4593c112d8d079d6d0"
// Authorization: Bearer "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c..."

{
  "to": ["j.doe@vesenda.com", "d.doe@vesenda.com"],
  "subject": "Send Email API Example",
  "body": "Messages sent with Send Email API."
}

Raw Response:

1
// Empty Response Body