SAP Jam Communities

Overview

Use the SAP Jam Communities service to integrate YaaS functionality with the SAP Jam Communities collaboration product.

With this service, you can:

  • Retrieve published questions and answers and the relevant comments from SAP Jam Communities.
  • Reply to a question or a comment.
  • Get all of the messages and participants who post questions or comments within a specific conversation.
  • Manage the configuration of SAP Jam Communities.
  • Manage SAP Jam Communities user data.
  • Manage the reference.


API Reference

/{tenant}/harvest

Harvest published data from SAP Jam Communities

/{tenant}/harvest

post

Retrieve questions and answers and their comments from SAP Jam Communities.

Required scope: hybris.sapcommunity_manage

/{tenant}/reply

Reply comments

/{tenant}/reply

post

Post a reply for a specific question or a comment.

Required scope: hybris.sapcommunity_manage

/{tenant}/conversations/{conversationId}

Get the whole content of a conversation

/{tenant}/conversations/{conversationId}

get

Get all the messages of a specific conversation from the stored harvest data.

Required scope: hybris.sapcommunity_view

put

Update messages in a specific conversation. Currently, only the following fields can be updated:

  • readFlag: to indicate whether the message in a specific conversation has been read or not;
  • processAgentID: to indicate who has processed the messages in a specific conversation.

Required scope: hybris.sapcommunity_manage

/{tenant}/conversations/{conversationId}/participants

Get the basic information list of participated users

get

Get the basic information, like user id, user name and email address, of users who create the question or comments in current conversation.

Required scope: hybris.sapcommunity_view

/{tenant}/configuration

SAP Jam Communities configuration

/{tenant}/configuration

get

Get SAP Jam Communities integration configuration.

Required scope: hybris.sapcommunity_configuration_view

post

Create SAP Jam Communities integration configuration.

Required scope: hybris.sapcommunity_configuration_manage

put

Update SAP Jam Communities integration configuration.

Required scope: hybris.sapcommunity_configuration_manage

delete

Delete SAP Jam Communities integration configuration.

Required scope: hybris.sapcommunity_configuration_delete

/{tenant}/token

Access token to handle reply

/{tenant}/token

post

Use this endpoint to obtain an access token for the client application.

get

Use this endpoint to get an access token for the client application.

/{tenant}/users

SAP Jams Communities users information

/{tenant}/users

post

Post user with details information into Social Media User service.

Required scope: hybris.sapcommunity_manage

get

Get the detail information list of SAP Jam Communities users.

Required scope: hybris.sapcommunity_view

/{tenant}/users/{userId}

Detail information of specific user.

put

Update the information of a specific SAP Jam Communities user.

Required scope: hybris.sapcommunity_manage

get

Get the detail information of a specific SAP Jam Communities user.

Required scope: hybris.sapcommunity_view

delete

Delete the information record of a specific SAP Jam Communities user.

Required scope: hybris.sapcommunity_manage

/{tenant}/users/{userId}/anonymize

Anonymize the personal information of current user.

put

Empty the fields that contains the personal information of a specific SAP Jam Communities user.

Required scope: hybris.sapcommunity_manage

Search for blogs from SAP Jam Communities.

/{tenant}/references

SAP Jams Communities references information

/{tenant}/references

post

Create a new reference between knowledge base article and user defined object.

Required scope: hybris.sapcommunity_manage

get

Retrieve a collection of reference.

If no query is specified, all references are returned in the result collection. To filter the result collection, use the query parameter q. The SAPJam Communities service uses the same query syntax as the Document service.

You can sort the result collection using the query parameter sort.

Required scope: hybris.sapcommunity_view

/{tenant}/references/{id}

Detail information of specific reference.

delete

Delete a reference.

The reference to be deleted is identified by its id.

Required scope: hybris.sapcommunity_manage


Scopes

The table shows the scopes that the SAP Jam Communities Service SDK supports:

