ibm_jstools-people

v1.2.2

Published

16 days ago

Allow to retrieve information from someone in ibm unified profile API

Downloads

424

0High
0Medium
0Low

thiagogs

ibm unified-profile profile-ibm

IMPORTANT

Comunicate 1

Due to the new mandatory change regarding the new Tokenization of the API we launch the version 1.1, now aside from the default parameters, we will have to request your token via boarding process and then use it with the API, details regarding the api usage, were updated, but if you want to know more about the tokenization, check the FAQ.

Comunicate 2

Due to the case-2022-05-05-1450 opened by the CSIRT team we had to migrate from the Public Github to the Github Enterprise, this change forced us to change the name of the gem.

Since the ruby does require the name of the gem to be used as the name of the class. Check below what changed:

Action 1 - Package.json

Change the name of the module to the new one in your package.json file and hit npm install on your terminal.

// From
"ibm-uprofile": "^3.1.0"

// To
"ibm_jstools-people": "1.0.0"

Action 2

Change everywhere you have within your application from the old require to the new one.

// From
const UProfile = require('ibm-uprofile')(debug)

// To
const UProfile = require('ibm_jstools-people')(debug)

From now on it should be transparent and require no other action.

IBM - Unified Profile

This module Allow the user to retrieve information from the IBM unified profile program.

Getting Started

To use this module you just need to import it to your project and have a running server with access to the blue network.

Installing

Run npm i ibm_jstools-people --save

Before you proceed

This module were created in a best effort to make the life of the developers easier, I'm currently working in several products and I'm not even member of the bluepages team.

Before using it, remember:

1- The responses here might not be completely up-to-date, since they can change it and I wo'nt be warned about it.

2- I tried my best with my skill, so be kind.

3- If you find a bug, or a response that is not matching the results stated here, please let me know, or even better, fork and submit a PR.

Testing

To run the test suite, first install the dependencies, run npm test, then in another tap of your terminal access the APIs

npm install
npm test
curl <API>

API List

Below follow the list of samples for testing

GET http://localhost:3000/:uid/info
GET http://localhost:3000/:uid/skill
GET http://localhost:3000/:uid/team
GET http://localhost:3000/:uid/all
POST http://localhost:3000/users

Body UIDs

[
  "000000631",
  "111111631",
  "222222631"
]

Body Emails

[
  "[email protected]",
  "[email protected]",
  "[email protected]"
]

PS: You can use one or another but you can't search by CNUM and EMAIL at the same time. The API will search the type it begin with, the other will be ignored.

Methods

Here is the list of the available methods for this module

UProfile.team(CNUM[,options])

Fetch the information regarding the user team. It will fetch the international and local hierarchical tree.

options*

There are several needs over the API, therefore these options allow you to have some plexibility.

| name | value | description | --- | --- | --- | include_headers | Array | Will include the headers of the People API into the result. (default: false) | break_on_404 | String | Will raise a not found error if not find the person you are looking for. (default: false) | token | String | Will be mandatory from February 2nd, 2024.

Token can be used as a argument of the module, but it will also look for the environment variable IBM_PEOPLE_API_KEY

Usage

const UProfile = require('ibm_jstools-people')(debug) // debug [true/false] will log more stuff to the stdout

// Await / Async
try {
  const user = await UProfile.team("000000631")
  console.log(user)
} catch (err) {
  console.log(err)
}

// Traditional Promise
UProfile.team("000000631")
  .then(user => console.log(user))
  .catch(err => console.log(err))

Response Schema - UserTeamObject

