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
1.0.3	01.08.2024	Andrew Sapon	Resource Availability API entities Adjusted Methods description

Prerequisite

Be aware that “Resource Availability API” by default is switched off. Please contact support department to have configured access to it for you.

Due to several security issues TLS versions 1.0 and 1.1 are set as deprecated and disallowed. TLS version 1.2 or 1.3 should be used instead.

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
tags	Array of Tags
attributes	Array of Attributes

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
tags	Array of Tags
attributes	Array of Attributes

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
startAfter	Constraint date for the Item, can be empty “2025-02-20T00:00:00+00:00”
finishBefore	Constraint date for the Item, can be empty “2025-02-20T00:00:00+00:00”

Example:

{

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

   “key”: “visible key”,

   “type”: “task”,

   “parent”: {

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

   },

   “name”: “name”,

   “infoField1”: “infoField1”,

   “infoField2”: “infoField2”,

   “infoField3”: “infoField3”,

   “predecessors”: [

       //array of predecessor

   ],

   “assignments”: //array of assignments

   [

   ],

   “tag”:

   [

   “tag1”, “tag2”, …

   ],

   “attributes”:

   [

   “externalCode1”, “externalCode2”, …

   ],

   “notes”: “”,

   “readytostart”: true,

   “link”: “http link”,

   “startAfter”: “2019-11-20”,

   “finishBefore”: “2020-01-10”

}

Summary

Step entity, describes Summary.

Field	Description
start	Start date of summary, can be empty
end	End date of summary, can be empty
startAfter	Constraint date for the Item, can be empty “2025-02-20T00:00:00+00:00”
finishBefore	Constraint date for the Item, can be empty “2025-02-20T00:00:00+00:00”

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”,

   “tag”:

   [

   “tag1”, “tag2”, …

   ],

   “attributes”:

   [

   “externalCode1”, “externalCode2”, …

   ],

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

   “end”: “2018-07-21”,

   “startAfter”: “2019-11-20”,

   “finishBefore”: “2020-01-10”

}

Milestone

Step entity, describes the Milestone.

Field	Description
deadline	Deadline of milestone, can be empty
baselineDeadline	set\update Baseline values “0001-01-01T00:00:00”

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”,

   “tag”:

   [

   “tag1”, “tag2”, …

   ],

   “attributes”:

   [

   “externalCode1”, “externalCode2”, …

   ],

   “deadline”: “2019-01-20”,

   “baselineDeadline”: “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.
averageWorkdayHours	Integer, that defines average work day hours per assignment. Overrides availability of assigned resource.
baselineWork	set\update Baseline values, in hours

Example:

{

   “id”: “1”,

   “resource”: {

       “id”: “resourceId”

   },

   “group”: {

       “id”: “groupId”

   },

   “remaining”: 25.5,

   “actual”: 74.5,

   “units”: 1,    

   “averageWorkdayHours”:13,    

   “baselineWork”: 70

}

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 projects

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 Active projects Only

GET rest/api/1/external/project?IncludeActive=true

Get Inactive projects Only

GET rest/api/1/external/project?IncludeInactive=true

Get Closed projects Only

GET rest/api/1/external/project?IncludeClosed=true

Get Archived projects Only

GET rest/api/1/external/project?IncludeArchived=true

Get projects of several different categories

GET rest/api/1/external/project?IncludeActive=true&IncludeClosed=true&IncludeArchived=true

Get Project Data>

To get listing of Projects’ Id you can define filtering by specific field that must be displayed. Be aware that all other fields except “id” are going to be be empty.

Get only Projects’ id

GET rest/api/1/external/project?fields=id

Example: Get only Inactive Projects’ id

GET rest/api/1/external/project?IncludeInactive=true&fields=id

Get project by Id

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

   ]

}

Update project

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

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”,

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

               “end”: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”,

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

               “end”:”2022-05-12″

           }

       ],

   “groups”:[

           {

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

               “name”:”Main Staff”,

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

               “end”:null

           },

           {

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

               “name”:”Temp group”,

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

               “end”:”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”,

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

               “end”: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”,

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

               “end”:”2022-05-12″

           }

       ],

   “groups”:[

           {

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

               “name”:”Main Staff”,

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

               “end”:null

           },

           {

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

               “name”:”Temp group”,

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

               “end”:”2018-09-29″

           }

       ]

   }

Update resource pool

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

Example:

Request:

curl -i -X POST -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”,

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

               “end”:null

           }

       ],

   “groups”:[

           {

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

               “name”:”Main Staff”,

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

               “end”: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”,

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

               “end”: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”,

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

       “end”:null

   },

   {

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

       “name”:”Temp group”,

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

       “end”:”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”,

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

   “end”:”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”,

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

   “end”:”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”,

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

   “end”:”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:

{

   “start”:”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”,

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

   “end”:”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”,

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

   “end”:”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”,

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

   “end”:”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

         }

       }

   ]

}