SCOPEDESCRIPTION
hybris.sapcommunity_viewRead-only access to SAP Jam communities data
hybris.sapcommunity_manageAuthorization to manipulate SAP Jam communities data
hybris.sapcommunity_configuration_viewRead-only access to SAP Jam communities integration configuration
hybris.sapcommunity_configuration_manageAuthorization to POST and PUT SAP Jam communities integration configuration
hybris.sapcommunity_configuration_deleteAuthorization to DELETE SAP Jam communities integration configuration

For more information about scopes, authorization, and authentication procedures for YaaS services, see Scopes and Authorization.


SAP Jam Communities

SAP Jam Communities provides online communities that your customers, resellers, and distributors can use to collaborate and conduct e-commerce. You can integrate the SAP Jam Communities service with SAP Hybris Commerce as a Service (SAP Hybris CaaS), and agents can use the information from SAP Jam Communities to better assist customers in purchase decisions.


Connecting to SAP Jam Communities

You can set up the connection between SAP Jam Communities and this service by performing configuration steps. To perform the steps, you need to provide a SAP Jam Community URL, its authentication information, and other settings. If the configuration settings are correct and posted, this service is connected to SAP Jam Communities, and you can use all functions that this service provides for using SAP Jam Communities.

Authorization for SAP Jam Communities

SAP Jam Communities uses the OAuth 2.0 service for third party application authorization.

For more information about scopes, authorization, and authentication procedures for YaaS services, see Scopes and Authorization.

A SAP Jam Communities service user must have the authorization to reply to questions or to create answers for SAP Jam Community posts.

The SAP Jam Communities service follows a two OAuth authentication token generation strategy. The service generates persistent tokens and tokens that expire after a predefined timeframe.

Persistent token

After the service generates the token, it is available indefinitely and stored in the attribute token.

The system deprecates persistent tokens after December 31st, 2016. Instead, you can use token with an expiration time.

Token with an expiration time

You need to regenerate this kind of token at certain time intervals. To ensure that the SAP Jam Communities service always uses the correct token, the service stores the parameters for the token generation instead of storing the token itself. The service automatically regenerates the token at the required intervals.

  • applicationID: ID of the application created in SAP Jam Communities
  • applicationSecret: Secret of the application created in SAP Jam Communities
  • loginUserName: User name for logging on to SAP Jam Communities. Usually, this is the user name of the system administrator.
  • loginUserPassword: User password for logging on to SAP Jam Communities. Usually, this is the password of the system administrator.


Retrieve SAP Jam Communities Data

Currently, these post types are available in SAP Jam Communities: Question, Discussion, and Blog. Note that this service only supports the Question post type.

After the SAP Jam Communities service is connected to SAP Jam Communities, you can retrieve data within the timeframe that you define when performing the configuration steps. You can store the retrieved data using Social Media Post service.


Reply to a Question or Place an Answer on SAP Jam Communities

Using the SAP Jam Communities service, you can reply to questions or place answers in SAP Jam Communities. If the reply is successful, the replied message is displayed in SAP Jam Communities.

If the reply function does not work, ensure that you have configured the integration with SAP Jam Communities according to the OAuth token strategy. For more information, see Authorization for SAP Jam Communities.


SAP Jam Communities Conversation

The service retrieves conversations from SAP Jam Communities. The service maps each conversation to a SAP Jam Communities question. The conversation contains all information related to the question and its comments. You can identify a conversation based on the unique conversation ID.

Retrieve a conversation

You can retrieve conversation details by using the conversation ID. The service returns all messages belonging to the corresponding conversation retrieved from SAP Jam Communites, including comments and participant information.

Retrieve participants

The service retrieves the conversation participant information, such as the user IDs, user names, and email addresses.

Batch update a conversation

A conversation can contain several comments and sub comments. You can update the messages belonging to a specific conversation. By using the batch update function, you can retrieve this information:

  • Whether a message belonging to the conversation has been read Initially, the service records all posted comments as unread by using the readFlag: false flag
  • Who has processed a message belonging to the conversation


SAP Jam Communities Users

You can use the Social Media User service to store and process social media user data. You can map SAP Jam Communities users to social media users. You can create, change, delete, and search for the mapped user in the social media. After you trigger these actions, the SAP Jam Communities service delegates them to the Social Media User service.

