Page tree
Skip to end of metadata
Go to start of metadata



Documentation's navigation

Linchpin User Profiles 


REST APIs

The Linchpin User Profiles has a RESTful API to retrieve useful information for any kind of external usage. All endpoints return their data as JSON strings (a standardized lightweight data-interchange format).

Do you miss some features here? Please feel free to let us know.


Profile Fields API

The Profile Fields API gives you all informations  about the configured fields. The Profile Fields API is available under YOUR_DOMAIN_AND_CONTEXT/rest/cup/1.0/fields.

Retrieve a list of all configured user profile fields.

  • URL: /rest/cup/1.0/fields
  • Method: GET
  • Parameters: dataSource=[IDP|XML|LDAP|USER] (optional, filters list of fields by data source) 
    NEW IN LUP 2.21

Results in a complete list of configured fields including all configuration data:

DOMAIN_AND_CONTEXT/rest/cup/1.0/fields
[
   {
      "confluenceCUPField": true,
      "dataSourceUrl": "string",
      "dataSourceType": "USER", 
      "fieldCategoryPK": 0,
      "fieldType": "CASCADE",
      "helpTextKey": "string",
      "hidden": true,
      "inVCard": true,
      "instantMessagingOptionsDto": {
         "discoveryHost": "string",
         "host": "string",
         "label": "string",
         "localizedLabel": "string",
         "statusEnabled": true,
         "type": "JABBER"
      },
      "labelPropertyKey": "string",
      "ldapField": true,
      "ldapKey": "string",
      "linkField": true,
      "linkOptionsDto": {
         "label": "string",
         "linkEnabled": true,
         "localizedLabel": "string",
         "url": "string"
      },
      "localizedFieldCategoryLabel": "string",
      "localizedHelpText": "string",
      "localizedLabel": "string",
      "options": [
         {
            "fieldOptionPK": 0,
            "labelKey": "string",
            "localizedLabelKey": "string",
            "optionPosition": 0
         }
      ],
      "originFieldKey": "string",
      "position": 0,
      "referenceFieldBK": "string",
      "referenceMappings": [
         {
            "dependentFieldBk": "string",
            "pK": 0,
            "sourceFilter": "string",
            "targetValue": "string"
         }
      ],
      "renderStrategy": {},
      "required": true,
      "subtitle": true,
      "type": "CASCADE",
      "userFieldBK": "string",
      "userFieldPK": 0,
      "writeToLdapEnabled": true,
      "xmlField": true,
      "xmlKey": "string"
   },
   { 
      ...
   }
]

User Profile API

The User Profile API provides various profile information. The API is available under DOMAIN_AND_CONTEXT/rest/cup/1.0/profile.

Get the LUP profile of the current user

With this endpoint of the User Profile API you can get the complete profile data of the currently logged in user.

  • URL: DOMAIN_AND_CONTEXT/rest/cup/1.0/profile
  • Method: GET 

Results in a complete set of profile information:

DOMAIN_AND_CONTEXT/rest/cup/1.0/profile
{
   "cup.abteilungsnummer-13":"712",
   "cup.e-mail-10":"Buckminster.Powell@Sales.company.com",
   "cup.fachbereich-12":"Accounting",
   "cup.fachbereich-5":"Sales",
   "cup.jourfix-18":null,
   "cup.land-7":"Germany",
   "cup.ort-6":"Kassel",
   "cup.raumnummer-14":"5925",
   "cup.sprache-15":"DE",
   "cup.stufe-17":"Staff",
   "cup.telefon-11":"(003) 28547554",
   "cup.titel-16":"0",
   "cup.vorgesetzter-19":null,
   "cup.vorname-8":"Buckminster Powell"
}

Get the LUP profile of a given user

With this endpoint of the User Profile API you can get the complete profile data of any given user.

  • URL: DOMAIN_AND_CONTEXT/rest/cup/1.0/profile/{userName}
  • Parameters:
    • userName: confluence user name for the profile you want to retrieve 
  • Method: GET

Results in a complete set of visible profile information of a specified user:

DOMAIN_AND_CONTEXT/rest/cup/1.0/profile/user
{
   "cup.abteilungsnummer-13":"580",
   "cup.e-mail-10":"Bianca.Villarreal@Executive.company.com",
   "cup.fachbereich-12":"Advertising",
   "cup.fachbereich-5":"Executive",
   "cup.jourfix-18":null,
   "cup.land-7":"Norway",
   "cup.ort-6":"Oslo",
   "cup.raumnummer-14":"2843",
   "cup.sprache-15":"EN",
   "cup.stufe-17":"Executive",
   "cup.telefon-11":"(08122) 5570356",
   "cup.titel-16":"0",
   "cup.vorgesetzter-19":null,
   "cup.vorname-8":"Bianca Villarreal"
}

Write data for a given user

NEW IN 2.22.0

With this endpoint you can write the complete profile data.

We are very happy to hear from you if you plan to use this API. Feedback gives us the chance to learn about your use cases and to improve our solution. So if you like just drop us a note via our helpdesk.

  • URL: DOMAIN_AND_CONTEXT/rest/cup/1.0/profile/{userName}
  • Method: PUT
  • Data / body payload:
    DOMAIN_AND_CONTEXT/rest/cup/1.0/profile/user
    {
       "cup.abteilungsnummer-13":"580", // set a new single value
       "cup.fachbereich-12":["Advertising","Marketing","Front Office"], // set multiple values e.g. for multi select fields
       "cup.fachbereich-5":"", // delete a value with "" or null
       "cup.land-7":"Norway"
    }

    Possible Responses:
    • 200 OK
    • 403 FORBIDDEN (update not allowed for one of different reasons)
    • 400 BAD REQUEST(if validation failed), result may look like this:
      400 BAD REQUEST validation failed
      {
        "general": ["You are not allowed to edit this profile." or other general messages]
        "fields": {
          "cup.field-2": "This field can only store exactly one value.",
          "cup.field-3": "The following select options are invalid: A, B, C.",
          "cup.field-4": "Field does not exist.",
          "cup.field-6": "Field is not writeable.",
          "cup.field-7": "Field is required."
        }
      }

