1. API & INTEGRATION

API & INTEGRATION

Version Date Author Comments
1.0.1 4.04.2018 Viktor Kushnir
1.0.2 6.07.2018 Viktor Kushnir json changesAddProject method changed

Entities

Project

Describes the project

Field Description
id Unique identifier
name Project’s name
manager Project manager’s name
resourcepool.id Id of resource pool should be used for this project
steps Array of Step entities

Resource pool

Describes the resource pool

Field Description
id Unique identifier
resources Array of Resource entities
groups Array of Group entities

Step

Base entity for Task, Summary, Milestone, Start of Project, End of Project

Field Description
id Unique identifier
key Identified which will be shown in Epicflow site
type Must be “task”
parent Id of parent summary, can be empty
name Name of task
predecessors Array of Predecessor entities, uses to describe relations between tasks
notes Task notes, will be visible at Epicflow site
link Http link to the issue in external system 

Task

Step entity, describes Task.

Field Description
assignments Array of Assignment, uses to describe assignments
readytostart Marks if task can be started, default value – false

Example:

{

   “id”: “89827837-7357-44e7-9469-98910ac314cf”,

   “key”: “visible key”,

   “type”: “task”,

   “parent”: {

       “id”:”{summaryid}” //”parent summary id”,

   },

   “name”: “name”,

   “predecessors”: [

       //array of predecessor

   ],

   “assignments”: //array of assignments

   [

   ],

   “notes”: “”,

   “readytostart”: true,

   “link”: “http link”

}

Summary

Step entity, describes Summary.

Field Description
start Start date of summary, can be empty
end End date of summary, can be empty

Example:

{

   “id”: “ef332fa1-b315-4ee4-9370-e822f7897958”,

   “key”: “visible key”,

   “type”: “summary”,

   “parent”: {

       “id”:”{summaryid}” //”parent summary id”,

   },

   “name”: “name”,

   “predecessors”: [

       //array of predecessor

   ],

   “notes”: “”,

   “link”: “http link”,

   “start”: “2018-01-09”,

   “end”: “2018-07-21”

}

Milestone

Step entity, describes the Milestone.

Field Description
deadline Deadline of milestone, can be empty

Example:

{

   “id”: “95668aae-2dac-490d-93bf-931b87346005”,

   “key”: “visible key”,

   “type”: “milestone”,

   “parent”: {

       “id”:”{summaryid}”,

   },

   “name”: “name”,

   “predecessors”: [

       //array of predecessor

   ],

   “notes”: “”,

   “link”: “http link”,

   “deadline”: “2019-01-20”

}

Start of project

Milestone entity, describes the Start milestone of project. Can be present just once per project. If omitted – Epicflow will calculate it automatically.

Example:

{

   “id”: “c77b6a51-19be-4646-9ccd-a30741442290”,

   “key”: “visible key”,

   “type”: “projectstart”,

   “parent”: {

       “id”:”{summaryid}”,

   },

   “name”: “name”,

   “predecessors”: [

       //array of predecessor

   ],

   “notes”: “”,

   “link”: “http link”,

   “deadline”: “2019-01-20”

}

End of project

Milestone entity, describes the end milestone of project. If omitted – Epicflow will calculate it automatically.

Example:

{

   “id”: “e83af0cd-1d13-44e4-8d21-0d00014f7c7d”,

   “key”: “visible key”,

   “type”: “projectend”,

   “parent”: {

       “id”:”{summaryid}” //”parent summary id”,

   },

   “name”: “name”,

   “predecessors”: [  //array of predecessor

   ],

   “notes”: “”,

   “link”: “http link”,

   “deadline”: “2019-01-20”

}

Predecessor

Describes the relation between tasks

Field Description
id Predecessor id, can be id of Task, Summary, Milestone, Start of Project, End of Project

Example:

{

   “id”:”{stepId}”

}

Assignment

Describes the assignment for specific task

Field Description
id Unique identifier within the task
resource.id Unique resource id
group.id Unique group id
remaining Remaining work, in hours
actual Completed work, in hours
units Assigned units, default value 1.

Example:

{

   “id”: “1”,

   “resource”: {

       “id”: “resourceId”

   },

   “group”: {

       “id”: “groupId”

   },

   “remaining”: 25.5,

   “actual”: 74.5,

   “units”: 1    

}

Resource

Describes the resource

Field Description
id Unique identifier
name Resource name
groups Array of Group
email Resource’s email
start The date when resource became available
end The date since resource become unavailable

Example:

{

“id”:”196bcd63-0809-41c8-aa90-77a68449789b”,

“name”:”Craig Wells”,

       “groups”:[

        {

           “id”:”d5333a04-8704-4af1-b88c-6f90bfb5ca3b”

        },

        {

           “id”:”8b658cfd-89b6-4c09-a9e1-59660846ac22″

        }

       ],

“email”:”craig.wells@yahoo.com”,

“start”:”2018-01-20″,

“end”:null

}