Create a user

You can create a user in social media. If you create a user, the service stores the SAP Jam Communities user ID in the Social Media User service for user mapping.

Retrieve a user

You can retrieve the information of a social media user. If you do not specify a query parameter, the service returns a limited number of users. If you have specified the user ID socialMediaUserID in the Socia Media Communities URL, the service returns a specified user.

Delete a user

You can delete a user based on the user ID. If you trigger the deletion of a user, the service deletes the corresponding user in the SAP Jam Communities service and not in SAP Jam Communities.

Anonymize a user

If you anonymize a user, the service removes the personal data from the corresponding fields. The fields remain empty.

You cannot reverse the settings after you anonymize a user.

For more details about anonymized information, see Anonymize SAP Jam Communities User.


Search for SAP Jam Communities Blogs

You can search for blogs of the type Post in the SAP Jam Communities that you have configured for integration with this service. You can define the paging and order of the search results using query parameters. The query parameter Keywords is mandatory.


SAP Jam Communities References

The SAP Jam Communities service maps a knowledge base to user-defined objects, such as service tickets and sales orders.

Create a reference

After you create a reference, the SAP Jam Communities service stores, in the Document service, the mapping between a knowledge base article ID and a user-defined object ID.

Retrieve references

You can retrieve a collection of references by performing a GET request to the /{tenant}/references endpoint. Each reference contains these fields:

  • id : Unique identifier of the reference generated by the Document service
  • knowledgeBaseArticleId : The identifier of one knowledge base article, such as the JAM community conversion ID
  • knowledgeBaseArticleType : The type of knowledge base article, for example, SAP_COMMUNITY_POST
  • targetObjectId : The identifier of an object
  • targetObjectType : The type of object, for example SAP_SERVICE_TICKET
  • createdBy : The user who created the reference

Delete a reference

You can delete a reference by its ID.


Configure the integration with SAP Jam Communities

Request

  • Method: POST

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/configuration

  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_configuration_manage.
  • URI Parameters

    • {tenant}: Name of the current tenant
  • Body

    If the SAP Jam Communities service is using a persistent token, the attributes applicationID, applicationSecret, loginUserName, and loginUserPassword are not required.

    If the SAP Jam Communities service is using a token with an expiration time, the attributes are required.

    An example using token with an expiration time looks similar to the following:

    {
      "traits": [{
          "traitName": "question",
          "timeStamp": "1450346443"
      }, {
          "traitName": "answer",
          "timeStamp": "1450347237"
      }],
      "networkID": "test",
      "communityURL": "https://test.com",
      "pushToContactCenter": true,
      "collectEscalated": true,
      "obtainConsent": true,
      "applicationID": "test application id",
      "applicationSecret": "test application secret",
      "loginUserName": "test user name",
      "loginUserPassword": "test password"
    }
    

Response

The successful response returns a 201 status code.


Update the SAP Jam Communities Configuration

After you have created the configuration of the SAP Jam Communities service, you can update these configuration attributes:

  • networkID: SAP Jam Communities network ID
  • communityURL: SAP Jam Communities URL
  • pushToContactCenter: Send request to SAP Contact Center after successfully retrieving data from the SAP Jam Communities (switch)
  • collectEscalated: Only collect escalated related data or collect all data when the retrieval job is being executed (switch)
  • obtainConsent: Obtain user's consent (switch)
  • OAuth token generation related configuration

This example shows how you can update the configuration:

Request

  • Method: PUT

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/configuration

  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_configuration_manage.
  • URI Parameters

    • {tenant}: Name of the current tenant
  • Body: The request body can contain the entire configuration information. You can refer to Configure the integration with SAP Jam Communities. Leave the value of the attribute loginUserPassword empty if you don’t want to change it.

    An example for updating configuration information with user password looks similar to the following:

    {
      "traits": [{
          "traitName": "question",
          "timeStamp": "1450346443"
      }, {
          "traitName": "answer",
          "timeStamp": "1450347237"
      }],
      "networkID": "test",
      "communityURL": "https://test.com",
      "pushToContactCenter": true,
      "collectEscalated": true,
      "obtainConsent": true,
      "applicationID": "test application id",
      "applicationSecret": "test application secret",
      "loginUserName": "test user name",
      "loginUserPassword": "test password"
    }
    

