Emakin offers infrastructure services that enable seamless integration with other applications, in addition to its process-based services.
These services can be accessed via the URL: "http(s)://<mydomain>.emakin.com/rest", and service methods are invoked using the REST format.
Authentication
To execute infrastructure service calls, an API Key is required, which can be obtained from the system administrator.
Some methods also require the logonId and logonProvider parameters to act on behalf of a user. The logonProvider specifies the registered Open Authentication provider. If Emakin's default login system is used, this can be specified as 'Organization.' The logonId may vary depending on the provider; for example, if Active Directory is used, the logonId would be the Windows login username.
Token-generating login methods always return tokens within the scope of the registered API Key.
Services
GetToken
Generates an authentication token to authorise users. The generated token can be used in the auth parameter to authenticate users without requiring them to log in.
Required Scope
login
Parameters
Parameter Name | Description |
|---|---|
apiKey | A unique key used to authenticate and authorise the calling system. |
logonId | User’s logon Id. |
logonProvider | The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system). |
Example Call
POST https://mydomain.emakin.com/rest/v1/getToken
{
"apiKey": "xxxx",
"logonId": "user@emakin.com",
"logonProvider": "Organization"
}
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 "41AA3CE3CAFB..............BF8114"
GetTokenFromUserInfo
Generates an authentication token based on user information. If the user is not found and auto-registration is enabled for the logon provider, the user is automatically created, and an authentication token is returned for the newly registered user. Otherwise, the method returns an authentication token for an already registered user.
Required Scope
login
Parameters
Parameter Name | Description |
|---|---|
apiKey | A unique key used to authenticate and authorise the calling system. |
userInfo | User information. |
Example Call
POST https://mydomain.emakin.com/rest/v1/getTokenFromUserInfo
{
"apiKey": "xxxx",
"userInfo": {
"logonProvider": "LinkedIn",
"id": "wcomx2h3jd",
"name": "John Doe",
"email": "john.doe@noreply.com",
}
}
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 "41AA3CE3CAFB..............BF8114"
GetWorklist
Returns the list of work items on the user's worklist. The tag parameter specifies the identifier for the specific list to be returned.
Required Scope
worklist_read
Parameters
Parameter Name | Description |
|---|---|
apiKey | A unique key used to authenticate and authorise the calling system. |
logonId | User’s logon Id. |
logonProvider | The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system). |
tag | Identifier for the worklist. If set to null, the default inbox is returned. |
start | Starting point for the list. Use |
maxLength | Limit on the number of rows to return. Use |
queryXml | Optional parameter for specifying query XML. See Rest Services#Query for more details. |
Example Call
POST https://mydomain.emakin.com/rest/v1/getWorklist
{
"apiKey": "xxxx",
"logonId": "user@emakin.com",
"logonProvider": "Organization",
"tag": null,
"start": 0,
"maxLength": 30,
"queryXml" : ""
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"Id":"e5134318-88bd-4a33-b561-4d78380734ce",
"Caption":"A new task",
"Start":"/Date(1445812020394)/",
"End":null,
"Instructions":"Please complete.",
"State":"Waiting",
"Number":12471
},
{
"Id":"796a34c6-fd2e-450e-a2af-8124ea68f8ca",
"Caption":"A new other task",
"Start":"/Date(1445512843034)/",
"End":null,
"Instructions":"Please complete.",
"State":"Waiting",
"Number":12468
}
]
GetWorklistCount
Returns the total number of records in the worklist. This method can be used to define paging parameters for the GetWorklist method.
Required Scope
worklist_read
Parameters
Parameter Name | Description |
|---|---|
apiKey | A unique key used to authenticate and authorise the calling system. |
logonId | User’s logon Id. |
logonProvider | The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system). |
tag | Identifier for the worklist. If set to null, the default inbox is returned. |
queryXml | Optional parameter for specifying query XML. See Rest Services#Query for more details. |
Example Call
POST https://mydomain.emakin.com/rest/v1/getWorklistCount
{
"apiKey": "xxxx",
"logonId": "user@emakin.com",
"logonProvider": "Organization",
"tag": null,
"queryXml" : ""
}
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 50
GetWorkItem
Retrieves detailed information about a work item, either for display or to perform an action for its completion.
Required Scope
worklist_read
Parameters
Parameter Name | Description |
|---|---|
apiKey | A unique key used to authenticate and authorise the calling system. |
logonId | User’s logon Id. |
logonProvider | The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system). |
id | The unique identifier of the work item. |
readOnly | Set to |
Example Call
POST https://mydomain.emakin.com/rest/v1/getWorkItem
{
"apiKey": "xxxx",
"logonId": "user@emakin.com",
"logonProvider": "Organization",
"id": "e5134318-88bd-4a33-b561-4d78380734ce"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"Id": "e5134318-88bd-4a33-b561-4d78380734ce",
"Caption": "A new task",
"Culture": "en-US",
"Start": "/Date(1445812020394)/",
"End": null,
"DeadlineDate": null,
"InstanceNumber": 12471,
"IsReadOnly": false,
"SelectedActionId": null,
"Actions": [
{
"Id": "2b0aa720-82f8-4a62-b7a1-2389203fa5e7",
"Name": "Complete",
"Color": "",
"BackgroundColor": "",
"Order": 1,
"Hidden" : false,
"RequireComment": false,
"ConfirmationMessage": "",
"ValidationGroup": ""
},
{
"Id": "c5350e5c-6e03-4b72-9522-49ab7f849b8a",
"Name": "Cancel",
"Color": "",
"BackgroundColor": "",
"Order": 2,
"Hidden" : false,
"RequireComment": true,
"ConfirmationMessage": "",
"ValidationGroup": ""
}
]
}
SelectAction
Selects an action for a work item and returns an array of identifiers for the next work items in the process.
Required Scope
workitem_action
Parameters
Parameter Name | Description |
|---|---|
apiKey | A unique key used to authenticate and authorise the calling system. |
logonId | User’s logon Id. |
logonProvider | The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system). |
id | The unique identifier of the work item. |
action | The identifier for the selected action. |
data | The XML data associated with the form. This can be null. (Note: There is no merge operation; the entire form data must be sent. If omitted, the form data will be replaced with the new data. You can retrieve the current data using the The final data should be enclosed within a form element, e.g. |
comments | User comments. |
Example Call
POST https://mydomain.emakin.com/rest/v1/selectAction
{
"apiKey": "xxxx",
"logonId": "user@emakin.com",
"logonProvider": "Organization",
"id": "e5134318-88bd-4a33-b561-4d78380734ce",
"action": "c5350e5c-6e03-4b72-9522-49ab7f849b8a",
"data": null
}
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ "716F8FCB-98C2-4591-8C43-043D54DEAADA" ]
InitiateByProcess
Initiates a new process instance using the specified parameters and returns the Id of the newly created work item.
Required Scope
process_initiate
Parameters
Parameter Name | Description |
|---|---|
apiKey | A unique key used to authenticate and authorise the calling system. |
logonId | User’s logon Id. |
logonProvider | The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system). |
process | The name or Id of the process to initiate. |
task | The name or Id of the task within the process. |
version | The version number or Id of the process. This can be null. |
data | XML data associated with the process. This can be null. |
culture | The culture preference. This can be null. |
Example Call
POST https://mydomain.emakin.com/rest/v1/initiateByProcess
{
"apiKey": "xxxx",
"logonId": "user@emakin.com",
"logonProvider": "Organization",
"process": "e5134318-88bd-4a33-b561-4d78380734ce",
"task": "c5350e5c-6e03-4b72-9522-49ab7f849b8a",
"version": null,
"data": "<pool><myField>ABC</myField></pool>",
"culture": null
}
HTTP/1.1 200 OK "716F8FCB-98C2-4591-8C43-043D54DEAADA"
ExecuteModule
Executes the specified module and returns the result of the module function.
Required Scope
module_execute
Parameters
Parameter Name | Description |
|---|---|
apiKey | A unique key used to authenticate and authorise the calling system. |
logonId | User’s logon Id. |
logonProvider | The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system). |
process | The name or Id of the process to initiate. |
module | The name of the module to call. |
function | The name of the function to call within the module. |
arguments | An array of parameters to pass to the function. |
Example Call
POST https://mydomain.emakin.com/rest/v1/executeModule
{
"apiKey": "xxxx",
"logonId": "user@emakin.com",
"logonProvider": "Organization",
"process" : "MyProcess",
"module": "MyModule",
"function": "myFunction",
"arguments": ["myParameter","myOtherParameter"]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"property1": 1,
"property2": "value"
}
Trigger
Triggers an event for listeners across all processes and returns an array of IDs for the triggered work items. If no listeners are found, the return value is an empty array.
Required Scope
event_trigger
Parameters
Parameter Name | Description |
|---|---|
apiKey | A unique key used to authenticate and authorise the calling system. |
logonId | User’s logon Id. |
logonProvider | The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system). |
eventName | The name of the event to trigger. |
testMode | Trigger the test mode or not work items. |
inputData | Event data in XML format. This can be null. |
culture | The culture preference. This can be null. |
Example Call
POST https://mydomain.emakin.com/rest/v1/trigger
{
"apiKey": "xxxx",
"logonId": "user@emakin.com",
"logonProvider": "Organization",
"eventName" : "myEvent",
"inputData": "<pool><eventParameter>ABC</eventParameter></pool>",
"testMode": false,
"culture": null
}
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 ["716F8FCB-98C2-4591-8C43-043D54DEAADA"]
Query
The query is an XML-based string that specifies the desired result set. If not provided, the default query is executed.
The query can be defined using the following column names for specifying the result set columns, criteria, and order.
Worklist Columns
Name | Description |
|---|---|
Id | Unique identifier of the work item. |
Name | Name of the work item. |
Caption | Localised caption of the work item. |
State | The current state of the work item. |
Start | Start date of the work item. |
End | End date of the work item. Can be null. |
IsDeadlined | A boolean that specifies the deadline has occurred. |
DeadlineDate | Deadline date. Can be null. |
NextReminderDate | Next reminder date. Can be null. |
SentReminders | Number of reminders sent. |
Instructions | Instructions for the work item. |
InstanceId | Unique identifier of the instance. |
PreviousWorkItemId | Identifier of the previous work item. Can be null. |
ActionId | Unique identifier for the action. Can be null. |
CompletedById | Id of the user who completed the work item. Can be null. |
CompletedBy | Display name of the user who completed the work item. Can be null. |
Number | Instance number. |
Priority | Priority of the instance. |
ProcessId | The Id of the process. |
ProcessName | The name of the process. |
FromId | Identifier of the initiating user. Can be null. |
From | Display name of the initiator user. Can be null. |
FolderId | Identifier of the related folder. |
FolderName | Name of the related folder. |
AssignedTo | List of users assigned to the work item. |
VersionNumber | Version number of the related process. |
VersionId | Version Id of the related process. |
TestMode | Boolean indicating whether the instance is in test mode. |
Instance.Start | Start date of the instance. |
Instance.State | State of the instance. |
Query contains the following sections;
Columns
A list of column names to be included in the result set.
Where
A list of criteria for filtering the results. The criteria names must correspond to column names.
Order
A list of sorting criteria. The order names must also correspond to column names.
Example Query Xml
<Query Start="" MaxLength="25">
<Columns>
<Column Expression="Id"/>
<Column Expression="Instructions"/>
<Column Expression="State"/>
<Column Expression="FromId"/>
<Column Expression="From"/>
<Column Expression="SentReminders"/>
<Column Expression="HasHistory"/>
<Column Expression="Caption"/>
<Column Expression="Start"/>
<Column Expression="DeadlineDate"/>
<Column Expression="End"/>
<Column Expression="FolderName"/>
<Column Expression="Number"/>
</Columns>
<Where>
<Criteria>
<Criteria Expression="Caption" Comparison="Like">
<Value>My Task*</Value>
</Criteria>
</Criteria>
</Where>
<Order>
<Order Expression="Start" Type="Descending" />
</Order>
</Query>
Decision
Returns the result of a decision model evaluation. This method processes input data and applies the business logic defined in the decision model to return an outcome. The decision model may involve rules, conditions, and calculations that lead to the final decision result.
Required Scope
decision_execute
Parameters
Parameter Name | Description |
|---|---|
apiKey | A unique key used to authenticate and authorise the calling system. |
logonId | User’s logon Id. |
logonProvider | The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system). |
process | The name or Id of the process related to the decision. |
model | The name or ID of the decision model to be evaluated. |
decision | The name or Id of the specific decision to be executed within the model. |
inputData | Input data for the decision, provided as either an XML or JSON string. |
Example Call
POST https://mydomain.emakin.com/rest/v1/decision
{
"apiKey": "",
"logonId": "user@emakin.com",
"logonProvider": "Organization",
"process" : "Decision",
"model" : "dinner",
"decision" : "Dish",
"inputData": "<pool><Season>Fall</Season><NumberOfGuests>2</NumberOfGuests></pool>"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 26
{"Dish":"Spareribs"}