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.

1 Authentication
2 Services
- 2.1 GetToken
  - 2.1.1 Required Scope
  - 2.1.2 Parameters
  - 2.1.3 Example Call
- 2.2 GetTokenFromUserInfo
  - 2.2.1 Required Scope
  - 2.2.2 Parameters
  - 2.2.3 Example Call
- 2.3 GetWorklist
  - 2.3.1 Required Scope
  - 2.3.2 Parameters
  - 2.3.3 Example Call
- 2.4 GetWorklistCount
  - 2.4.1 Required Scope
  - 2.4.2 Parameters
  - 2.4.3 Example Call
- 2.5 GetWorkItem
  - 2.5.1 Required Scope
  - 2.5.2 Parameters
  - 2.5.3 Example Call
- 2.6 SelectAction
  - 2.6.1 Required Scope
  - 2.6.2 Parameters
  - 2.6.3 Example Call
- 2.7 InitiateByProcess
  - 2.7.1 Required Scope
  - 2.7.2 Parameters
  - 2.7.3 Example Call
- 2.8 ExecuteModule
  - 2.8.1 Required Scope
  - 2.8.2 Parameters
  - 2.8.3 Example Call
- 2.9 Trigger
  - 2.9.1 Required Scope
  - 2.9.2 Parameters
  - 2.9.3 Example Call
- 2.10 Query
  - 2.10.1 Worklist Columns
  - 2.10.2 Columns
  - 2.10.3 Where
  - 2.10.4 Order
  - 2.10.5 Example Query Xml
- 2.11 Decision
  - 2.11.1 Required Scope
  - 2.11.2 Parameters
  - 2.11.3 Example Call

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

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

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

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

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 `0` to begin from the first item.
maxLength	Limit on the number of rows to return. Use `-1` to retrieve all rows.
queryXml	Optional parameter for specifying query XML. See Rest Services#Query for more details.

Example Call

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

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

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

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 `true` to fetch the work item in read-only mode. The default value is `false`.

Example Call

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

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 `GetWorkItemData` method. The final data should be enclosed within a form element, e.g. `<form><Data>...</Data></form>`.)
comments	User comments.

Example Call

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

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

ExecuteModule

Executes the specified module and returns the result of the module function.

Required Scope

module_execute

Parameters

Parameter Name	Description

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

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

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	Determines whether the event should also trigger for items in test mode.
inputData	Event data in XML format. This can be null.
culture	The culture preference. This can be null.

Example Call

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

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

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

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.

Rest Services

Authentication

Services

GetToken

Required Scope

Parameters

Example Call

GetTokenFromUserInfo

Required Scope

Parameters

Example Call

GetWorklist

Required Scope

Parameters

Example Call

GetWorklistCount

Required Scope

Parameters

Example Call

GetWorkItem

Required Scope

Parameters

Example Call

SelectAction

Required Scope

Parameters

Example Call

InitiateByProcess

Required Scope

Parameters

Example Call

ExecuteModule

Required Scope

Parameters

Example Call

Trigger

Required Scope

Parameters

Example Call

Query

Worklist Columns

Columns

Where

Order

Example Query Xml

Decision

Required Scope

Parameters

Example Call