Compliance Guide

The Events API and the compliance features described in this guide are currently pre-release features which are not available to all Cisco Spark users. If you have any questions, or if you need help, please contact the Cisco Spark DevSupport team at devsupport@ciscospark.com.

Table of Contents

Introduction

Cisco Spark™ is an end-to-end encrypted cloud collaboration platform. Organizations have exclusive control over the management of their encryption keys as well as the confidentiality of their data. Because we recognize that some data in Cisco Spark may involve access to sensitive information about users and accounts, we built the Cisco Spark Control Hub to support multiple types of administrator roles with access to different subsets of information. The Cisco Spark Control Hub provides a full-service management experience supporting trials, purchasing, account configuration, adoption, and customer support. For more information about the Cisco Spark Control Hub, please see this data sheet.

Within the Cisco Spark Control Hub, you can now associate administrative users with a new role to ensure that the data within Cisco Spark remains in compliance with the legal standards in effect for an organization. This role is known as the Compliance Officer. Compliance officers will be able to use the Cisco Spark API to access information within Cisco Spark to aid in compliance activities for their organization.

Additionally, the Cisco Spark API includes an Events API endpoint, which authorized third-party software can use to access, monitor, and archive the data created and shared by Cisco Spark users within an organization.

This guide will provide more detail about the new Compliance Officer role, the Events API endpoint, and the types of permissions that can be used for data monitoring and management within Cisco Spark. It will also describe the monitoring controls that can be put into place to ensure that all activities within Cisco Spark are in full compliance with accepted business practices and internal standards.

Cisco Spark Data

Permissions & Ownership

Data that is created within Cisco Spark is owned by the person, or organization, that created the room. Data access permissions within Cisco Spark vary depending on a few factors: the room creator, room membership, and organization membership. When a room is created, the organization associated with the creator is considered the owning organization for the room. If users from other organizations are added to the room, those organizations are participating organizations in the room.

In general, the following types of users will be viewing and creating data within Cisco Spark:

  • Owning organization—can moderate and manage all data within rooms created by a member of the organization.
  • Room moderator—users can be assigned as a moderator by a room owner and have exclusive control of the room including the room’s title and participant list.
  • Room participants—can send and view messages within the room.
  • Compliance officers for the owning organization—can moderate or manage rooms as necessary to mitigate any issues that are not in compliance with the organization.
  • Compliance officers for the participating organization—can monitor data that has been created by their users only. They cannot monitor all data in the room if their organization is not the owning organization.

Note: The compliance officer for the organization that owns the room will be able to monitor all data created within that room. Whereas the compliance officer of a participating organization can only see their messages in a room which is owned by another organization.

Security & Privacy

For more information about Cisco Spark's data security and privacy, please see the Cisco Spark Security White Paper.

Compliance

Compliance Officer

The role of a compliance officer is to ensure that a company is conducting its business in full compliance with all laws and regulations that pertain to its particular industry, as well as professional standards, accepted business practices, and internal standards.

The Cisco Spark API has compliance authorization scopes that support the compliance officer’s role. Using these spark-compliance scopes, compliance officers will have access to and management of all data created by their organization including messages, content attachments, etc. in order to monitor data and to mitigate compliance issues that could arise.

Authorization Scopes

The spark-compliance scopes and their descriptions are listed below:

Scope Usage
spark-compliance:events_read Access to read events in your user's organization
spark-compliance:memberships_read Access to read memberships in your user's organization
spark-compliance:memberships_write Access to delete memberships in all spaces in your user's organization
spark-compliance:messages_read Access to read messages in your user's organization
spark-compliance:messages_write Access to delete messages in all spaces in your user's organization
spark-compliance:rooms_read Access to read rooms in your user's organization
spark-compliance:teams_read Access to read teams in your user's organization

For instructions on how to add these scopes to your app and for a full list of all available authorization scopes see the Integrations/OAuth Guide.

Using the Compliance Scopes

Normally, Cisco Spark API users only have access to information related to their account, such as messages in rooms where they are members. The spark-compliance scopes provide access to information across the organization. For instance, if granted the spark-compliance:messages_read scope, messages will be available for all rooms within the organization, not just those that the authenticated compliance officer is a member of.

Several scopes provide access to write data or take action within an organization. If an action should be taken against certain data within Cisco Spark for compliance reasons, the Cisco Spark API can be used with an authentication token authorized with one of the above scopes to carry out the action. For example, if a message needs to be deleted, the spark-compliance:messages_write scope will be required. To delete the message, use the DELETE /messages endpoint to delete the message. By using the spark-compliance:message_write scope, the authenticated user does not need to be a member of the room.

