PeopleSync

PeopleSync synchronises the people of a project from a CSV file. It compares the file with what is already recorded, works out the difference, and applies only the changes needed: missing people are created, existing ones updated, and their offices and job assignments aligned to the file.

The synchronisation runs as an asynchronous Task, because a file can hold thousands of rows. Starting a sync returns a task reference: poll the Task API to follow its progress and read the outcome.

Use this API to:

• Upload a CSV file and start a synchronisation for a project
• Check the status and the result of a synchronisation you started

Version

1.0.0

OpenAPI version

3.0.0

Authentication

OAuth2

Security scheme type: oauth2

Flow type: password

Token URL: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token

Flow type: refreshToken

Token URL: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token

AccessToken

Security scheme type: apiKey

Query parameter name: access-token

Operations

create

POST

/people-sync/create

Create a new people sync task by uploading a CSV file and specifying the project and sync options.

Authorizations

• Oauth2
• AccessToken

Request Body

object

file

required

CSV file that contains data to synchronize.

string format: binary

project_id

required

The project identifier of people to synchronize.

string

b190e786-8b47-4575-9947-3b1f782e6356

pk

The name of the primary key field. It is used to uniquely identify a person.

string

default: code

tax_code

emulation

If true, the request is executed in emulation mode (no changes are made, but the changes and errors are reported).

boolean

0

1

max_changes

Maximum number of changes allowed in the task. If exceeded, the task is aborted.

integer

default: 100

150

sync_type

Defines which datasets will be synchronized. “people” syncs a single person, “offices” syncs person-office associations, “jobs” syncs person-job associations. “offices” requires “people”, “jobs” requires “offices”.

Array<string>

default: people

Allowed values: people offices jobs

[
  "people",
  "offices",
  "jobs"
]

Responses

201

Task was created and put in queue

object

task_id

The created task ID. Use it to retrieve the current task status via the /view endpoint.

string

task-1234

Example

{
  "task_id": "task-1234"
}

400

Bad request. Required parameter missing or invalid value.

403

Not allowed to synchronize data on the specified project due to permissions.

413

CSV file is too large.

500

Unknown internal server error.

view

GET

/people-sync/view/{id}

Retrieve the status and result of a people sync task by its unique ID.

Authorizations

• Oauth2
• AccessToken

Path Parameters

id

required

string

The task identifier

Responses

200

The requested task data

object

task_id

Task identifier

string

task-1234

user_id

Identifier of the user who created the task

string

admin@myproject.com

status

The current task status

string

Allowed values: TODO PENDING PROCESSING DONE FAILED

response

object

result

object

{
  "PS2": [
    {
      "id": "PS2",
      "action": "activate",
      "periods": [
        {
          "end_date": "2021-07-01 00:00:00",
          "start_date": "2020-07-01 00:00:0"
        },
        {
          "end_date": "",
          "start_date": "2023-06-08 00:00:00"
        }
      ]
    }
  ],
  "PS3": [
    {
      "id": "PS3",
      "action": "add"
    }
  ],
  "PS4": [
    {
      "id": "PS4",
      "action": "deactivate",
      "periods": [
        {
          "end_date": "2023-06-08 00:00:00",
          "start_date": "2020-07-01 00:00:00"
        }
      ]
    }
  ],
  "PS5": [
    {
      "id": "PS5",
      "action": "update",
      "changes": {
        "street": "New street address",
        "locality": "New locality"
      }
    }
  ],
  "PS6": [
    {
      "id": "OF2",
      "action": "add"
    },
    {
      "id": "OF1",
      "action": "deactivate",
      "periods": [
        {
          "end_date": "2023-06-14 00:00:00",
          "start_date": "1970-01-01 00:00:00"
        }
      ]
    },
    {
      "id": "OF2-JOB1",
      "action": "add"
    }
  ]
}

errors

It lists eventually task execution errors

Array<object>

object

line

CSV file line that cointains the error

integer

9

message

The error esplication

string

Invalid office code OF1234

info

Error additional informations

string

...

changes

It presents a summary of the applied changes after the task execution.

object

add

The total number of add operations

integer

2

update

The total number of update operations

integer

3

activate

The total number of activate operations

integer

5

deactivate

The total number of deactivate operations

integer

4

total

The total number of operations executed

integer

14

created_at

Date time when task was created

string

2023-06-30 10:40:00

updated_at

Date time when task was updated last

string

2023-06-30 10:40:00

Example

{
  "task_id": "task-1234",
  "user_id": "admin@myproject.com",
  "status": "DONE",
  "response": {
    "result": {
      "PS2": [
        {
          "id": "PS2",
          "action": "activate",
          "periods": [
            {
              "end_date": "2021-07-01 00:00:00",
              "start_date": "2020-07-01 00:00:00"
            },
            {
              "end_date": "",
              "start_date": "2023-06-08 00:00:00"
            }
          ]
        }
      ],
      "PS3": [
        {
          "id": "PS3",
          "action": "add"
        }
      ],
      "PS4": [
        {
          "id": "PS4",
          "action": "deactivate",
          "periods": [
            {
              "end_date": "2023-06-08 00:00:00",
              "start_date": "2020-07-01 00:00:00"
            }
          ]
        }
      ],
      "PS5": [
        {
          "id": "PS5",
          "action": "update",
          "changes": {
            "street": "New street address",
            "locality": "New locality"
          }
        }
      ],
      "PS6": [
        {
          "id": "OF2",
          "action": "add"
        },
        {
          "id": "OF1",
          "action": "deactivate",
          "periods": [
            {
              "end_date": "2023-06-14 00:00:00",
              "start_date": "1970-01-01 00:00:00"
            }
          ]
        },
        {
          "id": "OF2-JOB1",
          "action": "add"
        }
      ]
    },
    "errors": [
      {
        "line": 9,
        "message": "Invalid office code OF1234",
        "info": "..."
      }
    ],
    "changes": {
      "add": 2,
      "update": 3,
      "activate": 5,
      "deactivate": 4,
      "total": 14
    }
  },
  "created_at": "2023-06-30 10:40:00",
  "updated_at": "2023-06-30 10:40:00"
}

403

Not allowed to fetch task data due to permissions.