Response

The successful response returns a 204 status code.


Generate a Token

This example shows how you can obtain an access token from SAP Jam Communities:

Request

  • Method: POST

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/token

  • Headers

    • Authorization: This includes a valid OAuth2 access token
  • URI Parameters

    • {tenant}: Name of the current tenant
  • Body

    An example JSON content looks similar to the following:

    {
      "communityURL": "https://test.com",
      "applicationID": "applicationId",
      "applicationSecret": "applicationSecret",
      "loginUserName": "username",
      "loginUserPassword": "password"
    }
    

Response

If all required attributes have been assigned the correct value, the response includes a 201 status code, an access token, and other token-related information. The attribute expires_in is counted in seconds and represents the expiration time of the token.

Example:

{
    "access_token": "test token",
    "token_type": "bearer",
    "expires_in": 7200,
    "created_at": 1453707040
}

If the field value of any of the required fields is an incorrect value, the service renders a status code of 400 and an error description.

Example:

{
    "status": 400,
    "message": "There are validation problems, see details section for more information",
    "moreInfo": "https://api.yaas.io/patterns/errortypes.html",
    "type": "validation_violation",
    "details": [{
        "field": "hybris-tenant",
        "message": "size must be between 1 and 36",
        "type": "invalid_header"
    }]
}


Get a Token

This example shows how you can get an access token from SAP Jam Communities:

Request

  • Method: GET

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/token

  • Headers

  • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_view.

  • URI Parameters

  • {tenant}: Name of the current tenant

Response

A successful response includes a 200 status code, an access token, and other token-related information. The attribute expires_in is counted in seconds and represents the expiration time of the token.

Example:

{
    "access_token": "test token",
    "token_type": "bearer",
    "expires_in": 7200,
    "created_at": 1453707040
}


Retrieve Data

Retrieve questions, answers, and comments from SAP Jam Communities that are integrated. The following example shows how to retrieve data from integrated SAP Jam Communities.

Request

  • Method: POST

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/harvest

  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_manage.
  • URI Parameters

    • {tenant}: Name of the current tenant

Response

The successful response returns a 201 status code. An example JSON content looks similar to the following:

{
    "dataCount": 2,
    "socialMediaPosts": [{
        "socialPostID": "12345",
        "communicationMediumID": "0001",
        "socialPostOrigin": "1234567890",
        "socialUserID": "1234567890",
        "socialUserName": "John Smith",
        "socialUserEmail": "John.Smith@hybristest.com",
        "socialPostContent": "This is a test text",
        "creationDateTime": "2014-12-01T09:00:00",
        "socialMediaPostLink": "http://xxx.xxx.xxx",
        "socialPostDirection": "OUTBOUND",
        "socialPostParentID": "1234567890",
        "socialPostRootID": "1234567890",
        "readFlag": "false",
        "processAgentID": "test123",
        "postDepth": "0"
    }, {
        "socialPostID": "12345",
        "communicationMediumID": "0001",
        "socialPostOrigin": "1234567890",
        "socialUserID": "1234567890",
        "socialUserName": "John Smith",
        "socialUserEmail": "John.Smith@hybristest.com",
        "socialPostContent": "This is a test text",
        "creationDateTime": "2014-12-01T09:00:00",
        "socialMediaPostLink": "http://xxx.xxx.xxx",
        "socialPostDirection": "INBOUND",
        "socialPostParentID": "1234567890",
        "socialPostRootID": "1234567890",
        "readFlag": "false",
        "processAgentID": "test123",
        "postDepth": "1"
    }]
}


Posting of a Reply

This example shows how to reply to a message that is retrieved from integrated SAP Jam Communities. The reply is synchronized with the integrated SAP Jam Communities.