{
  "uid": String,
  "functional": {
    "leadership": [
      {
        "uid": String,
        "preferredIdentity": String,
        "name": {
          "last": String,
          "first": String
        },
        "nameFull": String,
        "role": String,
        "dept": {
          "code": String
        },
        "isEmployee": Boolean,
        "isManager": Boolean,
        "employeeType": {
          "isEmployee": Boolean,
          "isManager": Boolean,
          "title": String,
          "code": String
        },
        "legalEntity": {
          "groupCode": String,
          "groupId": String,
          "name": String,
          "code": String
        },
        "address": {
          "business": {
            "country": String,
            "locality": String,
            "state": String,
            "zip": String,
            "location": String,
            "stateCo": String,
            "address": [
              String
            ]
          }
        },
        "telephone": {
          "itn": String,
          "mobile": String,
          "office": String,
          "tieline": String
        },
        "notesEmail": String,
        "sAMAccountName": String,
        "preferredSlackId": String,
        "preferredSlackUsername": String,
        "conferenceUrl": String
      }
    ]
    "peers": [{ ... }]
  },
  "incountry": {
    "leadership": [{ ... }],
    "peers": [{ ... }]
  }
}

//PS: [{ ... }] Means the object is the same as before.

Uprofile.skills(CNUM[,options])

Fetch the skillset of the user it also retrieve the badges and other stuff related with the user skills.

options*

There are several needs over the API, therefore these options allow you to have some plexibility.

Token can be used as a argument of the module, but it will also look for the environment variable IBM_PEOPLE_API_KEY

Usage

const UProfile = require('ibm_jstools-people')(debug) // debug [true/false] will log more stuff to the stdout

// Await / Async
try {
  const user = await UProfile.skills("000000631")
  console.log(user)
} catch (err) {
  console.log(err)
}

// Traditional Promise
UProfile.skills("000000631")
  .then(user => console.log(user))
  .catch(err => console.log(err))

Response Schema - UserSkillsObject

{
  "jobRoles": [
    {
      "JR_ID": String,
      "jobRole": String,
      "primary": Boolean,
      "skillSets": [
        {
          "JRSS_ID": String,
          "skillSet": String,
          "primary": Boolean
        },
        {
          "JRSS_ID": String,
          "skillSet": String
        },
        {
          "JRSS_ID": String,
          "skillSet": String
        },
        {
          "JRSS_ID": String,
          "skillSet": String
        },
        {
          "JRSS_ID": String,
          "skillSet": String
        },
        {
          "JRSS_ID": String,
          "skillSet": String
        }
      ]
    },
    {
      "JR_ID": String,
      "jobRole": String,
      "skillSets": [
        {
          "JRSS_ID": String,
          "skillSet": String
        }
      ]
    }
  ],
  "expertiseSummary": String,
  "primaryJobCategory": {
    "id": String,
    "name": String
  },
  "secondaryJobCategory": {
    "id": String,
    "name": String
  },
  "certifications": {
    "badges": [
      {
        "badgeId": String,
        "badgeName": String,
        "badgeDescription": String,
        "badgeImageUrl": String,
        "issueId": String,
        "issueDate": String,
        "badgeUrl": String,
        "publicUrl": String
      },
      {
        "badgeId": String,
        "badgeName": String,
        "badgeDescription": String,
        "badgeImageUrl": String,
        "issueId": String,
        "issueDate": String,
        "badgeUrl": String,
        "publicUrl": String
      }
    ]
  },
  "linkedIn": {
    "memberToken": String,
    "url": String,
    "enabled": Boolean
  },
  "uid": String
}

// PS: Not all the information above may be available since it depends on the user update.

Uprofile.seach(QUERY[,options])

Search the user information by any string provided

options*

There are several needs over the API, therefore these options allow you to have some plexibility.

Token can be used as a argument of the module, but it will also look for the environment variable IBM_PEOPLE_API_KEY

Usage

Query

A string to find the closest match (name, email, uid, dept, etc).

Options

start: Specify the row number to start listing the users (Default: 0). limit: The number of records to bring back (from start) (Default: 10). serial: Usually the UID of the user searching the info, since it will try to match peers of the employee first.

The start and limit can be used to create some kind of pagination.

const UProfile = require('ibm_jstools-people')(debug) // debug [true/false] will log more stuff to the stdout

// Await / Async
try {
  const users = await UProfile.search("John.Dohn", { start: 0, limit: 5, serial: '000000631' })
  console.log(users)
} catch (err) {
  console.log(err)
}

