Retrieving connections
Added by IBM contributorIBM | Edited by IBM contributorPaul Bastide on July 6, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

To retrieve complete information about a colleague relationship, use the edit link found in the connection entry in the colleague connections feed.
You can use this operation to obtain connection information that you want to preserve prior to accepting an invitation. See Accepting an invitation to become a colleague for more information. This method returns the Atom entry of a single connection entry as opposed to a feed of all the connection entries. If you want to retrieve a feed, see Searching for a person's colleagues.
 

Process

1. Retrieve any user's Profiles service document using the user's credentials to authenticate the request. See Retrieving the Profiles service document ic45Create New Article
2. In the service document, find the href attribute value where the value of the rel attribute is rel="http://www.ibm.com/xmlns/prod/sn/connections/colleague"
For example: https://enterprise.example.org/profiles/atom/connections.do?connectionType=colleague&key=23e29c58-c16e-467b-8f72-d9d05fc0fef1&lastMod=1395486462948

3. Manually append the "status" attribute to the link found in step 2. The result should look similar to the following:

https://enterprise.example.com/profiles/atom/connections.do?connectionType=colleague&key=dc7218bc-90ee-4bca-8919-4f0b19223ddf&lastMod=1394990845362&status=pending

4. Execute the link from step 3 using the GET request method. Be sure to authenticate as the recipient of the invitation. The resulting feed will contain information about invitation status in the category element where the scheme attribute has the value "http://www.ibm.com/xmlns/prod/sn/status". For example: category term="pending" scheme="http://www.ibm.com/xmlns/prod/sn/status"

You can use this operation to obtain connection information that you want to preserve prior to accepting an invitation.

Input
Method URI Description
GET /profiles/atom/connections.do Value of the href attribute of <link rel="edit"> element of each entry in the colleague connections feed.
Name Type Optional Description
status
enumerated No Specifies the status of the invitation. Options are:
accepted: Lists the connections that the person was invited to participate in and has accepted.
pending: Lists the connections that the person was invited to participate in, but has not responded to yet. Note: You must authenticate the request when you specify this status value.
unconfirmed: Lists the connections that the person has invited others to participate in, but that have not yet been accepted or deleted. Note: You must authenticate the request when you specify this status value.
Authorized values:
  • accepted
  • pending
  • unconfirmed
inclMessage
boolean Yes Specifies whether or not to include the invitation message with the returned entries. This parameter accepts a Boolean value of true or false. If you include this parameter and set it to true, you must be the source of the connection object and you must authenticate the request.
connectionType
string No Identifies the type of connection to look for. You must specify connectionType=colleague.
key
string No An ID generated by Profiles to identify a person.
Note: A user's key value is contained in the element with a class attribute value of x-profile-key in the user's profile feed. You can access a user's feed by searching all profiles by name, which returns information you can then use to retrieve the person's feed.
email
string Yes Internet email address of the user whose colleagues you want to retrieve.
Format the HTTP request using the proper URL encoding. For example, the encoded form of the @ symbol is %40 as in:
adam_eventide%40garden.com
Note: You must provide either this parameter or the userid parameter. Do not provide this parameter if IBM® Connections is configured to prevent email addresses from being displayed. It will return an error code. Use the key or userid parameters instead.
Output
Content Type: application/atom+xml
Code Description
200
OK. Indicates that the request was received successfully.
400
Bad Request. Returned when no matching user record can be found.
401
Unauthorized. Returned when no authenticated user or no userid, email, or key parameter are provided on the request.
404
User Connection not found