Versions Compared

Old Version 30

changes.mady.by.user Ertan Tike

Saved on

compared with

New Version Current

changes.mady.by.user Selahattin Bostanci

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Including process based services Emakin also provides infrastructure services to integrate Emakin offers infrastructure services that enable seamless integration with other applications, in addition to its process-based services.

Infrastructure These services can be accessed from via the URL: "http(s)://<mydomain>.emakin.com/rest" url. Service methods can be called in rest , and service methods are invoked using the REST format.

Table of Contents

Authentication

Infrastructure To execute infrastructure service calls requires , an API Key to execute and get be acquired from is required, which can be obtained from the system administrator.

Some of methods requires "also require the logonId" and "logonProvider" parameters to act as user's behalf. Logon provider on behalf of a user. The logonProvider specifies the registered open auth logon Open Authentication provider. If Emakin's default emakin login system is used, this can be specified as "'Organization". Depending on selected provider logon id can be changes, for example if you use active directory logon id can be specified as windows logon user.' 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 authorize authorise users later. Generated The generated token can be use to "auth" used in the auth parameter to authorise authenticate users without login requirement.requiring them to log in.

Required Scope

login

Parameters

Parameter Name

Description

apiKey

Caller system identifier

A unique key used to authenticate and authorise the calling system.

logonId

User

User’s logon

id

Id.

logonProvider

User logon provider

The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system).

Example Call

...

Code Block

...

POST

...

https://

...

mydomain.emakin.com/rest/v1/getToken
 
{
     "apiKey": "xxxx",
     "logonId": "user@emakin.com",
     "logonProvider": "Organization"
}

...

Code Block
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 

...

"

...

41AA3CE3CAFB..............BF8114"

...

GetWorklist
Returns the list of work items on user's worklist. Tag parameter specifies the identifier of which list should be return.
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
Caller system identifier
A unique key used to authenticate and authorise the calling system.
logonId
userInfo
User 
 logon idlogonProviderUser logon provider
information.
tagWorklist identifier. If set to null default inbox is returned.startStart number of list. Use 0 to start from beginning.maxLengthLimit of number of rows in list. Use -1 to get all rows.queryXmlOptional query xml value. See Query for more details.
Example Call
...
Example Call
 Code Block
POST https://mydomain.emakin.com/rest/v1/getTokenFromUserInfo
 
{
     "apiKey": "xxxx",
     "
...
userInfo": 
...
{
     	"logonProvider": "
...
LinkedIn",
        "
...
id": 
...
"wcomx2h3jd",
        "
...
name": "John 
...
Doe",
        "
...
email": 
...
"john.doe@noreply.com",
     
...
}
}
...
 Code Block
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 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
 Code Block
POST https://mydomain.emakin.com/rest/v1/getWorklist
 
{
     "apiKey": "xxxx",
     "logonId": "user@emakin.com",
     "logonProvider": "Organization",
     "tag": null,
     "start": 0,
     "maxLength": 30,
     "queryXml" : ""
}
 Code Block
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. You can use this method to specify paging parameters in GetWorkList method.This method can be used to define paging parameters for the GetWorklist method.
Required Scope
worklist_read
Parameters
Parameter Name
Description
apiKey
Caller system identifier
A unique key used to authenticate and authorise the calling system.
logonId
User 
User’s logon 
 idtagWorklist identifier
Id.
logonProvider
User logon provider.
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 value
XML. See 
 Query 
 Rest Services#Query for more details.
Example Call
...
 Code Block
...
POST 
...
https://
...
mydomain.emakin.com/rest/v1/getWorklistCount
 
{
     "apiKey": "xxxx",
     "logonId": "user@emakin.com",
     "logonProvider": "Organization",
     "tag": null,
     "queryXml" : ""
}
...
 Code Block
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
...


...
50
...
GetWorkItem
Gets workitem information to display or complete with action.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
Caller system identifier
A unique key used to authenticate and authorise the calling system.
logonId
User 
User’s logon 
 id
Id.
logonProvider
User logon provider
The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system).
id
Work item identifier
The unique identifier of the work item.
readOnly
Set to true to fetch the work item in read-only mode. 
 Default 
The default value is false.
Example Call
...
 Code Block
POST 
...
https://
...
mydomain.emakin.com/rest/v1/getWorkItem

{
     "apiKey": "xxxx",
     "logonId": "user@emakin.com",
     "logonProvider": "Organization",
     "id": "e5134318-88bd-4a33-b561-4d78380734ce"
}
...
 Code Block
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": ""

...
        }
    
...
GetWorkItemData
Gets the xml data of workitem.
Parameters
Parameter NameDescription
apiKeyCaller system identifier.
logonIdUser logon id
logonProviderUser logon provider.
idWork item identifier.
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
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
 Code Block
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
}
 Code Block