// Traditional Promise
UProfile.search("John.Dohn", { start: 0, limit: 5, serial: '000000631' })
  .then(users => console.log(users))
  .catch(err => console.log(err))

Response Schema - UserTypeaheadObject

{
  "id": String,
  "address_preferred_locality": String,
  "address_preferred_state": String,
  "address_preferred_zip": String,
  "address_preferred_country": String,
  "address_business_zip": String,
  "address_business_locality": String,
  "address_business_state": String,
  "address_business_country": String,
  "address_business_location": String,
  "callupName": String,
  "co": String,
  "dept_code": String,
  "employeeType_code": String,
  "hrOrganizationCode": String,
  "mail": [
    String
  ],
  "manager": String,
  "name_last": String,
  "nameFull": String,
  "notesEmail": String,
  "org_title": String,
  "preferredIdentity": String,
  "role": String,
  "serial": String,
  "telephone_office": String,
  "telephone_mobile": String,
  "uid": String,
  "functionalManagerUid": String,
  "inCountryManagerUid": String,
  "languages_lang": [
    String
  ],
  "nameDisplay": String,
  "notesEmailWithDomain": String,
  "preferredLastName": String,
  "score": Number,
  "resultLevel": Number
}

Uprofile.info(CNUM[,options])

Fetch the user profile from the bluepages.

options*

There are several needs over the API, therefore these options allow you to have some plexibility.

Token can be used as a argument of the module, but it will also look for the environment variable IBM_PEOPLE_API_KEY

Usage

Can consult one or more than one user.

IMPORTANT

You can only search one type [CNUM/EMAIL] at time, if you try put both type in the same list will will return only the results from the first item of the list.

Single Search

const UProfile = require('ibm_jstools-people')(debug) // debug [true/false] will log more stuff to the stdout

// Await / Async
try {
  const user = await UProfile.info("000000631")
  console.log(user)
} catch (err) {
  console.log(err)
}

// Traditional Promise
UProfile.info("000000631")
  .then(user => console.log(user))
  .catch(err => console.log(err))

Response Schema - UserInfoObject

{
  "address": {
    "business": {
      "country": String,
      "locality": String,
      "state": String,
      "zip": String,
      "location": String,
      "stateCo": String,
      "address": [
        String
      ]
    }
  },
  "backup": {
    "backupCountryCode": String,
    "backupSerialNumber": String,
    "uid": String
  },
  "dept": {
    "code": String
  },
  "employeeType": {
    "isEmployee: Boolean,
    "isManager: Boolean,
    "title": String,
    "code": String
  },
  "legalEntity": {
    "groupCode": String,
    "groupId": String,
    "name": String,
    "code": String
  },
  "name": {
    "first": String,
    "last": String
  },
  "oooSettings": {
    "message: Boolean,
    "date: Boolean
  },
  "org": {
    "group": String,
    "title": String,
    "unit": String,
    "code": String
  },
  "telephone": {
    "itn": String,
    "mobile": String,
    "office": String,
    "tieline": String
  },
  "workLocation": {
    "building": String,
    "code": String,
    "campusID": String
  },
  "cn": [
    String
  ],
  "languages": [
    String
  ],
  "mail": [
    String
  ],
  "alternateLastName": String,
  "c": String,
  "callupName": String,
  "co": String,
  "costCenter": String,
  "courtesyTitle": String,
  "createdDate": String,
  "div": String,
  "dn": String,
  "employeeCountryCode": String,
  "entryType": String,
  "functionalManagerUid": String,
  "hrActive": String,
  "hrOrganizationCode": String,
  "importantContactInfo": String,
  "imt": String,
  "inCountryManagerUid": String,
  "iot": String,
  "manager": String,
  "managerPSC": String,
  "nameDisplay": String,
  "nameFull": String,
  "notesEmail": String,
  "notesMailDomain": String,
  "notesMailFile": String,
  "notesMailServer": String,
  "notesShortName": String,
  "preferredContactMethod": String,
  "preferredIdentity": String,
  "preferredLanguage": String,
  "preferredSlackId": String,
  "preferredSlackUsername": String,
  "profileLastUpdated": String,
  "pronunciation": String,
  "psc": String,
  "role": String,
  "sAMAccountName": String,
  "serial": String,
  "startDate": String,
  "timeZone": String,
  "timeZoneCode": String,
  "uid": String,
  "workdayWorkerID": String,
  "workerId": String,
  "workplaceIndicator": String,
  "conferenceUrl": String
}