Group

Describes the group

Field Description
id Unique identifier
name Resource name
start The date when group became available
end The date since group become unavailable
ucltgroup Marks group as uclt group, default value – 0

Example:

{

“id”:”b0ac41f8-0e5e-4a49-b3f1-5f2c967c71cb”,

“name”:”ExternalGroup”,

“start”:”2018-01-20″,

“end”:”2020-09-29″

}

Authentication

Authentication POST auth/1/session

Returns session id, which must be used for all API requests as header – EpicflowSessionId.

Request

curl -i -X POST -H “Content-Type:application/json” https://epicflow.net/auth/1/session

{

   user:”{login}”,

   password:”{password}”

}

Example:

Response

{

   “sessionid”: “0804e9b3-afd4-43bc-ae9f-f9fa6faaac7c”

}

Project

Get all project GET rest/api/1/external/project

Returns all projects

Example:

Request:

curl -i -X GET -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/project

Response:

[

   {

“id”:”534ad934-39ca-438b-a11a-d97ef953b2cd”,

“name”:”Example”,

“manager”:”John Smith”,

“resourcepool”:{

   “id”:”exampleResourcePoolId”

},

“steps”:

[

//Step entities

]

   }

]

Get project

GET rest/api/1/external/project/{id}

Returns the project.

Example:

Request:

curl -i -X GET -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/project/{projectId}

Response:

{

   “id”:”534ad934-39ca-438b-a11a-d97ef953b2cd”,

   “name”:”Example”,

   “manager”:”John Smith”,

   “resourcepool:{

“id”:”afb43f3b-6642-4cfd-8ee4-e99d71d7ca76″

   },

   “steps”:

   [

//Step entities

   ]

}

Add project

PUT rest/api/1/external/project

Adds project to Epicflow

Example:

Request:

curl -i -X PUT -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/project

{

   “id”:”534ad934-39ca-438b-a11a-d97ef953b2cd”,

   “name”:”Example”,

   “manager”:”John Smith”,

   “resourcepool:{

“id”:”afb43f3b-6642-4cfd-8ee4-e99d71d7ca76″

   },

   “steps”:

   [

//Step entities

   ]

}

Update project

POST rest/api/1/external/project/{id}

Full update of project.

Example:

curl -i -X POST -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/project/{projectId}

{

   “name”:”Example”,

   “manager”:”John Smith”,

   “resourcepool:{

“id”:”afb43f3b-6642-4cfd-8ee4-e99d71d7ca76″

   },

   “steps”:

   [

//Step entities

   ]

}

Update project

PATCH rest/api/1/external/project/{id}

Modify specific field in project.

Example:

curl -i -X PATCH -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/project/{projectId}

{

   “manager”:”Joan Smith”

}

Delete project

DELETE rest/api/1/external/project/{id}

Deletes the project.

Example:

curl -i -X DELETE -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/project/{projectId}

ResourcePool

Add or modify resources or groups.

 

Base url – api/1/external/resourcepool

 

Get resource pools

GET rest/api/1/external/resourcepool

Returns all resource pools

Example:

Request:

curl -i -X GET -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool

 

Response:

[

   {

   “id”:”afb43f3b-6642-4cfd-8ee4-e99d71d7ca76″,

   “resources”:[

           {

               “id”:”69b26672-bb60-43df-a535-63cc5c2ab946″,

               “name”:”Maddison Hamilton”,

               “groups”:[

                   {

                       “id”:”d5333a04-8704-4af1-b88c-6f90bfb5ca3b”

                   },

                   {

                       “id”:”8b658cfd-89b6-4c09-a9e1-59660846ac22″

                   }

               ]

               “email”:”maddison.h@mail.com”,

               “startdate”:”2006-01-20″,

               “enddate”:null

           },

           {

               “id”:”518d95c1-e5d4-413b-99a8-55bad737bb75″,

               “name”:”Chloe Holmes”,

               “groups”:[

                   {

                       “id”:”d5333a04-8704-4af1-b88c-6f90bfb5ca3b”

                   },

                   {

                       “id”:”8b658cfd-89b6-4c09-a9e1-59660846ac22″

                   }

               ],

               “email”:”chloe@mail.com”,

               “startdate”:”2006-01-20″,

               “enddate”:”2022-05-12″

           }

       ],

   “groups”:[

           {

               “id”:”d5333a04-8704-4af1-b88c-6f90bfb5ca3b”,

               “name”:”Main Staff”,

               “startdate”:”2003-01-01″,

               “enddate”:null

           },

           {

               “id”:”8b658cfd-89b6-4c09-a9e1-59660846ac22″,

               “name”:”Temp group”,

               “startdate”:”2018-01-01″,

               “enddate”:”2018-09-29″

           },

       ]

   }

]