Request

  • Method: POST

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/reply

  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_manage.
  • URI Parameters

    • {tenant}: Name of the current tenant
  • Body: Attribute socialPostParentID is a pointer to the message that you want to reply. The value of this attribute must be the value of socialPostID retrieved from SAP Jam Communities.

    An example JSON content looks similar to the following:

    {
      "socialPostParentID": "13550",
      "socialPostContent": "hi, what can I do for you",
      "processAgentID": "tester"
    }
    

Response

The successful response returns a 201 status code. An example JSON content looks similar to the following:

{
    "communicationMediumID": "SAP_COMMUNITY",
    "creationDateTime": "1477297941000",
    "id": "580dc717cd598f001d6cca4c",
    "moderationStatus": "moderation_status_clear",
    "postDepth": 2,
    "postSequence": "13551",
    "processAgentID": "xxxxxxxx",
    "profilePhotoLink": "https://acecorp2.community-demo.sapjam.com/assets/person_shadow_48x48-ec241cfd27fa86867e0279183a2b20c4.png",
    "readFlag": true,
    "socialMediaPostLink": "https://acecorp2.community-demo.sapjam.com/question/3N2cu7tZejBpwXKcVCi984/acecorp2/question-1",
    "socialPostContent": "level 2",
    "socialPostDirection": "OUTBOUND",
    "socialPostID": "NXTCmM7g75LWPCuqgDmGJt",
    "socialPostOrigin": "hkKsEYf9vgT6EBffyxySFr",
    "socialPostParentID": "13550",
    "socialPostRootID": "3N2cu7tZejBpwXKcVCi984",
    "socialPostTitle": "question test",
    "socialUserEmail": "tester@sap.com",
    "socialUserID": "hkKsEYf9vgT6EBffyxySFr",
    "socialUserName": "tester",
    "traits": "answer"
}


Retrieve a Conversation

You can retrieve all messages of a specific conversation from the stored retrieved data. This example shows how to retrieve a conversation by using the attribute id.

Request

  • Method: GET

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/conversations/{conversationId}

  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_view.
  • URI Parameters

    • {tenant}: Name of the current tenant
    • {conversationId}: The unique ID of a specific conversation

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

{
    "communityItemLink": "https://acecorp2-community-demo.sapjam.com/question/z9XeztLVVB9InFHMYbMTPP/acecorp2/11-16-2015-test-question",
    "rootItemFound": true,
    "conversation": {
        "id": "5649f2211e0eab5082610ef5",
        "socialPostID": "m1XI4mFXOd0blUlQOlvuNj",
        "communicationMediumID": "SAP_COMMUNITY",
        "socialPostOrigin": "Ixs0dhgzAyYrz8IcPGoum0",
        "socialUserID": "Ixs0dhgzAyYrz8IcPGoum0",
        "socialUserName": "jingjing ping",
        "socialUserEmail": "23937756@qq.com",
        "socialPostTitle": "11/16/2015 Test Question",
        "socialPostContent": "here is the test question for pushing to cctr",
        "creationDateTime": "1447685788000",
        "socialMediaPostLink": "https://acecorp2-community-demo.sapjam.com/question/z9XeztLVVB9InFHMYbMTPP/acecorp2/11-16-2015-test-question",
        "socialPostDirection": "INBOUND",
        "socialPostParentID": "null",
        "socialPostRootID": "z9XeztLVVB9InFHMYbMTPP",
        "readFlag": false,
        "postSequence": "1648",
        "postDepth": 0,
        "profilePhotoLink": "https://acecorp2-community-demo.sapjam.com/assets/person_shadow_48x48-ec241cfd27fa86867e0279183a2b20c4.png",
        "childNodes": [{
            "id": "5649f2222c8e35e913cfa53c",
            "socialPostID": "3G5ijiC7EzLTIyFXsBIEl1",
            "communicationMediumID": "SAP_COMMUNITY",
            "socialPostOrigin": "Ixs0dhgzAyYrz8IcPGoum0",
            "socialUserID": "Ixs0dhgzAyYrz8IcPGoum0",
            "socialUserName": "jingjing ping",
            "socialUserEmail": "23937756@qq.com",
            "socialPostTitle": "11/16/2015 Test Question",
            "socialPostContent": "test answer comes",
            "creationDateTime": "1447686463000",
            "socialMediaPostLink": "https://acecorp2-community-demo.sapjam.com/question/z9XeztLVVB9InFHMYbMTPP/acecorp2/11-16-2015-test-question",
            "socialPostDirection": "INBOUND",
            "socialPostParentID": "1648",
            "socialPostRootID": "z9XeztLVVB9InFHMYbMTPP",
            "readFlag": false,
            "postSequence": "1649",
            "postDepth": 1,
            "profilePhotoLink": "https://acecorp2-community-demo.sapjam.com/assets/person_shadow_48x48-ec241cfd27fa86867e0279183a2b20c4.png"
        }]
    }
}


