Versions Compared

Old Version 21

changes.mady.by.user Ertan Tike

Saved on

compared with

New Version Current

changes.mady.by.user Ertan Tike

Saved on

Key

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

...

Infrastructure services can be accessed from "http(s)://<mydomain>.emakin.com/rest.asmx" url. Depending on call style service  Service methods can be called in soap or rest format. If you prefer the use SOAP related WSDL document can be accessed from http://<mydomain>.emakin.com/rest.asmx?WSDL

Table of Contents

Authentication

Infrastructure service calls requires an API Key to execute and get be acquired from system administrator.

Some of methods requires "logonId" and "logonProvider" parameters to act as user's behalf. Logon provider specifies the registered open auth logon provider. If default emakin login system is used 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.

Token generating login methods always returns tokens in registered API Key scope. 

Services

GetToken

Generates an authentication token to authorize users later. Generated token can be use to "auth" parameter to authorise users without login requirement.

Required Scope

login

Parameters

Parameter Name

Description

apiKey

Caller system identifier.

logonId

User logon id

logonProvider

User logon provider.

Example Call

...

Code Block
POST http://

...

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
...
GetTokenFromUserInfo
Generates an authentication token from the user info. If user is not found and logon provider auto registration is enabled, user is automatically created and returns an authentication token for registered user, otherwise returns authentication token if user was registered before.
Required Scope
login
Parameters
Parameter Name
Description
apiKey
Caller system identifier.
logonId
userInfo
User 
 logon id
information
logonProviderUser logon provider.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.
Example Call
...
Example Call
 Code Block
POST http://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 user's worklist. Tag parameter specifies the identifier of which list should be returned.
Required Scope
worklist_read
Parameters
Parameter Name
Description
apiKey
Caller system identifier.
logonId
User logon id
logonProvider
User logon provider.
tag
Worklist identifier. If set to null default inbox is returned.
start
Start number of list. Use 0 to start from beginning.
maxLength
Limit of number of rows in list. Use -1 to get all rows.
queryXml
Optional query xml value. See Rest Services#Query for more details.
Example Call
 Code Block
POST http://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
      },
    
...
GetWorklistCount
Returns number of records in worklist. You can use this method to specify paging parameters in GetWorkList method.
Parameters
...
Example Call
...
  {
         "Id":"796a34c6-fd2e-450e-a2af-8124ea68f8ca",
         "Caption":"A new other task",
         "Start":"/Date(1445512843034)/",
         "End":null,
         "
...
Instructions":"Please 
...
complete.",
       
...
  "State":
...
"
...
Waiting",
...

  
...
 
...
      "
...
Number":12468
 
...
 
...
 
...
 
...
 
...
 }
]
 No Format
HTTP/1.1 200 OK
Cache-Control: private, max-age=0
Content-Type: application/json; charset=utf-8
Date: Mon, 26 Oct 2015 21:15:17 GMT
Content-Length: 8
 
{
   "d":50
}
GetWorkItem
Gets workitem information to display or complete with action.
Parameters
...
GetWorklistCount
Returns number of records in the worklist. You can use this method to specify paging parameters in the GetWorkList method.
Required Scope
worklist_read
Parameters
Parameter Name
Description
apiKey
Caller system identifier.
logonId
User logon id
logonProvider
User logon provider.
id
tag
Work item 
Worklist identifier. 
readOnlySet true to fetch work item read only. Default is false
If set to null, default inbox is returned.
queryXml
Optional query xml value. See Rest Services#Query for more details.
Example Call
...
 Code Block
...
POST http://
...
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.
Required Scope
worklist_read
Parameters
Parameter Name
Description
apiKey
Caller system identifier.
logonId
User logon id
logonProvider
User logon provider.
id
Work item identifier.
readOnly
Set true to fetch work item read only. Default is false.
Example Call
 Code Block
POST http://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
...
SelectAction
Selects an action of a work item and returns an array of next work item identifiers.
Required Scope
workitem_action
Parameters
RequestResponse No FormatPOST http://ertan.emakin2.com/rest.asmx/getWorkItemData HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: ertan.emakin2.com
Content-Length: 124

Parameter Name
Description
apiKey
Caller system identifier.
logonId
User logon id
logonProvider
User logon provider.
id
Work item identifier.
Example Call
action
Action identifier.
data
XML data. Can be null. (There is no merge operation.The whole form data should be sent, otherwise
the form data is replaced with the new data. The data can be retrieved by the GetWorkItemData method.
The final data should be send inside of a form element. e.g. <form><Data>...</Data></form>)
comments
User comments
Example Call
 Code Block
POST http://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=utf-8

...


...
SelectAction
Selects an action on a work item and returns array of next work item identifiers.
Parameters
...
[ "716F8FCB-98C2-4591-8C43-043D54DEAADA" ]