Add resource pool

PUT rest/api/1/external/resourcepool

Adds resource pool

Example:

Request:

curl -i -X PUT -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool

   

   “id”:”ExampleResourcePool”,

   “resources”:[

           {

               “id”:”69b26672-bb60-43df-a535-63cc5c2ab946″,

               “name”:”Maddison Hamilton”,

               “groups”:[

                   {

                       “id”:”d5333a04-8704-4af1-b88c-6f90bfb5ca3b”

                   },

                   {

                       “id”:”8b658cfd-89b6-4c09-a9e1-59660846ac22″

                   }

               ],

               “email”:”maddison.h@mail.com”,

               “startdate”:”2006-01-20″,

               “enddate”:null

           },

           {

               “id”:”518d95c1-e5d4-413b-99a8-55bad737bb75″,

               “name”:”Chloe Holmes”,

               “groups”:[

                   {

                       “id”:”d5333a04-8704-4af1-b88c-6f90bfb5ca3b”

                   },

                   {

                       “id”:”8b658cfd-89b6-4c09-a9e1-59660846ac22″

                   }

               ],

               “email”:”chloe@mail.com”,

               “startdate”:”2006-01-20″,

               “enddate”:”2022-05-12″

           }

       ],

   “groups”:[

           {

               “id”:”d5333a04-8704-4af1-b88c-6f90bfb5ca3b”,

               “name”:”Main Staff”,

               “startdate”:”2003-01-01″,

               “enddate”:null

           },

           {

               “id”:”8b658cfd-89b6-4c09-a9e1-59660846ac22″,

               “name”:”Temp group”,

               “startdate”:”2018-01-01″,

               “enddate”:”2018-09-29″

           }

       ]

   }

Update resource pool

POST rest/api/1/external/resourcepool/{id}

Example:

Request:

curl -i -X PUT -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{id}

{

   “id”:”afb43f3b-6642-4cfd-8ee4-e99d71d7ca76″,

   “resources”:[

           {

               “id”:”69b26672-bb60-43df-a535-63cc5c2ab946″,

               “name”:”Maddison Hamilton”,

               “groups”:[

                   {

                       “id”:”d5333a04-8704-4af1-b88c-6f90bfb5ca3b”

                   }

               ],

               “email”:”maddison.h@mail.com”,

               “startdate”:”2006-01-20″,

               “enddate”:null

           }

       ],

   “groups”:[

           {

               “id”:”d5333a04-8704-4af1-b88c-6f90bfb5ca3b”,

               “name”:”Main Staff”,

               “startdate”:”2003-01-01″,

               “enddate”:null

           }

   ]

}

Update resource pool

PATCH rest/api/1/external/resourcepool/{id}

Example:

Request:

curl -i -X PATCH -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{id}

{

   “id”:”afb43f3b-6642-4cfd-8ee4-e99d71d7ca76″,

   “resources”:[

           {

               “id”:”196bcd63-0809-41c8-aa90-77a68449789b”,

               “name”:”Craig Wells”,

               “groups”:[

                   {

                       “id”:f7b037b8-dc7c-4c44-a9de-fd1896124c3a”

                   }

               ],

               “email”:”craig.wells@yahoo.com”,

               “startdate”:”2018-01-20″,

               “enddate”:null

           }

       ]

}

Delete resource pool

DELETE rest/api/1/external/resourcepool/{id}

Example:

Request:

curl -i -X DELETE -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{id}

Groups

Base url  api/1/resourcepool/{resourcepoolid}

Get groups for specific resource pool

GET {groupurl}/group

Example:

Request:

curl -i -X GET -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{resourcepoolid}/group

[

   {

       “id”:”d5333a04-8704-4af1-b88c-6f90bfb5ca3b”,

       “name”:”Main Staff”,

       “startdate”:”2003-01-01″,

       “enddate”:null

   },

   {

       “id”:”8b658cfd-89b6-4c09-a9e1-59660846ac22″,

       “name”:”Temp group”,

       “startdate”:”2018-01-01″,

       “enddate”:”2018-09-29″

   }

]

Add group

PUT {groupurl}/group

Example:

Request:

curl -i -X PUT -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{resourcepoolid}/group

{

   “id”:”b0ac41f8-0e5e-4a49-b3f1-5f2c967c71cb”,

   “name”:”ExternalResource”,

   “startdate”:”2018-01-01″,

   “enddate”:”2020-09-29″

}

Get group

GET {groupurl}/group/{id}


Example:

 

curl -i -X GET -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{resourcepoolid}/group/{groupId}

Response:

{

   “id”:”b0ac41f8-0e5e-4a49-b3f1-5f2c967c71cb”,

   “name”:”ExternalResource”,

   “startdate”:”2018-01-01″,

   “enddate”:”2020-09-29″

}

