Personio to JSM Assets

Personio to JSM Assets

Personio to JSM Assets Integration Guide

This page explains how to use OnLink to import employee data from Personio into Jira Service Management Assets.

Overview

OnLink imports Personio API responses into Jira Service Management Assets object types using mapping statements such as key:, map:, and config:. Use this pattern for Personio resources such as workers, departments, job functions, companies, and teams.

The high-level process is:

  1. Create or confirm the target Assets schema and object type.

  2. OAUTH credentials to connect to API.

  3. Set the API method and Personio endpoint, then fetch sample data.

  4. Map JSON fields from the Personio response to Assets attributes.

  5. Run Get Data to validate the result, then run the import when the mapping is correct.

Supported Personio APIs

The examples on this page use Personio List persons https://developer.personio.de/reference/get_v2-persons API. The same pattern can be adapted for other Personio API methods.

2. Configure the OnLink data source

  1. In OnLink, add an Assets Data Source.

  2. Set Authentication Type to OAUTH Client Credentials.

  3. Set the token URL as https://api.personio.de/v2/auth/token

  4. Set Client ID and Secret provided by your Personio Admin

  5. Set Scope personio:persons:read

 

3. Configure the API method

Use a GET request to retrieve records from List Persons API https://developer.personio.de/reference/get_v2-persons . For example, to fetch persons, configure the request as follows:

  1. Set Method to GET.

  2. Set URL to https://api.personio.de/v2/persons

  3. Set Response data path to _data.

  4. Leave the remaining configuration at the default values unless your Personio API endpoint requires additional parameters.

GET https://api.personio.de/v2/persons

5. Fetch sample data

Save the connection, then run it to fetch sample values from Personio. Use the returned sample JSON to confirm that the endpoint is correct and to identify the field names needed for mapping.

Sample JSON

{ "_data": [ { "id": "3003", "email": "jen.doe@personio.de", "created_at": "2017-07-21T17:32:28Z", "updated_at": "2017-07-21T17:32:28Z", "first_name": "John", "last_name": "Smith", "preferred_name": "John Smith", "gender": "MALE", "profile_picture": { "url": "https://api.personio.de/v1/company/employees/3003/profile-picture" }, "status": "ACTIVE", "custom_attributes": [ { "id": "dynamic_305", "type": "string", "value": "Red", "global_id": "color" }, { "id": "dynamic_306", "type": "string", "value": "DExx-xxff-ss-os02", "global_id": "IBAN" } ], "employments": [ { "id": "c85d978e-1104-4762-be94-c868525eef45" } ], "_meta": { "links": { "employments": { "href": "https://api.personio.de/v2/persons/3003/employments" } } } } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/persons" } } } }

6. Configure pagination

Personio API responses support pagination.

The endpoint returns a paginated list using cursor-based pagination. Use the following configuration.

 

7. Apply filtering

You can refine results using the  query parameter. Filterable fields include id, first_name, last_name, created_at, and updated_at. For example, to import only active workers:

status=ACTIVE

 

8. Configure the Assets import and mapping

After the connection is established, create the Assets import by following the JSM Assets Data Synchronization guide.

Use the fetched API sample to identify the Personio JSON field names and map them to the corresponding JSM Assets attributes. The key: mapping should identify the stable unique value used to match and update existing Assets objects.

 

key:id=id

The key prefix defines the unique identifier. Personio’s id field maps to the Assets id attribute, so future syncs update existing objects instead of creating duplicates.

map:email=Email

Maps the Personio email field to the corresponding Assets email attribute.

map:first_name=First Name

Maps the Personio first_name field to the worker’s first name in Assets.

map:last_name=Last Name

Maps the Personio last_name field to the worker’s last name in Assets.

map:status=Status

Maps the Personio status field to the worker’s Status in Assets.

Use the Personio documentation to add additional fields https://developer.personio.de/reference/get_v2-persons

Mapping guidance

  • Start with one unique key: mapping so OnLink can identify whether to create or update an Assets object.

  • Add map: entries for each Personio field you want to store in Assets.

  • Compare the Personio sample JSON with the Assets object type attributes before running an import.

  • If a value is nested in the JSON response, inspect the sample output carefully and use the field path supported by the OnLink mapping configuration.

9. Validate and run the import

  1. Use Get Data first to preview the data returned by Personio.

  2. Confirm that the sample records contain the expected fields and values.

  3. Verify that the key field maps to a unique Assets attribute.

  4. Review the object type mapping and attribute names for spelling and case consistency.

  5. Run the import only after the previewed data and mapping are correct.