Batch Update Posts in a Conversation

Update the read flag and the assigned processor for a specific conversation by using batch processing.

  • readFlag: Indicate whether the message in a specific conversation has been read or not
  • processAgentID: Indicate who has processed the messages in a specific conversation

Request

  • Method: PUT

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/conversations/{conversationId}

  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_manage.
  • URI Parameters

    • {tenant}: Name of the current tenant
    • {conversationId}: The unique ID of a specific conversation
  • Body

    An example JSON content for updating three messages in batch looks similar to the following:

    {
      "conversation": [{
          "socialPostID": "xxxxxxx1",
          "processAgentID": "example agent",
          "readFlag": true
      }, {
          "socialPostID": "xxxxxxx2",
          "processAgentID": "example agent",
          "readFlag": true
      }, {
          "socialPostID": "xxxxxxx3",
          "processAgentID": "example agent",
          "readFlag": true
      }]
    }
    

Response

The successful response returns a 204 status code.


Retrieve Participants in a Conversation

This example shows how to retrieve the information for all participants in a specific conversation.

Request

  • Method: GET

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/conversations/{conversationId}/participants

  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_view.
  • URI Parameters

    • {tenant}: Name of the current tenant
    • {conversationId}: The unique ID of a specific conversation

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

[{
    "socialUserID": "example001",
    "socialUserName": "example user 1",
    "socialUserEmail": "exampleuser1@test.com"
}, {
    "socialUserID": "example002",
    "socialUserName": "example user 2",
    "socialUserEmail": "exampleuser2@test.com"
}, {
    "socialUserID": "example003",
    "socialUserName": "example user 3",
    "socialUserEmail": "exampleuser3@test.com"
}]


Store an SAP Jam Communities User

This example shows how to create a user in by using the Social Media User service:

Request

  • Method: POST

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/users

  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_manage.
  • URI Parameters

    • {tenant}: Name of the current tenant
  • Body: Parameter socialMediaUserID should use the id retrieved from SAP Jam Communities.

    An example JSON content looks similar to the following:

    {
      "socialMediaUserID": "1234567",
      "socialMediaUserAccountName": "Mary",
      "socialMediaEmail": "mary.smith@hybristest.com",
      "creationDateTime": "2015-10-02T14:10:00.000+0000",
      "socialMediaUserProfilePhotoLink": "www.test.com",
      "consentGivenOn": "2015-12-02T14:10:00.000+0000",
      "consentGivenBy": "John Marker",
      "firstName": "Mary",
      "lastName": "Smith",
      "fullName": "Mary Smith",
      "provider": "John Marker",
      "referenceCustomerNumber": "09876"
    }
    

Response

The successful response returns a 201 status code. An example JSON content looks similar to the following:

{
    "id": "580ec812cd598f001d6cd4f9",
    "link": "https://api.us.yaas.io/hybris/dsocialmediauser/v1/cecenterdevman/socialMediaUsers/580ec812cd598f001d6cd4f9"
}

The id that the service returns is the ID of the user stored in the Social Media User service. The attribute link is the URL that leads to the user details.


Retrieve an SAP Jam Communities User

After you save a user in the Social Media User service, you can retrieve the user by using its ID. For more information, see this example:

Request

  • Method: GET

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/users/{userId}

  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_view.
  • URI Parameters

    • {tenant}: Name of the current tenant
    • {userId}: The identifier of user

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

{
    "consentGivenBy": "John Marker",
    "consentGivenOn": "2015-12-02T14:10:00.000+0000",
    "creationDateTime": "2015-10-02T14:10:00.000+0000",
    "firstName": "Mary",
    "fullName": "Mary Smith",
    "lastName": "Smith",
    "provider": "Twitter",
    "referenceCustomerNumber": "09876",
    "socialMediaEmail": "mary.xxx@hybristest.com",
    "socialMediaUserAccountName": "Mary",
    "socialMediaUserID": "246234245tasr",
    "socialMediaUserProfilePhotoLink": "www.facebook.com/useraccount/userprofile/photo.img"
}


Update an SAP Jam Communities User

After the service saves the user, you can update the following attributes of the user:

  • socialMediaUserAccountName: account name of the social media user
  • socialMediaEmail: email of social media user
  • creationDateTime: creation time for social media user
  • socialMediaUserProfilePhotoLink: social media user profile photo URL
  • consentGivenBy: social media user creation consent provider
  • consentGivenOn: time when the consent to create the social media user is given
  • firstName: first name
  • lastName: last name
  • fullName: full name
  • Provider: provider
  • referenceCustomerNumber: reference customer number of the social media user

    You cannot change the id of a social media user.

This example shows how to update a specific user:

Request

  • Method: PUT

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/users/{userId}

  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_manage.
  • URI Parameters

    • {tenant}: Name of the current tenant
    • {userId}: The identifier of user
  • Body: The parameters consentGivenOn and consentGivenBy are required. The other parameters are optional.

    User update uses the replacement mechanism. During the update, the service replaces the stored data for the user with the contents of the update request. For example, if you have saved the attribute provider for a user before and do not want to update its value in the present user update, and do not include it in the update request, the attribute provider is no longer included in the stored user data, after the update. In short, in a user update request, you must also include the stored data that you want to keep, even if you do not want to change it. Otherwise, the service removes the data.

    An example JSON content for updating the socialMediaUserProfilePhotoLink of a user looks similar to the following:

    {
      "consentGivenBy": "admin",
      "consentGivenOn": "2015-12-02T14:10:00.000+0000",
      "creationDateTime": "2015-10-02T14:10:00.000+0000",
      "firstName": "fname",
      "fullName": "fname lname",
      "lastName": "lname",
      "provider": "anony",
      "referenceCustomerNumber": "12345",
      "socialMediaEmail": "xxx.xxxx@sap.com",
      "socialMediaUserAccountName": "tester",
      "socialMediaUserProfilePhotoLink": "www.new.com"
    }
    

Response

The successful response returns a 204 status code.


Anonymize an SAP Jam Communities User

If you anonymize a specific SAP Jam Communities user, the information is removed from the fields that contains personal information. This includes these attributes:

  • socialMediaUserAccountName: account name of the social media user
  • socialMediaEmail: email of social media user
  • creationDateTime: creation time for social media user
  • socialMediaUserProfilePhotoLink: social media user profile photo URL
  • firstName: first name
  • lastName: last name
  • fullName: full name
  • referenceCustomerNumber: reference customer number of the social media user

This example shows how to anonymize a specific user:

Request

  • Method: PUT

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/users/{userId}/anonymize

  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_manage.
  • URI Parameters

    • {tenant}: Name of the current tenant
    • {userId}: The identifier of user

Response

The successful response returns a 204 status code.


Search for SAP Jam Communities Blogs

This example shows how you can search for posts of the type blog in integrated SAP Jam Communities.

Request

  • Method: GET

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/search

  • Headers

    • Authorization: This includes a valid OAuth2 access token
  • URI Parameters

    • {tenant}: Name of the current tenant
  • Query Parameters

    • keywords: mandatory keyword combination to be used for retrieving related documents.
    • pageNumber: the page number to be retrieved where the size of the pages must be specified by the pageSize parameter. The number of the first page is 1.
    • pageSize: the number of documents being retrieved on the page.
    • q: The query string is composed following the patternor().
    • type can be "blog". subType can be "featured_blog".
    • sort: sorting rule. It can be "relevance", "newest", or "oldest".

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