Multiple Search

This module allow the application to query large amount of data, although the UnifiedProfile API currently has a limitation of 7873 characters in the url. IT won't happen here.

To create a way around it I will calculate the quantity of chars in the URL after the encode and perform several chunks below the cap running asynchronously multiple query into the UnifiedProfile.

This way, the limitation is transparent when using this module even if it still there.

Below follow the example about how to use it:

const UProfile = require('ibm_jstools-people')(debug) // debug [true/false] will log more stuff to the stdout

// Await / Async
try {
  const user = await UProfile.info(["000000631", "111111631", "222222631"])
  console.log(user)
} catch (err) {
  console.log(err)
}

// Traditional Promise
UProfile.info(["000000631", "111111631", "222222631" ])
  .then(user => console.log(user))
  .catch(err => console.log(err))

Response Schema - `[UserInfoObject]`

[
  { ... },
  { ... }
]

The objects within the array is the same as UserInfoObject

Uprofile.all(CNUM[,options])

Basically put together the result of the 3 APIs before into a single object.

Usage

const UProfile = require('ibm_jstools-people')(debug) // debug [true/false] will log more stuff to the stdout

// Await / Async
try {
  const user = await UProfile.all("000000631")
  console.log(user)
} catch (err) {
  console.log(err)
}

// Traditional Promise
UProfile.all("000000631")
  .then(user => console.log(user))
  .catch(err => console.log(err))

Response Schema - all (Object)

{
  "identity_info": UserInfoObject
  "team_info": UserTeamObject
  "profile_extended": UserSkillsObject
}

Options

Currently there are a small set of options, but will help you to customize a little bit the API:

| attribute | Purpose | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | break_on_404 | If true, will throw an error 404 error if the user do not match. Default: falseThis option is ignored when you are searching more than one user | | headers | If true, will bring the headers from the Unified Profile. Default: false |

About IBM-Unified-Profile API

I coun't find any detailed information regarding the APIs, like limitation and stuff like that.

Here is the link regarding all APIs => https://w3.ibm.com/w3publisher/bluepages-ui-support/unified-profile-apis

This module is not related with the APIs, it only uses the URLs from there and provide a transparent way to query users from it.

Authors

Night - Niightly

Special Thanks

I would like to express here my gratitude to Matt Funk (Product Owner for BluePages & User Profile) for the patience to listen to the results of my tests and problems I have faced regarding the new version of the APIs.

License

This project is licensed under the MIT License (whatever it means hahahah)

PS: just kidding, thanks Massachusetts Institute of Technology for this wonderful license.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

IMPORTANT

Comunicate 1

Comunicate 2

Action 1 - Package.json

Action 2

IBM - Unified Profile

Getting Started

Installing

Before you proceed

Testing

API List

Body UIDs

Body Emails

Methods

UProfile.team(CNUM[,options])

options*

Usage

Response Schema - UserTeamObject

Uprofile.skills(CNUM[,options])

options*

Usage

Response Schema - UserSkillsObject

Uprofile.seach(QUERY[,options])

options*

Usage

Query

Options

Response Schema - UserTypeaheadObject

Uprofile.info(CNUM[,options])

options*

Usage

Single Search

Response Schema - UserInfoObject

Multiple Search

Response Schema - [UserInfoObject]

Uprofile.all(CNUM[,options])

Usage

Response Schema - all (Object)

Options

About IBM-Unified-Profile API

Authors

Special Thanks

License

Response Schema - `[UserInfoObject]`