Resource Availability API entities

Work with Availability API id one via next procedure

• Initialization of API for Resource (usually one time action)
• Availability Upload

I. INITIALIZATION

Before availability update for any of previously created resources, such should be introduced via API.

Resource entity, describes Resources.

Field	Description
resourceName	String, contains User name Mandatory.
localPersonnelNumber	String, unique Id of user in HR system Mandatory.
contactDetails	String, defines User Email Mandatory.
hireDate	datetime, defines Start date for the User’s Availability Mandatory.
holidayCalendar	String, Id of the required Calendar (Additional Calendars must be configured separately ) Default Company calendar will be used if Empty Optional.
skills	Array of String, Ids of User’s skills (skill must be configured separately) Optional.
contractedHours	Decimal, Total working hours per working week. Mandatory.
availability	Integer, allowed values from 0 till 100. Used to specify availability of the User in relation to “contractedHours” contractedHours*availability/100 Mandatory.
transferToEpicflow	Boolean, shows should Epicflow import/update user in Epicflow, if False – this record will be ignored. Mandatory.
terminationDate	datetime, defines End date of the User’s Availability (when person retire from his position) Optional.

Set info about user

POST /api/user

Header

Content-Type: application/json

This POST method is used to create or update user.

It should be always executed at least once before usage of Availability upload method.

• If required resource doesn’t exist in Epicflow, it will be created.
• If resource present in Epicflow, then method will add required information. In this case Email is used as unique ID to define <localPersonnelNumber> for the user at first method execution.

Example

 
{
    "resource": [{
            "resourceName": "SomeTestUserName",
            "localPersonnelNumber": "2040003",
            "contactDetails": "TestName.s3@epicflow.com",
            "hireDate": "2021-01-04T00:00:00.000",
            "holidayCalendar": "",
            "additionalSkill": "1",
            "contractedHours": "40",
            "availability": "100",
            "transferToEpicflow": "true"
        },
        .....
    ]
}

Additionally, method supports next none obligatory fields

Field	Description
functionalManagerId	String, localPersonnelNumber of manager for the User
terminationDate	nullable datetime, End date for the User’s Availability

Method usage rules

Be aware, that

• Before availability update for any of previously created resources, such should be introduced via API.

II. AVAILABILITY Upload

Resource entity, describes Resource’s Absence Data.

Set info about user

POST /api/absence

Header

Content-Type: application/json

Field	Description
personId	Can be used at further adjustments for the previously created user’s fields value. Must be the same value as localPersonnelNumber from previous method
scheduledLeaves	Array of ScheduledLeaves, contains leaves data

Field	Description
quantityinHours	mandatory field of decimal, absence hours. This value taked into account only if “startDate” equal to “endDate”
startDate	mandatory field of date type, Start of Leave
endDate	mandatory field of date type, End of Leave

Example

 
{
    "resource": [{
            "resourceName": "SomeTestUserName",
            "personId": "2040003",
            "scheduledLeaves": [{
                    "startDate": "2022-02-28T00:00:00.000",
                    "endDate": "2022-02-28T00:00:00.000",
                    "quantityinHours": "5"
                },{
                    "startDate": "2022-02-29T00:00:00.000",
                    "endDate": "2022-02-29T00:00:00.000",
                    "quantityinHours": "5"
                }, { 
                    "startDate": "2022-12-30T00:00:00.000",
                    "endDate": "2023-01-200T00:00:00.000",
                    "quantityinHours": "0"
                },
		.....
            ]
        },
	....
    ]
}

Method usage rules

Be aware, that

• when range is specified, no <quantityinHours> usage is required. System will ignore any value for <quantityinHours> if range is specified for more than one day. For such case availability will be set “0” automatically.
• In case if partial availability it is required to be set per day, <quantityinHours> filed should be used. Availability will be calculated as 8 working hour minus <quantityinHours>. For example, if availability of 3 hours must be defined, <quantityinHours> must be set as 5.
• In case if partial availability is required to be set for a range, then it should be defined for each day separately. Otherwise “0” will be applied automatically.
• Any information present in json will overwrite previously provided. In case if some range won’t be present in next iteration of API method invoke, it will be erased.
• Availability is allowed to be defined for two months in the past and no limitation for the future.
• PersonId (localPersonnelNumber) cannot be updated via the API; however, it can be done via the interface (Internal ID) or a CSV file upload (ExternallD2).

III. ERRORS handling

At this moment errors handling is maintained via system logs export.

If method composed correctly, reply Status will be 200. Still, you need to check other logs for additional error description information.

Be aware , this approach will be changed with further releases to be unified to other API errors handling notification.

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