[{
    "title": "the history",
    "type": "blog",
    "subType": "featured_blog",
    "link": "https://cameras61.community-demo.sapjam.com/blog/2KJ33VtrYx53rRl6H4W0nc/cameras61/the-history",
    "highlightedContent": "For example, in 1586, men from a ship commanded by an English explorer named John Davis, went ashore to play a form of football with Inuit (Eskimo) people in Greenland.",
    "fullContent": "some very long article",
    "creatorName": "admincameras61",
    "createdTime": "Sep 07, 2016",
    "topic": "Point and Shoot"
}, {
    "title": "find some other football fans",
    "type": "blog",
    "link": "https://cameras61.community-demo.sapjam.com/blog/A7pZKhfezQoc0fZmEoWAjq/cameras61/find-some-other-football-fans",
    "highlightedContent": "find some other football fans",
    "fullContent": "is there anyone like foot ball?",
    "creatorName": "admincameras61",
    "createdTime": "Sep 06, 2016",
    "topic": "Mirrorless"
}]


Reference Creation

To create a reference, you need:

Request

  • Method: POST

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/references

  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_manage.
  • URI Parameters

    • {tenant}: Name of the current tenant
  • Body

The JSON content looks similar to the example shown:

{
    "knowledgeBaseArticleId": "cgBYJch5Y5mSROnevwfSSr",
    "knowledgeBaseArticleType": "SAP_COMMUNITY_POST",
    "targetObjectType": "SAP_SERVICE_TICKET",
    "targetObjectId": "567890",
    "createdBy": "mary.smith@sap.com"
}

Response

A successful response returns a 201 status code. The JSON content response looks similar to the example shown:

{
  "id": "55473b487deefe21340ae74f",
  "link": "https://api.beta.yaas.io/repository/v2/test/test/data/socialMediaUsers/55473b487deefe21340ae74f"
}


Retrieve a collection of references

To retrieve a collection of references, you need to:

Request

  • Method: GET

  • Request URL: https://api.beta.yaas.io/hybris/sapcommunity/v1/{tenant}/references

  • Headers

    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.sapcommunity_view.
  • URI Parameters

    • {tenant}: Name of the current tenant
  • Query Parameters:

    • q: Use the query to search for specific results. If you do not specify a query, the SAP Jam Communities service returns all references. The SAP Jam Communities service uses the same query syntax as the Document service.
    • sort: Use this query parameter to sort the search results.
    • pageNumber: Use this query parameter to control which page the service retrieves.
    • pageSize: Use this query parameter to control the number of references per page. The maximum value supported for pageSize is 64.

Response

A successful response returns a 200 status code. The JSON content looks similar to the example shown:

[
  {
    "id": "55473b487deefe21340ae74f",
    "knowledgeBaseArticleId": "cgBYJch5Y5mSROnevwfSSr",
    "knowledgeBaseArticleType": "SAP_COMMUNITY_POST",
    "targetObjectType": "SAP_SERVICE_TICKET",
    "targetObjectId": "567890",
    "createdBy": "mary.smith@sap.com"
  },
  {
    "id": "dfdf11511663344556677dsaw",
    "knowledgeBaseArticleId": "2324fafewqr314564fafafd",
    "knowledgeBaseArticleType": "SAP_COMMUNITY_POST",
    "targetObjectType": "SAP_SALES_ORDER",
    "targetObjectId": "148536",
    "createdBy": "mary.smith@sap.com"
  },
]


Error Types

For information about error codes, see the API Reference.


Glossary

TermDescription
harvestRetrieve published data, such as questions and answers.
referenceA reference is a mapping between a knowledge base article and a user-defined object.
SAP Jam CommunitiesA collaborative environment that connects customers, enabling peer reviews, recommendations, and questions and answers on commerce sites. Such communities instill buying confidence, which is shown to increase revenue.


  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.