Full update

POST {groupurl}/group/{id}

Example:

 

curl -i -X POST -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{resourcepoolid}/group/{groupId}

Request:

{

   “id”:”b0ac41f8-0e5e-4a49-b3f1-5f2c967c71cb”,

   “name”:”ExternalGroup”,

   “startdate”:”2017-01-01″,

   “enddate”:”2020-09-29″

}

 

Partial update

PATCH {groupurl}/group/{id}

Example:

 

curl -i -X PATCH -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{resourcepoolid}/group/{groupId}

Request:

{

   “startdate”:”2016-02-01″

}

Delete group

DELETE {groupurl}/group/{id}

Example:

 

curl -i -X DELETE -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{resourcepoolid}/group/{groupId}

Resource

Base url for all requests – api/1/external/resourcepool/{resourcepoolid}

Get resource

GET {resourceurl}/resource/{id}

Example:

curl -i -X GET -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{resourcepoolid}/resource/{resourceId}

Response

{

   “id”:”518d95c1-e5d4-413b-99a8-55bad737bb75″,

   “name”:”Chloe Holmes”,

   “groups”:[

             {

                 “id”:”d5333a04-8704-4af1-b88c-6f90bfb5ca3b”

             },

             {

                 “id”:”8b658cfd-89b6-4c09-a9e1-59660846ac22″

             }

   ],

   “email”:”chloe@mail.com”,

   “startdate”:”2006-01-20″,

   “enddate”:”2022-05-12″

}

 

Add resource

PUT {resourceurl}/resource

Example:

curl -i -X PUT -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{resourcepoolid}/resource

Request:

{

   “id”:”40d295ba-45ce-46c7-9a74-a61ee1dbfa5e”,

   “name”:”Sara Bradley”,

   “groups”:[

       {

            “id”:”d5333a04-8704-4af1-b88c-6f90bfb5ca3b”

       },

       {

            “id”:”8b658cfd-89b6-4c09-a9e1-59660846ac22″

       }

   ],

   “email”:”sara.b@mail.com”,

   “startdate”:”2006-01-20″,

   “enddate”:”2022-05-12″

}

 

Full update

POST {resourceurl}/resource/{id}

Example:

curl -i -X POST -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{resourcepoolid}/resource/{resourceId}

Request

{

   “id”:”40d295ba-45ce-46c7-9a74-a61ee1dbfa5e”,

   “name”:”Sara Bradley”,

   “groups”:[

       {

            “id”:”d5333a04-8704-4af1-b88c-6f90bfb5ca3b”

       },

       {

            “id”:”8b658cfd-89b6-4c09-a9e1-59660846ac22″

       }

   ],

   “email”:”sara.b@mail.com”,

   “startdate”:”2006-01-20″,

   “enddate”:”2022-05-12″

}

Partial update

PATCH {resourceurl}/resource/{id}

Example:

curl -i -X PATCH -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{resourcepoolid}/resource/{resourceId}

Request

{

   “name”:”Sara J. Bradley”

}

Delete resource

DELETE {resourceurl}/resource/{id}

Deletes specific resource.

Example

curl -i -X DELETE -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/external/resourcepool/{resourcepoolid}/resource/{resourceId}

Priority

Get all priorities per project GET /priority

Returns priorities per project

curl -i -X GET -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/priority

Response

 

[{

       “projectid”: “534ad934-39ca-438b-a11a-d97ef953b2cd”,

       “priority”: [{

               “taskpriority”: {

                   “taskid”: “8a52a186-27ae-48d6-9017-b946eaf8b4a3”,

                   “priority”:102.4

               },

               “taskpriority”: {

                   “taskid”: “5b52a146-27ae-3b03-1026-7a46eaf8b4a2”,

                   “priority”:89.1

               }

           }

       ]

   }

]

Get task for specific project GET /priority/{projectId}

Returns priorities for specific project

 

curl -i -X GET -H “Content-Type:application/json” -H “EpicflowSessionId:{your id}” https://epicflow.net/rest/api/1/priority/{projectId}

Response

{

   “projectid”: “534ad934-39ca-438b-a11a-d97ef953b2cd”,

   “priority”: [{

       “taskpriority”: {

           “taskid”: “8a52a186-27ae-48d6-9017-b946eaf8b4a3”,

           “priority”:102.4

        },

        “taskpriority”: {

            “taskid”: “5b52a146-27ae-3b03-1026-7a46eaf8b4a2”,

            “priority”:89.1

         }

       }

   ]

}

HTTP response status codes

Status 200 – OK – request applied

Status 201 – Created – item created

Status 401 – Unauthorized – session id invalid or expired

Status 403 – Forbidden – request forbidden

Status 404 – Not found – requested item not found

Status 409 – Conflict, Already present – cannot add item, already present