getRecommendedEntitiesForUser

A method by which the caller is able to query SAM in an authenticated manner, thus indirectly identifying the user who is making the call, to then taylor the response payload of recommended (discoverable) entities (initially companies) back to the user. The caller is also able to optionally supply search terms, which allows the same method to act as a suggestion only system, while also able to be used as a search like method with smarts to restrict the results.

The logic and algorithm of the actual recommendation and search capability is out of the scope of this document. It is in XXXXX document. However some top level assumptions include: Return entities which partially match or fully match the company’s criteria relative to the users’ user profile metadata. Only return entities which the user is currently not connected to. Otherwise the user will just think its noise. Do not return companies which have chosen their wall to be hidden. Only return companies which are active, and not inactive or deleted. Only return one entity per company or event… not one per criteria, otherwise multiple criteria would result in multiple duplicate entries shown to the user which are like duplicates, and that would give the user a bad experience. (As per agreed in meeting @9 Sep 2019) Do return entities which match the criteria, and the user has requested the connection, but the request is still pending ‘manual signoff’. [FUTURE] for events, don’t return events that are expired/passed. Backend will ensure there are no duplicate criteria returned (countries, profession, specialty, identifier tuple)

See link for further details: https://docs.google.com/document/d/11alwVD_i64tv-Cy8J7SCYEZ_J9JjQwG94MWAbKREG40/edit#heading=h.taryg5g8tpxr

Request

POST /rest/user/recommended/entities

Headers

Header	Required	Description
x-nextinteract-authtoken	Yes	Auth token returned from loginUser

Response

200 OK

Returns a JSON array of dictionaries. If no results are returned, an empty array is to be returned.

Version 1 Response

[
   {
      "companyBannerURL" : "http://blah.com/image_banner.jpg",
      "companyLogoURL" : "http://blah.com/image_logo.jpg",
      "companyName" : "Pfizer",
      "companyDesc" : "Blah blurb",
      "companyAddress" : "175 Pitt St",
      "companyCity" : "Sydney",
      "companyPostcode" : "2000",
      "companyState": "New South Wales"
      "companyCountry" : "AUSTRALIA",
      "companyContactName" : "Brad Pitt",
      "companyContactEmail" : "brad@pitt.com",
      "companyWebsite" : "http://brad.com",     
      "entityType" : "company",
      "entityId" : "1234",
      "entityConnectionPending” : true
   }
]

[
   {
      "companyBannerURL" : "http://blah.com/image_banner.jpg",
      "companyLogoURL" : "http://blah.com/image_logo.jpg",
      "companyName" : "Pfizer",
      "companyDesc" : "Blah blurb",
      "companyAddress" : "175 Pitt St",
      "companyCity" : "Sydney",
      "companyPostcode" : "2000",
      "companyState": "New South Wales"
      "companyCountry" : "AUSTRALIA",
      "companyContactName" : "Brad Pitt",
      "companyContactEmail" : "brad@pitt.com",
      "companyWebsite" : "http://brad.com",     
      "entityType" : "company",
      "entityId" : "1234",
      "entityConnectionPending” : true,
      "usesCAF" : true,
      "cafUrl" : "http://mi-caf-test.s3-website-ap-southeast-2.amazonaws.com/mdfa"
   }
]

Response Fields

Field	Type	Description
entityType	String	The type of entry being returned. Currently supports ‘company’, with future support for ‘event’ and other types.
entityId	String	The ID of entry being returned. Represents a string of the company ID when entityType is ‘company’, or event UUID/ID when entityType is ‘event’.
entityConnectionPending	Boolean	Indicates whether this entity has had the user already request a connection but is still pending final approval (e.g. manual vetting).

NOTE: for entities already connected to, we will never have those entities returned in the response as they are already discovered. A value of false means the user can request a connection, and a value of true means the user has requested connection and has PASSED all criteria, but is pending a manual vetting before approving.

NOTE: When a discoverable company is requested to be connected to by the user, and the user fills their user profile details more, but one of their attributes now DOES NOT satisfy the criteria. The user is rejected when attempting to connect. This is OK, and entityConnectionPending is not a concern, as the entity will no longer be returned to the user in the future.

Fields specific to entityType = ”company”:

Field	Type	Description
companyBannerURL	String	Criteria variant of company banner entered by the user for discoverable companies/entities in SAM. URL is not a signed/secured URL.
companyLogoURL	String	Default company logo seen in the headers in UI and company connections. URL is not a signed/secured URL.
companyName	String(100)	Company Name as entered by Company Admin in SAM UI.
companyDesc	String(2000)	Company Description as entered by Company Admin in SAM UI.
companyAddress	String(255)	The address of the company entered by Company Admin in SAM UI.
companyCity	String(30)	The city of the company entered by Company Admin in SAM UI.
companyPostcode	String(12)	The postcode of the company entered by Company Admin in SAM UI.
companyState	String(255)	The long description of the ISO State Code of the company entered by Company Admin in SAM UI.
companyCountry	String(255)	The country of the company entered by Company Admin in SAM UI. SAM DB stores ISO Country code and resolves to long form.
companyContactName	String(50)	The contact name of the company entered by Company Admin in SAM UI.
companyContactEmail	String(255)	The contact email of the company entered by Company Admin in SAM UI.
companyWebsite	String(255)	The website of the company entered by Company Admin in SAM UI.

Response Headers

{ "version":1, "entityType":["company","event"], "searchTerms":"something to search" }

Field	Type	Description
version	Number	Currently set to 2. Version 2 adds support for CAF. See TP19195.
entityType	Array of Strings	Specifies the type of recommended/discoverable stuff to return. Should always include at least one of: ”company” (for companies) or ”event” (RESERVED FOR FUTURE USE).
searchTerms	String	Optional. If included, the value cannot be null, it must be a UTF8 string that is not empty.

Errors

Exception	Description
WSInvalidParameterException	See Error Definitions
WSUnsupportedVersionException	See Error Definitions
WSInvalidAuthTokenException	See Error Definitions
WSCacheServiceException	See Error Definitions
WSDiscoverableServiceException	See Error Definitions