Vai al contenuto

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.

Hint

If a method requires any ID to work (e.g. ApplicationId, WorkspaceId): you can recover the necessary Id by checking the eLegere's meta-data database.

Info

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

Attention

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
//HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZC...",
    "expires_in":3600,
    "token"
}

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 the TIMESTAMP values from (2) in the objects to save.

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 or 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
{
    "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 Items

Data

The method queries an application through the WorkspaceId, ApplicationId, and Session Token to obtain an application's data.

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"}

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"}

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
8
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
        }
    ]
}

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 in a folder within the row's attachments folders' tree.

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
    }
]

Get 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 GET
URL {base_url}/SmartExplorerApi/api/attachment/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
8
9
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/attachment/file?id=1
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
27
{
    "actionId":"GUID",
    "parametersMap": [
    {
        "Name":"ProcedureName",
        "Value":"name of stored procedure"
    },
    {
        "Name":"Parameters",
         "Value": [
            {
            "key":"p1",
            "value":"p1 value"
            },
            {
            "key":"p2",
            "value":"p2 value"
            },
            // ... Series of values
            {
            "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
21
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
10
// 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 the eLegere installation's email provider's 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
13
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. 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
12
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