InitiateByProcess
Initiates a new process instance with specified parameters and returns the Id number of work item.
Required Scope
process_initiate
Parameters
Parameter Name
Description
apiKey
Caller system identifier.
logonId
User logon id
logonProvider
User logon provider.
idWork item identifier.actionAction identifierUser comments
process
Name or Id number of the process
task
Name or Id number of the task
version
Version number or id of process. Can be null.
data
XML data. Can be null.
comments
culture
Culture preference. Can be null.
Example Call
...
 Code Block
POST http://
...
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.
When testing this method with Soap UI, you must include the xml for the data parameter inside <![CDATA[]]>, for example: <![CDATA[<pool><myField>ABC</myField></pool>]]>
Parameters
...
ExecuteModule
Executes the specified module and returns result value of module function.
Required Scope
module_execute
Parameters
Parameter Name
Description
apiKey
Caller system identifier.
logonId
User logon id
logonProvider
User logon provider.
process
Name or 
 Id 
id number of process
task
module
Name 
 or Id number of taskdataXML data. Can be null.cultureCulture preference. Can be null.
Example Call
RequestResponsenoformat
of module to be call.
function
Name of function to be call.
arguments
Array of function parameters.
Example Call
 Code Block
POST http://
...
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 all processes and returns array of id number of triggered work items. When there is no listener return value is a empty array.
Required Scope
event_trigger
Parameters
Parameter Name
Description
apiKey
Caller system identifier.
logonId
User logon id
logonProvider
User logon provider.
eventName
Name of event
testMode
Trigger the test mode or not work items
inputData
Event Data in XML can be null.
culture
Culture preference. Can be null.
Example Call
...
 Code Block
POST http://
...
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 based string that specifies the requested result. If not specified, default query is performed.
Query definition uses the following column names to be specified as a result set column name, criteria and order.
Worklist Columns
Name
Description
Id
Unique work item identifier
Name
Name of a work item
Caption
Localized caption of a work item.
State
State of work a  item.
Start
Start date of a work item
End
End date of a 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 sent reminders
Instructions
Instructions of work item
InstanceId
Unique instance identifier
PreviousWorkItemId
Previous id number of work item. Can be null.
ActionId
Unique action identifier. Can be null.
CompletedById
Id number of completed by user. Can be null.
CompletedBy
Display name of completed by user. Can be null.
Number
Instance number
Priority
Instance priority
ProcessId
Id number of process
ProcessName
Name of process
FromId
Id number of initiator user. Can be null.
From
Display name of initiator user. Can be null.
FolderId
Id number of related folder id.
FolderName
Name of related folder.
AssignedTo
List of assigned users
VersionNumber
Version number of related process
VersionId
Id number of related process version
TestMode
A boolean that specifies instance is in test mode or not.
Instance.Start
Start date of instance
Instance.State
State of instance
Query contains the following sections;
...
List of order to be performed. Order name can be specified from column names.
Example Query Xml
...
languagexml
...
name can be specified from 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="IdDeadlineDate"/>
        <Column Expression="InstructionsEnd"/>
        <Column Expression="StateFolderName"/>
        <Column Expression="FromIdNumber"/>
    </Columns>
    <Column<Where>
        <Criteria>
            <Criteria Expression="From"/>Caption" Comparison="Like">
                <Column Expression="SentReminders"/><Value>My Task*</Value>
           <Column Expression="HasHistory"/></Criteria>
        <Column Expression="Caption"/></Criteria>
    </Where>
   <Column Expression="Start"/> <Order>
        <Column<Order Expression="DeadlineDate"Start" Type="Descending" />
        <Column Expression="End"/>
        <Column Expression="FolderName"/>
        <Column Expression="Number"/>
    </Columns>
    <Where>
        <Criteria>
            <Criteria Expression="Caption" Comparison="Like">
   </Order>
</Query>
Decision
Returns the decision result.
Required Scope
decision_execute
Parameters
Parameter Name
Description
apiKey
Caller system identifier.
logonId
User logon id
logonProvider
User logon provider.
process
Name or Id number of the process
model
Name or Id number of the decision model
decision
Name or Id number of the decision
inputData
Decision input data. Xml or Json string.
Example Call
 Code Block
POST https://mydomain.emakin.com/rest/v1/decision

{
     "apiKey": "",
     <Value>My Task*</Value>"logonId": "user@emakin.com",
     "logonProvider": "Organization",
     </Criteria>
 "process" : "Decision",
      </Criteria>
"model" : "dinner",
   </Where>  "decision"   <Order>: "Dish",
     "inputData": "<pool><Season>Fall</Season><NumberOfGuests>2</NumberOfGuests></pool>"
 <Order Expression="Start" Type="Descending" />
    </Order>
</Query>}
 Code Block
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 26

{"Dish":"Spareribs"}