Profile data API FAQ

Q: Can we update all field types using the API?
A: Yes.

Q: Can I have an example on how to update data for the type Cascade select?
A: Sure. Let's say your CSV file looks like the one we used as example in our documentation.

cascade_selection_example.csv
Cat-Number, Category,	Group-Number,	Group,		Product-Id,	Product
1,			foodstuffs,	1,				vegetables,	aa,			tomato
1,			foodstuffs,	1,				vegetables,	ab,			potato
1,			foodstuffs,	2,				fruits,		ac,			cherry
1,			foodstuffs,	2,				fruits,		ad,			apple
1,			foodstuffs,	2,				fruits,		ae,			banana
2,			tools,		3,				hand,		ba,			hammer
2,			tools,		3,				hand,		bb,			nipper
2,			tools,		4,				electric,	bc,			drilling machine

If you want to set "foodstuff - vegetables - tomato" and "tools - hand - nipper" to a users profile your JSON request should look like this (the field key must of course match the one you want to change in your system):

{
   "cup.cascading-1":["1/1/aa","2/3/bb"]
}

(warning) Warning: The API will actually not return an error if the data does not exist in your CSV file. It will be saved successfully but in the profiles UI will be no visible data.


Q:
Can the user still overwrite the field after it has been updated by the API or is the field locked?
A: Updating profile fields via the profile API is only possible for fields that are writable, i.e. ones that are not obtaining their values through XML or LDAP import. Thus, it's always possible for users to edit the field values after the API has been used to set a field value. Programmatic locking/unlocking of fields for manual edits is not possible yet

Q:  Is it possible to setup permissions in a way where only an API user can edit fields but users themselves don't have edit access, or maybe just restrict certain fields?
A: No, this is not possible yet. You can grant profile edit permissions to more users but can't exclude the owning user.

Q: Does the API wipe away other fields you don't specify in the API payload?
A: The API only updates the fields that are included with the update request, and keeps the rest intact. Deletion / wiping of existing field data is still possible by providing an empty string as update value, so if that's not desired, you'll need to make sure the JSON passed to our API only contains keys for those fields you'd like to update (and the corresponding values shouldn't be empty in that case, of course).

Profile Picture API

The User Picture API provides access to a users profile picture. The API is available under DOMAIN_AND_CONTEXT/rest/cup/1.0/profile.

Get the profile picture of the current user

With this endpoint of the User Profile API you can get the complete profile data of the currently logged in user.

  • URL: DOMAIN_AND_CONTEXT/rest/cup/1.0/profile/{username}/profilepicture
  • Method: GET
  • Possible Responses: 200 OK
DOMAIN_AND_CONTEXT/rest/cup/1.0/profile/{username}/profilepicture
{
  "uploadAllowed": true,
  "maxFileSize": 2048,
  "dimension": 200,
  "url": [string]
}

Save a new profile picture to a given user

  • URL: DOMAIN_AND_CONTEXT/rest/cup/1.0/profile/{userName}/profilepicture
  • Body payload: "imageDataUrl": [string] (data url of base64 encoded image, e.g. ""data:image/jpeg;base64,/9j/4AAQSk...")
  • Method: PUT
  • Possible Responses: 
    • 200 OK
    • 403 FORBIDDEN (upload not allowed)
    • 404 NOT_FOUND (no user or missing image data)
    • 413 TOO_LARGE (image exceeds max file size)
    • 415 UNSUPPORTED_MEDIA_TYPE (mime type is neither image/png nor image/jpg)

Profile Background Picture API

The User Background Picture API provides access to a users profile background picture. The API is available under DOMAIN_AND_CONTEXT/rest/cup/1.0/profile.

Get the profile background picture of the current user

With this endpoint of the User Profile API you can get the complete profile data of the currently logged in user.

  • URL: DOMAIN_AND_CONTEXT/rest/cup/1.0/profile/{username}/background/image
  • Method: GET
  • Possible Responses: 200 OK + Image data

Save a new profile background picture to a given user

  • URL: DOMAIN_AND_CONTEXT/rest/cup/1.0/profile/{userName}/background/image
  • Method: PUT
  • Possible Responses: 
    • 200 OK
    • 403 FORBIDDEN (upload not allowed)
    • 404 NOT_FOUND (no user or missing image data)
    • 413 TOO_LARGE (image exceeds max file size)
    • 415 UNSUPPORTED_MEDIA_TYPE (mime type is neither image/png nor image/jpg)
  • Payload:
body: {
    "imageDataUrl": [string] (base64 encoded image data),
    "settings": {
        "position": {
            "x": [int],
            "y": [int]
        },
        "imageVersion": [int]
    }
}


Delete the profile background picture for a given user

  • URL: DOMAIN_AND_CONTEXT/rest/cup/1.0/profile/{userName}/background/image
  • Method: DELETE
  • Possible Responses:
    • 200 OK
    • 400 BAD_REQUEST
    • 403 FORBIDDEN
    • 404 NOT_FOUND