Events

Introduction

The Events API endpoint gives developers access to events happening with their Cisco Spark organization. Events can be integrated with Data Loss Prevention (DLP) software to check for policy violations and take action to resolve any issues. The events available for monitoring include posting messages, sending content such as files, and adding users to spaces. The Events API endpoint can be integrated with your existing archiving software to archive an unlimited amount of Cisco Spark data. For access to events older than 90 days, the organization will need the Pro Pack for Cisco Spark Control Hub.

Use the Events API endpoint to access activities after they have occurred. Perhaps you need to retrieve every message sent by a particular user to comply with a legal discovery process, or you need to know which rooms someone joined and left. The Events API endpoint will give you access to this information quickly and securely.

Events are available for the following API resources whenever they are created, updated, or deleted:

Authorization Scopes

One scope for Events is available. Note that in order to use a spark-compliance scope you will need to be a designated compliance officer for your organization in the Cisco Spark Control Hub. For instructions on how to add these scopes to your app and for a full list of all available authorization scopes see the Integrations/OAuth Guide.

Scope Usage
spark-compliance:events_read Access to read events in your user's organization

Using Events

With the Events API endpoint you can retrieve information about user activities in Cisco Spark such as message activity in spaces, content or files shared, or user membership changes in spaces.

The spark-compliance:events_read scope can be used by compliance officers to retrieve events for the entire organization.

When requesting a list of events from the API, the result may be split into pages. See the Pagination guide to learn how to navigate through paged API responses.

Example: Retrieve Created Messages

To retrieve all messages that have been created, use the List Events endpoint. Use URL query parameters to limit the response to include only events related to the messages resource and only created items by using: resource=messages&type=created.

GET https://api.ciscospark.com/v1/events?resource=messages&type=created

{
  "items" : [ {
    "id" : "Y2lzY29zcGFyazovL3VzL0VWRU5UL2JiY2ViMWFkLTQzZjEtM2I1OC05MTQ3LWYxNGJiMGM0ZDE1NAo",
    "resource" : "messages",
    "type" : "created",
    "actorId" : "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
    "orgId" : "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
    "appId" : "null",
    "created" : "2015-10-18T14:26:16+00:00",
    "data" : {
      "id" : "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvOTJkYjNiZTAtNDNiZC0xMWU2LThhZTktZGQ1YjNkZmM1NjVk",
      "roomId" : "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
      "roomType" : "group",
      "text" : "PROJECT UPDATE - A new project plan has been published on Box: http://box.com/s/lf5vj. The PM for this project is Mike C. and the Engineering Manager is Jane W.",
      "personId" : "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
      "personEmail" : "matt@example.com",
      "created" : "2015-10-18T14:26:16+00:00"
    }
  } ]
}

In this example response, only one record is returned, but let's take a look at it in detail.

{
  "items" : [ {
    "id" : "Y2lzY29zcGFyazovL3VzL0VWRU5UL2JiY2ViMWFkLTQzZjEtM2I1OC05MTQ3LWYxNGJiMGM0ZDE1NAo",
    "resource" : "messages",
    "type" : "created",
    "actorId" : "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
    "orgId" : "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
    "appId" : "null",
    "created" : "2015-10-18T14:26:16+00:00",
    "data" : {
      ... omitted ...
    }
  } ]
}

Each event object returned will contain several fields which describe the event. This includes:

  • id—a unique ID for the event
  • resource—which resource the event includes
  • type—the type of action which took place, such as created or deleted
  • actorId—the ID of the person which committed the activity for this event
  • orgId—the ID of the organization for the actor
  • appId—the ID of the integration or bot which committed the activity for this event
  • created—when the event took place
  • data—the data for the event

{
  "items" : [ {
    ... omitted ...
    "data" : {
      "id" : "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvOTJkYjNiZTAtNDNiZC0xMWU2LThhZTktZGQ1YjNkZmM1NjVk",
      "roomId" : "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
      "roomType" : "group",
      "text" : "PROJECT UPDATE - A new project plan has been published on Box: http://box.com/s/lf5vj. The PM for this project is Mike C. and the Engineering Manager is Jane W.",
      "personId" : "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
      "personEmail" : "matt@example.com",
      "created" : "2015-10-18T14:26:16+00:00"
    }
  } ]
}

Inside of each event object, the data object will contain an object which represents the Cisco Spark API resource at the time the event took place. For instance, in this event, a message object is returned to represent the message at the time of its creation.

For more information about how to use the Events API endpoint, please see the Events API Reference.