ExternalStreamInstance

ExternalStreamInstance Service

Web service endpoints for External Stream instances.

To create activity for an External Stream instance you should use the jivelinks version of this service.

Create Extended Properties

POST /extstreams/{externalStreamInstanceID}/extprops

Save a new set of extended properties for a external stream instance with specified name/value pairs, and return an entity representing the newly created extended properties. Any previous extended properties for this external stream instance will be completely replaced.

This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being stored on the target external stream instance will be also associated with the consumer of the oAuth token.

Path Parameters:
NameTypeRequiredDescription
externalStreamInstanceIDStringtrueID of the external stream instance for which to create a extended properties
Takes:
  • ExtProps describing the extended properties to be saved
  • Retrieves:
  • ExtProps representing the newly created extended props
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)The specified instance cannot be found
    400 (Bad Request)An input field is malformed or max number of extended properties has been reached
    403 (Forbidden)You are not allowed to manage ext properties for external stream instance

    Create Extended Properties For Addon

    POST /extstreams/{externalStreamInstanceID}/extprops/addOn/{addonUUID}

    Save a new set of extended properties for a external stream instance with specified characteristics, and return an entity representing the newly created extended properties. Any previous extended properties for this external stream instance will be completely replaced.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, this service will validate that the consumer of the oAuth token can access the specified add-on.

    Path Parameters:
    NameTypeRequiredDescription
    externalStreamInstanceIDStringtrueID of the external stream instance for which to create a extended properties
    addonUUIDStringtrueUUID of the addon for which the properties are created.
    Takes:
  • ExtProps describing the extended properties to be saved
  • Retrieves:
  • ExtProps representing the newly created extended props
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)The specified instance cannot be found
    400 (Bad Request)An input field is malformed or max number of extended properties has been reached
    403 (Forbidden)You are not allowed to manage ext properties for external stream instance
    Since: 3.9

    Create Private Properties

    POST /extstreams/{externalStreamInstanceID}/privateprops

    Save a new set of private properties for a external stream instance with specified name/value pairs, and return an entity representing the newly created private properties. Private properties are scoped to the viewer and are not visible to nor do they overlap with any other user. Any previous private properties for this external stream instance will be completely replaced.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being created on the target external stream instance will be those associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    externalStreamInstanceIDStringtrueID of the external stream instance for which to create a private properties
    Takes:
  • PrivateProps describing the private properties to be saved
  • Retrieves:
  • PrivateProps representing the newly created private props
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)The specified external stream instance cannot be found
    400 (Bad Request)An input field is malformed or max number of private properties has been reached
    403 (Forbidden)You are not allowed to manage ext properties for external stream instance
    Since: 3.10

    Destroy Extended Properties

    DELETE /extstreams/{externalStreamInstanceID}/extprops

    Delete the existing extended properties for the specified external stream instance.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being deleted from the target external stream instance will be also associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    externalStreamInstanceIDStringtrueID of the external stream instance for which the extended properties are to be deleted
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)The specified external stream instance does not exist
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete properties

    Destroy Extended Properties For Addon

    DELETE /extstreams/{externalStreamInstanceID}/extprops/addOn/{addonUUID}

    Delete the existing extended properties for the specified external stream instance.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, this service will validate that the consumer of the oAuth token can access the specified add-on.

    Path Parameters:
    NameTypeRequiredDescription
    externalStreamInstanceIDStringtrueID of the external stream instance for which the extended properties are to be deleted
    addonUUIDStringtrueUUID of the addon for which the properties are deleted.
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)The specified external stream instance does not exist
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete properties
    Since: 3.9

    Destroy Private Properties

    DELETE /extstreams/{externalStreamInstanceID}/privateprops

    Delete the existing private properties for the specified external stream instance.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being deleted from the target external stream instance will be those associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    externalStreamInstanceIDStringtrueID of the external stream instance for which to create a private properties
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)The specified external stream instance does not exist
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete properties
    Since: 3.10

    Get Extended Properties

    GET /extstreams/{externalStreamInstanceID}/extprops

    Return the specified extended properties for the specified external stream instance.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being deleted from the target external stream instance will be also associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    externalStreamInstanceIDStringtrueID of the external stream instance that is associated to the extended properties
    Retrieves:
  • ExtProps containing the specified extended properties
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)If the specified external stream instance does not exist
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to retrieve these properties

    Get Extended Properties For Addon

    GET /extstreams/{externalStreamInstanceID}/extprops/addOn/{addonUUID}

    Return the specified extended properties for the specified external stream instance.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, this service will validate that the consumer of the oAuth token can access the specified add-on.

    Path Parameters:
    NameTypeRequiredDescription
    externalStreamInstanceIDStringtrueID of the external stream instance that is associated to the extended properties
    addonUUIDStringtrueUUID of the addon for which the properties are fetched.
    Retrieves:
  • ExtProps containing the specified extended properties
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)If the specified external stream instance does not exist
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to retrieve these properties
    Since: 3.9

    Get Instance

    GET /extstreams/{externalStreamInstanceID}

    Return the specified external stream instance with the specified fields.

    Path Parameters:
    NameTypeRequiredDescription
    externalStreamInstanceIDStringtrueID of the external stream instance to be returned
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned (default is "@all")
    Retrieves:
  • ExternalStreamInstance containing the specified instance
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified external stream instance
    404 (Not Found)The specified external stream instance does not exist

    Get Instance By External ID

    GET /extstreams/external/{extensionUUID}/{externalID}

    Return the specified external stream instance with the specified fields.

    Path Parameters:
    NameTypeRequiredDescription
    extensionUUIDStringtrueThe UUID of the add-on in which the external stream is defined
    externalIDStringtrueThe external ID of the external stream instance to be returned
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseID of the external stream instance to be returned
    Retrieves:
  • ExternalStreamInstance containing the specified instance
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified external stream instance
    404 (Not Found)The specified external stream instance does not exist

    Get Instances

    GET /extstreams

    Return a paginated list of external stream instances that match the specified filter criteria.

    This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.

    Filter Params Example
    tilePage one Page URI ?filter=author(http://domain/api/core/v3/pages/1234)

    This service supports the following sort types.

    Sort Description
    dateCreatedAsc Sort by the date this instance was created, in ascending order
    dateCreatedDesc Sort by the date this instance was created, in descending order. Default if none was specified.
    Query Parameters:
    NameTypeRequiredDescription
    sortStringfalseThe requested sort order
    startIndexIntegerfalseThe zero-relative index of the first matching instance to be returned
    countIntegerfalseThe maximum number of instances to be returned
    fieldsStringfalseThe fields to be returned on each instance
    Takes:
  • filters
  • Retrieves:
  • ExternalStreamInstance[] of the matched external stream instances
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed

    Get Private Properties

    GET /extstreams/{externalStreamInstanceID}/privateprops

    Return the private properties for the specified external stream instance. Private properties are scoped to the viewer and are not visible to nor do they overlap with any other user.

    This service only accepts oAuth authentication. Assuming that the oAuth token used to access this service was acquired through 2-legged oAuth, the properties being created on the target external stream instance will be those associated with the consumer of the oAuth token.

    Path Parameters:
    NameTypeRequiredDescription
    externalStreamInstanceIDStringtrueID of the external stream instance for which to create a private properties
    Takes:
  • PrivateProps describing the private properties to be saved
  • Retrieves:
  • PrivateProps containing the specified private properties
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    401 (Unauthorized)Authentication credentials were not provided or are incorrect
    410 (Gone)Instance is no longer available
    404 (Not Found)If the specified external stream instance does not exist
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to retrieve these properties
    Since: 3.10

    Create Activity

    POST /extstreams/activities/external/{extensionUUID}/{externalID}/{privatePath}

    Create a new external stream activity entity.

    This service does not require authentication and can be used anonymously. The parameters extensionUUID, externalID, and privatePath are all available through the UI after installation.

    When an AddOn is installed into Jive, contained ExternalStreamDefinition will be imported. Each ExternalStreamDefinition that supports this functionality for easily creating new external stream activities, will also include a transformation definition. These transformations are going to be used to convert the payload of this call into a format that can be understood by Jive. If the payload fails to be transformed into Jive's format, a Bad Request (error 400) will be returned.

    Below is an example of a payload received by this service before it was converted

         {
              "entry": {
                  "image": "http://external.crm/og/id/123.png",
                  "title": "Acme Corp Opportunity",
                  "description": "Selling to Acme Corp",
                  "url": "http://external.crm/og/id/123"
              }
         }
     
    ... or ...
      curl -i -X POST  -H "application/x-www-form-urlencoded"
                       -d "subject=Published a blog entry today"
                       -d "type=website update"
                       -d "url=http://URL_TO_MY_BLOG/2015/03/03/world/paris-skeletons-found/blog.html"
                           http://JIVE_INSTANCE/api/core/v3/extstreams/activities/external/xyz/123/abc
      

    and this is the JSON format as understood by Jive after the transformation

       {
          "activity: {
              "action": {
                  "name": "updated",                               // Optional: actionName          Max 127 characters
                  "description": "Updated an opportunity",         // Optional: actionDescription   Max 255 characters
              },
              "actor": {
                  "name": "John Smith",                            // Optional: attributionName     Max 127 characters
                  "email": "john.smith@jivesoftware.com"           // Optional: attributionEmail    Max 127 characters
              },
              "object": {
                  "type": "jive:opportunity",                      // Required: openGraphType       Max 127 characters
                  "url": "http://external.crm/og/id/123",          // Required: externalURL         Max 1024 characters
                  "image": "http://external.crm/og/id/123.png",    // Optional: imageURL            Max 1024 characters
                  "title": "Acme Corp Opportunity",                // Required: subject             Max 255 characters
                  "description": "Selling to Acme Corp"            // Optional
              }
          }
       }
     

    For convenience, errors while pushing new activity can be seen from the UI when configuring the external stream instance. This will let community admins easily test things and troubleshoot problems without the need to look into logs or trace network calls.

    Example:
      curl -i -X POST  -H "Content-Type: application/json"  -d
      '{"myActivity":
          {
              "subject": "Acme Corp Opportunity",
              "url": "http://URL_TO_MY_BLOG/2015/03/03/world/paris-skeletons-found/blog.html"
          }
      }'
      http://JIVE_INSTANCE/api/core/v3/extstreams/activities/external/xyz/123/abc
      
    ... or ...
      curl -i -X POST  -H "application/x-www-form-urlencoded"
                       -d "subject=Published a blog entry today"
                       -d "type=website update"
                       -d "url=http://URL_TO_MY_BLOG/2015/03/03/world/paris-skeletons-found/blog.html"
                           http://JIVE_INSTANCE/api/core/v3/extstreams/activities/external/xyz/123/abc
      

    The transformation configured with the external stream instance, then processes the above payload to something like:

      {"activity":
          {
              "action": {
                  "name": "posted a blog"
              },
              "object": {
                  "image": "http://www.nasa.gov/sites/default/themes/NASAPortal/images/nasa-logo.gif",
                  "title": "Acme Corp Opportunity",
                  "type": "website update",
                  "url": "http://URL_TO_MY_BLOG/2015/03/03/world/paris-skeletons-found/blog.html"
              }
          }
      }
      
    Path Parameters:
    NameTypeRequiredDescription
    extensionUUIDStringtrueThe UUID of the add-on in which the external stream is defined
    externalIDStringtrueThe external ID of the external stream instance
    privatePathStringtrueThe unique private path assigned to the external stream instance for accepting activities
    Retrieves:
  • ExternalStreamActivity representing the newly external stream activity entity
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    410 (Gone)Instance is no longer available
    404 (Not Found)The specified external stream instance cannot be found
    400 (Bad Request)An input field is malformed
    Since: 3.11