HTTP/1.1 200 OK
Content-Type: application/json; charset=
...
SelectAction
Selects an action on a work item and returns array of next work item identifiers.
Parameters
...
XML data. Can be null. (There is no merge operation. Whole form data should be sent otherwise
the form data is replaced with the new data. The data can be retrieved by GetWorkItemData method.
The final data should be send inside of a form element. e.g. <form><Data>...</Data></form>)
...
Example Call
...
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
 Code Block
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
}
...
 Code Block
HTTP/1.1 200 OK
...


...


...
"716F8FCB-98C2-4591-8C43-043D54DEAADA"
...


...
InitiateByProcess
Initiates a new process instance with specified parameters and returns the Id number of work item.
...
ExecuteModule
Executes the specified module and returns the result of the module function.
Required Scope
module_execute
Parameters
Parameter Name
Description
apiKey
Caller system identifier
A unique key used to authenticate and authorise the calling system.
logonId
User 
User’s logon 
 id
Id.
logonProvider
User logon provider
The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system).
process
Name 
The name or Id 
 number 
 of the process to initiate.
taskName or Id number of taskversionVersion number or id of process. Can be null.dataXML data. Can be null.cultureCulture preference. Can be null
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
...
 Code Block
...
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"]
}
...
 Code Block
HTTP
...
/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
     "property1": 1,
     "
...
property2": "
...
value"
}

Trigger
Triggers an event for listeners on across all processes and returns an array of id number of IDs for the triggered work items. When there is no listener If no listeners are found, the return value is a an empty array.
Required Scope
event_trigger
Parameters
Parameter Name
Description
apiKey
Caller system identifier
A unique key used to authenticate and authorise the calling system.
logonId
User 
User’s logon 
 id
Id.
logonProvider
User logon provider
The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system).
eventName
Name 
The name of the event to trigger.
testMode
Trigger the test mode or not work items
Determines whether the event should also trigger for items in test mode.
inputData
Event 
 Data 
data in XML format. This can be null.
culture
Culture 
The culture preference. 
 Can 
This can be null.
Example Call
...
 Code Block
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
}
...
 Code Block
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...


...

["716F8FCB-98C2-4591-8C43-043D54DEAADA"]

...
Query
Query is xml The query is an XML-based string that specifies the requested desired result set. If not specified provided, the default query is performedexecuted.
Query definition uses The query can be defined using the following column names to be specified as for specifying the result set column namecolumns, criteria, and order.
Worklist Columns
Name
Description
Id
Unique identifier of the work item
 identifier
.
Name
Name of the work item.
Caption
Localized 
Localised caption of the work item.
State
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 
 is 
has occurred.
DeadlineDate
Deadline date. Can be null.
NextReminderDate
Next reminder date. Can be null.
SentReminders
Number of reminders sent
 reminders
.
Instructions
Instructions 
 of 
for the work item.
InstanceId
Unique identifier of the instance
 identifier
.
PreviousWorkItemId
Previous id number 
Identifier of the previous work item. Can be null.
ActionId
Unique identifier for the action
 identifier
. Can be null.
CompletedById
Id 
 number 
 of 
 completed by user
the user who completed the work item. Can be null.
CompletedBy
Display name of 
 completed by user
the user who completed the work item. Can be null.
Number
Instance number.
Priority
Instance priority
Priority of the instance.
ProcessId
The Id 
 number 
 of the process.
ProcessName
Name 
The name of the process.
FromId
Id number 
Identifier of 
 initiator 
the initiating user. Can be null.
From
Display name of the initiator user. Can be null.
FolderId
Id number 
Identifier of the related folder
 id
.
FolderName
Name of the related folder.
AssignedTo
List of users assigned 
 users
to the work item.
VersionNumber
Version number of the related process.
VersionId
Version Id 
 number 
 of the related process
 version
.
TestMode
A boolean that specifies 
Boolean indicating whether the instance is in test mode
 or not
.
Instance.Start
Start date of the instance.
Instance.State
State of the instance.
Query contains the following sections;
Columns
List A list of column names that requested. to be included in the result set.
Where
List A list of criteria to be performed. Criteria name can be specified from for filtering the results. The criteria names must correspond to column names.
Order
List of order to be performed. Order name can be specified from A list of sorting criteria. The order names must also correspond to column names.
Example Query Xml
 Code Block
languagexml
<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>
...
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
Caller system identifier
A unique key used to authenticate and authorise the calling system.
logonId
User 
User’s logon 
 id
Id.
logonProvider
User logon provider
The authentication provider used for user login (e.g., 'Organization' for Emakin's default login system).
process
Name 
The name or Id 
 number 
 of the process related to the decision.
model
Name 
The name or 
 Id number 
ID of the decision model to be evaluated.
decision
Name 
The name or Id 
 number 
 of the specific decision to be executed within the model.
inputData
Decision input data. Xml or Json 
Input data for the decision, provided as either an XML or JSON string.
Example Call
...
 Code Block
...
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>"
}
...
 Code Block
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 26


...
{"Dish":"Spareribs"
...
}