Wave REST API Developer Guide

Transcription

1 Wave REST API Developer Guide Salesforce, Spring Last updated: March 17, 2017

2 Copyright salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc., as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.

3 CONTENTS WORKING WITH THE WAVE REST API Wave REST API Overview Wave REST API Authentication WAVE REST API REFERENCE Wave REST API Resources Overview Wave Resource Query Resource Charts Geodata List Resource Charts Geodata Resource Charts Geodata File List Resource Charts Maps List Resource Charts Maps Resource Datasets List Resource Dataset Resource s List Resource Resource File Resource XMD List Resource XMD Resource Lenses List Resource Lens Resource Lens File Resource Lens File Metadata Resource Dashboards List Resource Dashboard Resource Dependencies Resource Features Configuration Resource Folders List Resource Folder Resource Replicated Datasets Resource Replicated Datasets List Resource Replicated Dataset Fields Resource Templates List Resource Templates Resource Templates Configuration Resource Template Release Notes Resource Trended Reports List Resource Trended Reports Resource

4 Contents Annotations List Resource Annotation Resource

5 WORKING WITH THE WAVE REST API Wave REST API Overview You can access Wave Analytics datasets and lenses programmatically using the Wave REST API. Using the Wave REST API, you can: Send queries directly to the Wave Platform. Access datasets that have been imported into the Wave Platform. Create and retrieve Wave Analytics lenses. Access XMD information. Retrieve a list of dataset versions. Create and retrieve Wave Analytics applications. Create, update, and retrieve Wave Analytics dashboards. Retrieve a list of dependencies for an application. Determine what features are available to the user. Work with and schedule Trend in Wave report snapshots. Manipulate replicated datasets. Get, add, update, and delete eclair geo map charts. The Wave REST API is based on the Chatter REST API and follows its conventions. For more information about the Chatter REST API, see the Chatter REST API Developer Guide. Important: The internal API, that was previously used in the Wave UI, also labeled as private and for Salesforce only, is not supported. This internal API will be depricated, as first noted in API version 36. Clients using this internal private API will not have access to any newly created or updated dashboard assets created using tools in the latest release. We encourage developers of such clients to port them to the Wave API GA. Wave REST API Authentication Salesforce uses the OAuth protocol to allow users of applications to securely access data without having to reveal username and password credentials. The following sections introduce authentication and provide the steps you need to follow to set up authorization and connect to Wave REST API using OAuth. Understanding Authentication Before making API calls using the Wave API, you must authenticate the application user using OAuth 2.0. To do so, you ll need to do the following: Set up your application as a connected app in the Salesforce organization. Determine the correct Salesforce OAuth endpoint for your connected app to use. 1

6 Working with the Wave REST API Wave REST API Authentication Authenticate the connected app user via one of several different OAuth 2.0 authentication flows. An OAuth authentication flow defines a series of steps used to coordinate the authentication process between your application and Salesforce. Supported OAuth flows include the following: Web server flow, where the server can securely protect the consumer secret. User-agent flow, used by applications that cannot securely store the consumer secret. Username-password flow, where the application has direct access to user credentials. Set Up Authorization Create a connected app in a Salesforce organization and enable OAuth. The client application uses the connected app to connect to Salesforce. 1. In your Salesforce organization, from Setup, click Create Apps, and in the Connected Apps section, click New to create a new connected app. 2. Clients can use a connected app to sign in to any organization, even if the connected app isn t defined in that organization. 3. Enter a connected app name. 4. Select Enable OAuth Settings. 5. Enter a Callback URL. It must be secure: use and not 6. Enter an OAuth scope. Select Access and manage your data (api) in addition to any other scope you want your connected app to allow access to. 7. Click Save. 8. The Consumer Key is created and displayed, and a Consumer Secret is created (click the link to reveal it). Connect to Wave REST API Using OAuth Use OAuth to connect to Salesforce and get an access token. Pass the access token in requests to Wave API. This table maps the terms used in the connected app you created to the OAuth properties used in the examples. The OAuth 2.0 specification uses the word client instead of consumer. Connected App Application Label Consumer Key Consumer Secret Value in Example client_id Key client_secret Note: The instructions here use the username-password OAuth authentication flow. The username-password authentication flow passes the user s credentials back and forth. Use this authentication flow only when necessary. No refresh token will be issued. To make a request to Salesforce, substitute values from your organization into these examples: 1. Generate the access token. This curl command generates an access token: curl --form client_id=3mvg9phr6g6b7ps4xdycwgri4pvjvzvk9 --form client_secret=

7 Working with the Wave REST API Wave REST API Authentication --form grant_type=password --form --form password=1lsfdc! Note: To paste a multiline command into a Mac or Linux command line interface, escape each line with a backslash ( \ ) to indicate that the command continues on the next line. An escaped line looks like this: curl --form client_id=3mvg9phr6g6b7ps4xdycwgri4pvjvzvk9 \ To paste a multi-line command into the Windows Command Prompt, escape each line with a caret ( ^ ). An escaped line looks like this: curl --form client_id=3mvg9phr6g6b7ps4xdycwgri4pvjvzvk9 ^ The response includes the server instance and the access token: { "id":" "issued_at":" ", "instance_url":" "signature":"5jcevy5fuai0lwntusxkwbzwcvrjd01rcokibzpygv0=", "access_token":"00dd fj6t!aqkaqpde_dmf2vgzddfzmbrs95gojdbta rkkgukagzp0ovfyy5kkaqhlw9ejekilpj3fgwgawerlbiwrt8mfxeuazgbznosk" } 2. To request a Wave REST API resource, use the returned instance_url as the server instance. Pass the returned access_token as a Bearer token in the Authorization request header. curl -X GET -H 'Authorization: Bearer 00DD FJ6T!AQkAQPde_DMF2vGzddfZmBRS95Goj DbtArKkgukAgZP0OVFYY5KkAqhLw9ejeKIlpJ3FgwGAWeRlBiWRt8mfXEuAZGbZNosk' Property Server instance client_id client_secret grant_type username password Value in Example yourinstance.salesforce.com 3MVG9PhR6g6B7ps4xDycwGrI4PvjVZvK password The value of grant_type depends on the OAuth authentication flow you use admin@seattleapps.com 1Lsfdc! 3

8 WAVE REST API REFERENCE Wave REST API Resources Overview The Wave REST API provides resources so you can access your Wave Analytics data. All Wave REST API resources are accessed using: A base URI for your company (for example, information (for example, /services/data/v) A named resource (for example, /wave) Put together, an example of the full URL to the resource is: hhttps://yourinstance.salesforce.com/services/data/v/wave Org and Object Identifiers Id fields in Salesforce, and in the Wave UI, are typically 15-character, base-62, case-sensitive strings. This is true of JSON XMD too. However, many Salesforce APIs, including the Wave REST API, use 18-character, case-insensitive strings for example, the Id property of the Dataset resource/wave/datasets/<dataset ID>. The last three digits are a checksum of the preceding 15 characters. The use of case-insensitive Id s eases interaction with external applications and development environments that use case-insensitive references. To convert an 18-character Id back to a 15-character ID, simply remove the last three characters. Resource Supported HTTP Method Resource URL Wave Resource Lists the top-level resources available for Wave Analytics. GET /wave Query Resource Executes a query written in Salesforce Analytics Query Language (SAQL). POST /wave/query Datasets List Resource Returns a list of Wave Analytics datasets. GET /wave/datasets Dataset Resource Returns the Wave Analytics dataset with the specified ID, deletes a dataset (DELETE), or updates a dataset (PATCH). GET, DELETE, PATCH /wave/datasets/<dataset ID> s List Resource Returns a collection of dataset versions for a particular dataset. GET /wave/datasets/<dataset ID> /versions Resource Returns a Wave Analytics dataset version (GET), or updates the predicate (PATCH). GET, PATCH /wave/datasets/<dataset ID> /versions/<version ID> File Resource Provides access to the binary content of the dataset file. GET /wave/datasets/<dataset ID> /versions/<version ID> /files/<file ID> 4

9 Wave REST API Resources Overview Resource Supported HTTP Method Resource URL XMD List Resource Returns a list of XMD resources for a version of a dataset. GET /wave/datasets/<dataset ID> /versions/<version ID>/xmds XMD Resource Returns the extended metadata (XMD) for a version of a dataset (GET) and replaces the user XMD file (PUT). GET, PUT /wave/datasets/<dataset ID> /versions/<version ID>/xmds/<XMD type> Lenses List Resource Returns a list of Wave Analytics lenses (GET), or creates a lens (POST). GET, POST /wave/lenses Lens Resource Returns a JSON file that describes the structure of a Wave Analytics lens with the specified ID (GET), deletes a lens (DELETE), or updates a lens (PATCH). GET, DELETE, POST /wave/lenses/<lens ID> Lens File Resource Returns a file that is part of a Wave Analytics lens. GET, PUT /wave/lenses/<lenses ID> /files/<files ID> Dashboards List Resource Returns a list of Wave Analytics dashboards, or creates a dashboard. GET, POST /wave/dashboards Dashboard Resource Returns or updates the dashboard with the specified ID or API name. GET, DELETE, PATCH /wave/dashboards/<dashboard ID> Dependencies Resource Returns the dependencies for an application (folder). GET /wave/dependencies/<folder ID> Folders List Resource Creates a Wave Analytics application (POST), which is a folder that contains Wave datasets, lenses, and dashboards, or returns a collection of applications or folders (GET). GET, POST /wave/folders Folder Resource Replicated Datasets Resource Returns the representation for a Wave Analytics application or folder (GET), replaces an application or folder (PUT), updates it (PATCH), or deletes it (DELETE). Replicates data from an external Source Object into a Wave as a dataset. Replicated Datasets are not intended to be visualized directly, but are used like a cache to speed up other workflows which refer to the same source object. GET, PUT, PATCH, DELETE GET, PATCH, DELETE /wave/folders/<folder ID> /wave/replicateddatasets/<id> Replicated Datasets List Resource Returns a list of replicated datasets. GET, POST wave/replicateddatasets Replicated Dataset Fields Resource A list of Replicated Fields for a particular Replicated Dataset. GET, PATCH /wave/replicateddatasets/<id>/fields 5

10 Wave REST API Resources Overview Resource Supported HTTP Method Resource URL Templates List Resource Returns a list of Wave Analytics templates, or adds a template. GET /wave/templates Templates Resource Returns a list of Wave Analytics templates, or adds a template. GET /wave/templates /<templateidorapiname> Templates Configuration Resource Returns the configuration of a Wave Analytics template. GET /wave/templates /<templateidorapiname> /configuration Trended Reports List Resource Returns or adds to a collection of Trending Reports. GET, POST /wave/trendedreports Trended Reports Resource Returns, deletes, or updates a Trending Report. DELETE, GET, PATCH /wave/trendedreports/<id> Lens File Metadata Resource Resource for management of Wave lens file metadata. GET, POST /wave/lenses/<lensid>/files Features Configuration Resource The Wave features that are available to a user. GET /wave/config/features Annotations List Resource on page 138 A collection of annotations. GET, POST /wave/annotations Annotations Resource on page 139 An asset's annotations. GET, PATCH /wave/annotations/<annotation ID> Template Release Notes Resource on page 129 Resource for retrieving the release notes for a single Wave Analytics Template. GET /wave/templates/<templateidorapiname>/releasenotes Charts Maps List Resource on page 12 Get the collection of maps, or post a new map. GET POST /eclair/maps Charts Maps Resource on page 16 Get, update, or delete a specific map. DELETE GET PATCH /eclair/maps/<id> Charts Geodata Resource on page 11 Get, update, or delete a specific geodata definition. DELETE GET PATCH /eclair/geodata/<id> 6

11 Wave Resource Resource Supported HTTP Method Resource URL Charts Geodata List Resource on page 9 Charts Geodata File List Resource on page 12 Get the collection of geodata definitions, or post a new one. Get the binary file associated with a geodata definition. GET POST GET /eclair/geodata /eclair/geodata/<id>/file Filtering REST Responses Returns the representation for a Wave Analytics application or folder (GET), replaces an application or folder (PUT), updates it (PATCH), or deletes it (DELETE). In addition to Wave REST API input parameters, you can use the following Chatter REST API input parameters to filter the results returned from a request: filtergroup, external, and internal. For more information, see Specifying Response Sizes in the Chatter REST API Developer Guide. Wave Resource Lists the top-level resources available for Wave Analytics. Resource URL /wave Formats JSON HTTP Methods GET GET Response Body Filter Group and datasets The URL to the datasets resource for the organization. Small, lenses The URL to the lenses resource for the organization. Small, query The URL to the query resource for the organization. Small, Example Response Body { "datasets" : "/services/data/v/wave/datasets", 7

12 Query Resource } "lenses" : "/services/data/v/wave/lenses", "query" : "/services/data/v/wave/query" Query Resource Executes a query written in Salesforce Analytics Query Language (SAQL). Resource URL /wave/query Formats JSON HTTP Methods POST POST Request Body query The SAQL query in JSON format. Required Example Request Body { } "query":"q = load \"0Fbxx CAA/0Fcxx dCAA\"; q = group q by 'FirstName'; q = foreach q generate 'FirstName' as 'FirstName', count() as 'count'; q = limit q 2000;" POST Response Body json The results of a SAQL query, in JSON format. Small, Example Response Body { "action":"query", "responseid":"3vy-e9ymx-tiwe0769jud-", "results": { "records":[ {"FirstName":"","count":1}, 8

13 Charts Geodata List Resource } {"FirstName":"Admin","count":1}, {"FirstName":"Integration","count":1}, {"FirstName":"Security","count":1}]}, "query":"q = load \"0Fbxx CAA/0Fcxx dCAA\"; q = group q by 'FirstName'; q = foreach q generate 'FirstName' as 'FirstName', count() as 'count'; q = limit q 2000;", "responsetime":544 For more information about creating SAQL queries, see Wave Analytics SAQL Reference. Charts Geodata List Resource Get the collection of geodata definitions, or post a new one. Resource URL /eclair/geodata Formats JSON HTTP Methods GET POST GET Request Parameters Parameter Name page Int The page number you want to view. pagesize Int How many items you want to view on each page, up to 500. GET Response Body GeoDataCollection POST Request Parameters Parameter Name geodatafile Binary The geojson file you want to upload. geodataobject Object (GeoDataInput) List of all relevant information about the GeoData, i.e. { "label": "My GeoData" }. 9

14 Charts Geodata List Resource POST Request Body GeoDataInput POST Response Body GeoData GeoDataCollection geodata GeoData [] A list of the geodata. Small, GeoData id The ID of this geo data record. Small, label The user set name for the geo data. Small, name The developer name for the geo data. Small, namespace The namespace of the geo data. Small, type ConnectEclairGeo DataEnum The type of geo data (currently just GeoJSON). Small, url The url to retrieve the geodata. Small, GeoDataInput label Sets the GeoData label. name Sets the GeoData developer name. Example curl request to create a geodata resource from a GeoJson file curl -H "X-PrettyPrint: 1" \ -F 'json={"label": "GeoJsonLabel","name": "<developer_name>"};type=application/json' \ -F "geodatafile=@yourgeonjsonfile.json" \ -X POST \ \ -H 'Authorization: OAuth Oauth Token' 10

15 Charts Geodata Resource Example Response Body { } "id" : "05oP LIAQ", "label" : "GeoJsonLabel", "name" : "<developer_name>", "type" : "geojson", "url" : "/services/data/v/eclair/geodata/05op liaq/file" Charts Geodata Resource Get, update, or delete a specific geodata definition. Resource URL /eclair/geodata/<id> Formats JSON HTTP Methods DELETE GET PATCH GET Response Body GeoData id The ID of this geo data record. Small, label The user set name for the geo data. Small, name The developer name for the geo data. Small, namespace The namespace of the geo data. Small, type ConnectEclairGeo DataEnum The type of geo data (currently just GeoJSON). Small, url The url to retrieve the geodata. Small, PATCH Request Parameters Parameter Name geodatafile Binary The geojson file you want to upload. geodataobject Object (GeoDataInput) List of all relevant information about the GeoData, i.e. { "label": "My GeoData" }. 11

16 Charts Geodata File List Resource PATCH Request Body GeoDataInput label Sets the GeoData label. name Sets the GeoData developer name. PATCH Response Body GeoData id The ID of this geo data record. Small, label The user set name for the geo data. Small, name The developer name for the geo data. Small, namespace The namespace of the geo data. Small, type ConnectEclairGeo DataEnum The type of geo data (currently just GeoJSON). Small, url The url to retrieve the geodata. Small, Charts Geodata File List Resource Get the binary file associated with a geodata definition. Resource URL /eclair/geodata/<id>/file Formats JSON HTTP Methods GET GET Response Body Streamed. Returns a binary stream of the contents of the specified file. Charts Maps List Resource Get the collection of maps, or post a new map. 12

17 Charts Maps List Resource Resource URL /eclair/maps Formats JSON HTTP Methods GET POST GET Request Parameters Parameter Name page Int The page number you want to view. pagesize Int How many items you want to view on each page, up to 500. GET Response Body MapCollection maps Map [] The list of the collection. Small, POST Request Parameters Parameter Name geomapobject Object (MapInput) List of all relevant information about the map, i.e. { "label": "My Map" }. POST Request Body MapInput boundingbox MapBoundingBox Input Sets the Map bounding box. geodata AssetReference Input Sets the parent GeoData. 13

18 Charts Maps List Resource label Sets the Map label. name Sets the Map name projection ConnectEclairMap Projection Enum Sets the Map projection (AlbersUSA, Equirectangular, or Mercator) POST Response Body Map boundingbox BoundingBox The bounding box of the geo map Small, createdby User The creator of the map Small, createddate Date The date when this map was created Small, geodata GeoData The geo data of the map Small, id The 18 character user ID Small, label The label of the map Small, name The name of the map Small, namespace The namespace of the map Small, projection ConnectEclairMap Projection Enum The projection used by the map (AlbersUSA, Equirectangular, or Mercator) Small, url The url to the map representation Small, MapBoundingBoxInput bottom Double The bottom boundary of the geo map Required left Double The left boundary of the geo map Required right Double The right boundary of the geo map Required top Double The top boundary of the geo map Required 14

19 Charts Maps List Resource BoundingBox bottom Double The bottom boundary of the geo map Small, left Double The left boundary of the geo map Small, right Double The right boundary of the geo map Small, top Double The top boundary of the geo map Small, User id The 18 character user ID Small, name The name of the user Small, Example curl request (without bounding boxes) curl -H "X-PrettyPrint: 1" \ -d '{"geodata": {"id": "<id_of_geodata_resource>"},"name": "<developer_name_for_map>","label": "<display_label_for_map>","projection": "equirectangular"}' \ -F "geodatafile=@yourgeonjsonfile.json" \ -X POST \ \ -H 'Authorization: OAuth Oauth Token' Example Response Body { "boundingbox": {}, "createdby": { "id": "005G KRG3IAO", "name": "Anand B Narasimhan" }, "createddate": " T13:18:53.000Z", "geodata": { "id": "05oP BIAQ", "label": "PA_Territories", "name": "PA_Territories", "type": "geojson", "url": "/services/data/v/eclair/geodata/05op biaq/file" }, "id": "05pP aIAA", "label": "map_lable", "name": "map_name", "projection": "equirectangular", 15

20 Charts Maps Resource } "url": "/services/data/v/eclair/maps/05pp aiaa" Example curl request (with bounding boxes) curl -H "X-PrettyPrint: 1" \ -d '{"boundingbox": {"bottom": ,"left": ,"right": ,"top": },\ "geodata": {"id": "id_of_geodata_resource"},"name": "<developer_name_for_map>",\ "label": "<display_label_for_map>","projection": "equirectangular"}' \ -F "geodatafile=@yourgeonjsonfile.json" \ -X POST \ \ -H 'Authorization: OAuth Oauth Token' Example Response Body { } "boundingbox": { "bottom": , "left": , "right": , "top": }, "createdby": { "id": "005G KRG3IAO", "name": "Anand B Narasimhan" }, "createddate": " T13:18:53.000Z", "geodata": { "id": "05oP BIAQ", "label": "PA_Territories", "name": "PA_Territories", "type": "geojson", "url": "/services/data/v/eclair/geodata/05op biaq/file" }, "id": "05pP aIAA", "label": "map_label", "name": "map_name", "projection": "equirectangular", "url": "/services/data/v/eclair/maps/05pp aiaa" Charts Maps Resource Get, update, or delete a specific map. Resource URL /eclair/maps/<id> Formats JSON 16

21 Charts Maps Resource HTTP Methods DELETE GET PATCH GET Response Body Map boundingbox BoundingBox The bounding box of the geo map Small, createdby User The creator of the map Small, createddate Date The date when this map was created Small, geodata GeoData The geo data of the map Small, id The 18 character user ID Small, label The label of the map Small, name The name of the map Small, namespace The namespace of the map Small, projection ConnectEclairMap Projection Enum The projection used by the map (AlbersUSA, Equirectangular, or Mercator) Small, url The url to the map representation Small, PATCH Request Parameters Parameter Name geomapobject Object (MapInput) List of all relevant information about the map, i.e. { "label": "My Map" }. PATCH Request Body MapInput boundingbox MapBoundingBox Input Sets the Map bounding box. 17

22 Datasets List Resource geodata AssetReference Input Sets the parent GeoData. label Sets the Map label. name Sets the Map name projection ConnectEclairMap Projection Enum Sets the Map projection (AlbersUSA, Equirectangular, or Mercator) PATCH Response Body Map boundingbox BoundingBox The bounding box of the geo map Small, createdby User The creator of the map Small, createddate Date The date when this map was created Small, geodata GeoData The geo data of the map Small, id The 18 character user ID Small, label The label of the map Small, name The name of the map Small, namespace The namespace of the map Small, projection ConnectEclairMap Projection Enum The projection used by the map (AlbersUSA, Equirectangular, or Mercator) Small, url The url to the map representation Small, Datasets List Resource Returns a list of Wave Analytics datasets. You can filter the results to include only those datasets that have a current dataset version defined by using the hascurrentonly parameter. You can also request supplemental information about datasets that have a current dataset version defined by using the filtergroup parameter. For example, the following GET request sets these parameters: /wave/datasets?hascurrentonly=true&filtergroup=supplemental 18

23 Datasets List Resource This request filters the list of datasets and adds the following supplemental fields to the output representation: currentcreatedby currentcreateddate currentlastmodifiedby currentlastmodifieddate For more information about the filtergroup parameter, see Specifying Response Sizes in the Chatter REST API Developer Guide. Resource URL /wave/datasets Formats JSON HTTP Methods GET GET Request Parameters Parameter Name folderid ID Filters the results to include only the contents of a specific folder. Can be the requesting user s ID for items in the user s private folder. hascurrentonly Filters the list of datasets to include only those datasets that have a current version. The default is false. page A generated token that indicates the view of datasets to be returned. pagesize Int Number of items to be returned in a single page. Minimum is 1, maximum is 200, and default is 25. q Search terms. Individual terms are separated by spaces. Wild cards aren t supported. sort Enum Sort order of the results. Values are: LastModified Mru: Most recently used (last viewed date) Name The default value is Mru. 19

24 Dataset Resource GET Response Body datasets Dataset Resource on page 21[] List of datasets available to the current user. Small, nextpageurl The URL to retrieve the next page of contents in the collection. Small, totalsize The total count of the elements in the collection, including all pages. Medium, url The URL to retrieve the collection. Small, Example Response Body { } "datasets" : [ "/* Datasets detail omitted for brevity. */" ], "nextpageurl" : "/services/data/v/wave/datasets?page=eyjwywdlu2l6zsi6mjusinnv", "totalsize" : 33, "url" : "/services/data/v/wave/datasets" Dataset Resource Returns the Wave Analytics dataset with the specified ID, deletes a dataset (DELETE), or updates a dataset (PATCH). Resource URL /wave/datasets/<dataset ID> Formats JSON HTTP Methods GET, DELETE, and PATCH PATCH Request Body DatasetInput currentid ID The 18-character ID of the current version of this dataset. description The description of the dataset. 20

25 Dataset Resource folder ID The 18-character ID of the folder that contains the dataset. For example: "folder": { "id":"005xx000001swtwaa0" } To patch the folder, you must have edit access to the current and new folders. label The label of the dataset. name The name of the dataset. Note: Patching of developer names for datasets is not allowed. Dataflows reference datasets by using their developer names, and changing names can lead to broken dataflows. userxmd XmdInput User XMD associated with this dataset. GET and PATCH Response Body Dataset Filter Group and assetsharingurl The URL for opening this asset in the Wave builder. This is a form of deep linking. The server examines the link parameters, which might include url, assetid, orgid, and loginhost, as well as other optional parameters, and translates as necessary to produce the correct result on the target client. For example, it will open the wave dashboard on desktop clients, or mobile if you are on a mobile OS. For example, the shared URL: Small, application/ 005xx000001SvSwAAK? url=sharing& orgid=00dt dpvc& loginhost=https%3a%2f%2f test.my.salesforce.com 21

26 Dataset Resource Filter Group and Might produce the following web Url: explore.apexp#application/ 005xx000001SvSwAAK Or it might produce the following Url on ios: com.salesforce.kona:// application/ 005xx000001SvSwAAK& orgid=00dt dpvc& loginhost=https%3a%2f%2f test.my.salesforce.com createdby Wave User The creator of the dataset. Small, createddate Date The time at which the dataset was created, in ISO8601 date format. Small, currentcreatedby Wave User The creator of the current version of the dataset. Only returned if the filtergroup input parameter is set to Supplemental. Supplemental, currentcreateddate Date The time at which the current version of the dataset was created, in ISO8601 date format. Only returned if the filtergroup input parameter is set to Supplemental. Supplemental, currentid ID The 18-character ID of the current dataset version. Small, currentlastmodifiedby Wave User The user who last updated the current version of the dataset. Only returned if the filtergroup input parameter is set to Supplemental. Supplemental, currentlastmodifieddate Date The last time the current version of the dataset was modified, in ISO8601 date format. Only returned if the filtergroup input parameter is set to Supplemental. Supplemental, currenturl The URL for the current dataset version. Small, description Short description of the asset. Small, 22

27 Dataset Resource Filter Group and folder Asset Reference A reference to the folder in which this dataset is stored. Small, id ID The 18-character ID of the dataset. Small, label The label of the dataset. Small, lastquerieddate Date Date/time when this dataset was last queried. Small, lastaccesseddate Date The last time the dataset was accessed, in ISO8601 date format. Small, lastmodifiedby Wave User The user who last updated the dataset. Small, lastmodifieddate Date The last time the dataset was modified, in ISO8601 date format. Small, name The dataset name. Small, namespace The namespace of the Asset. Small, permissions Permissions The permissions for the current user. Small, type The asset type. For datasets, the value is dataset. Small, url The URL to the resource for the dataset. Small, userxmd Xmd on page 30 Reference to the associated user xmd (if any). Medium, versionsurl The URL for dataset versions. Small, Wave User id ID The 18-character user ID. Small, name The name of the user. Small, profilephotourl The Chatter profile photo of the user. Small, 23

28 Dataset Resource Permissions manage Indicates whether a user can manage access control on an asset. Small, modify Indicates whether a user can modify an asset. Small, view Indicates whether a user can view an asset. Small, AssetReference id The 18 character ID of the asset. Small, label The asset label. Small, name The asset developer name. Small, namespace The namespace that qualifies the asset name Small, url The asset URL. Small, Example Response Body { "createdby" : { "id" : "005D LSoIAM", "name" : "User Name", "profilephotourl" : " }, "createddate" : " T20:27:34.000Z", "currentid" : "0FcD KAA", "currenturl" : "/services/data/v/wave/datasets/0fbd hukaa/versions/0fcd kaa", "folder": { "id":"005xx000001swtwaa0" }, "id" : "0FbD huKAA", "label" : "OppHistory", "lastaccesseddate" : " T18:31:00Z", "lastmodifiedby" : { "id" : "005D LT8IAM", "name" : "Integration User", "profilephotourl" : "" }, 24

29 s List Resource } "lastmodifieddate" : " T20:27:44.000Z", "name" : "OppHistory", "permissions" : { "modify" : true, "view" : true }, "type" : "dataset", "url" : "/services/data/v/wave/datasets/0fbd hukaa" s List Resource Returns a collection of dataset versions for a particular dataset. Resource URL /wave/datasets/<dataset ID>/versions Formats JSON HTTP Methods GET GET Response Body url The URL to retrieve the collection. Small, versions Dataset [] The collection of dataset versions for a particular dataset. Small, Example Response Body { "url" : "/services/data/v/wave/datasets/0fb ftcai/versions", "versions" : [ { "createdby" : { "id" : " DhrEAAS", "name" : "Integration User", "profilephotourl" : " }, "createddate" : " T23:19:33.000Z", "dataset" : { "id" : "0Fb FtCAI", "url" : "/services/data/v/wave/datasets/0fb ftcai" }, "files" : [ ], 25

30 Resource "id" : "0Fc VOCAY", "lastmodifiedby" : { "id" : " DhrEAAS", "name" : "Integration User", "profilephotourl" : " }, "lastmodifieddate" : " T23:19:49.000Z", "permissions" : { "modify" : true, "view" : true }, "type" : "datasetversion", "url" : "/services/data/v/wave/datasets/0fb ftcai/versions/0fc vocay", "xmdsurl" : "/services/data/v/wave/datasets/0fb ftcai/versions/0fc vocay/xmds" } } ] Resource Returns a Wave Analytics dataset version (GET), or updates the predicate (PATCH). Resource URL /wave/datasets/<dataset ID>/versions/<version ID> Formats JSON HTTP Methods GET and PATCH GET and PATCH Response Body createdby Wave User The creator of the dataset. Small, createddate Date The time at which the dataset was created, in ISO8601 date format. Small, dataset Dataset Reference A reference to the dataset. Small, files WaveFileMetadata [] List of information about the data files that make up the dataset version. Medium, id ID The 18-character dataset ID. Small, lastmodifiedby Wave User The user who last updated the dataset. Small, 26

31 Resource lastmodifieddate Date The last time the dataset was modified, in ISO8601 date format. Small, permissions Permissions The permissions for the current user. Small, predicate The row-level security predicate. Only returned if the predicate is set in the input request. Small, predicate Double The version of the row-level security predicate. Only returned if the predicate is set in the input request. Small, sharingenabled Whether Sharing rules are enabled for this dataset version. Small, type The asset type. For dataset versions, the value is datasetversion. Small, filesurl The URL of the files resource for this dataset version. Small, xmdmain XMD The extended metadata (XMD) for this dataset version. Medium, xmdsurl The URL of the XMD collection resource for this dataset version. Small, Dataset Reference id ID The 18-character ID of the dataset. Small, url The URL of the dataset. Small, Example Response Body { "createdby" : { "id" : "005D VHeYIAW", "name" : "Integration User", "profilephotourl" : " }, "createddate" : " T20:17:54.000Z", "dataset" : { "id" : "0FbD CoMKAU", "url" : "/services/data/v/wave/datasets/0fbd comkau" }, 27

32 File Resource "files" : [ ], "id" : "0FcD DRyKAM", "lastmodifiedby" : { "id" : "005D VHeYIAW", "name" : "Integration User", "profilephotourl" : " }, "lastmodifieddate" : " T20:18:14.000Z", "permissions" : { "modify" : true, "view" : true }, "type" : "datasetversion", "url" : "/services/data/v/wave/datasets/0fbd comkau/versions/0fcd drykam" } PATCH Request Body iscomplete Indicates whether the Dataset is complete predicate The row level security predicate to be applied to this Dataset. sharingenabled Whether sharing rules should be on the dataset version totalrows The total number of rows that make up the Dataset Example Request Body { } "predicate" : "<predicate value>" PATCH Response Body Dataset File Resource Provides access to the binary content of the dataset file. Note: This resource is accessible only to administrators with the Manage Wave Analytics user permission. Resource URL /wave/datasets/<dataset ID>/versions/<version ID>/files/<file ID> 28

33 XMD List Resource Formats JSON HTTP Methods GET GET Response Body Returns the binary content of the dataset file. XMD List Resource Returns a list of XMD resources for a version of a dataset. Resource URL /wave/datasets/<dataset ID>/versions/<version ID>/xmds Formats JSON HTTP Methods GET GET Response Body url The location of the XMD collection. Small, xmds XMD Metadata[] The list of XMD resources. Small, XMD Metadata type The type of XMD. Values are: Small, main system user url The location of this XMD. Small, 29

34 XMD Resource Example Response Body { "url" : "/services/data/v/wave/datasets/0fb ftcai/versions/0fc vocay/xmds", "xmds" : [ { "type" : "main", "url" : "/services/data/v/wave/datasets/0fb ftcai/versions/0fc vocay/xmds/main" }, { "type" : "user", "url" : "/services/data/v/wave/datasets/0fb ftcai/versions/0fc vocay/xmds/user" }, { "type" : "system", "url" : "/services/data/v/wave/datasets/0fb ftcai/versions/0fc vocay/xmds/system" } } ] XMD Resource Returns the extended metadata (XMD) for a version of a dataset (GET) and replaces the user XMD file (PUT). Resource URL /wave/datasets/<dataset ID>/versions/<version ID>/xmds/main /wave/datasets/<dataset ID>/versions/<version ID>/xmds/system /wave/datasets/<dataset ID>/versions/<version ID>/xmds/user Formats JSON HTTP Methods GET and PUT (on /wave/datasets/<dataset ID>/versions/<version ID>/xmds/user only) GET Response Body Filter Group and createdby Wave User The creator of the XMD. Small, createddate Date The time at which the XMD was created, in ISO8601 date format. Small, 30

35 XMD Resource Filter Group and dates XMD Date[] A list of dates with formatting information. Small, deriveddimensions XMD Dimension[] A list of derived dimensions with formatting information. Small, derivedmeasures XMD Measure[] List of derived measures with formatting information. Small, dimensions XMD Dimension[] List of dimensions with formatting information. Small, errormessage Message if there was error copying forward the current version's user XMD to the newly created version. Small, language The language in which this XMD is localized. Values are: Small, bg: Bulgarian zh_cn: Chinese Simplified zh_tw: Chinese Traditional hr: Croatian cs: Czech da: Danish nl_nl: Dutch en: English en_gb: English (United Kingdom) fi: Finnish fr: French de: German el: Greek hu: Hungarian in: Indonesian it: Italian ja: Japanese ko: Korean no: Norwegian pl: Polish pt_pt: Portuguese (Portugal) pt_br: Portuguese (Brazil) ro: Romanian 31

36 XMD Resource Filter Group and ru: Russian sk: Slovak sl: Slovenian es: Spanish es_mx: Spanish (Mexico) sv: Swedish th: Thai tr: Turkish uk: Ukrainian vi: Vietnamese lastmodifiedby Wave User The user who last updated the XMD. Small, lastmodifieddate Date The last time the XMD was modified, in ISO8601 date format. Small, measures XMD Measure[] List of measures with formatting information. Small, organizations XMD Organization[] List of organizations for multi-organization support. Small, showdetailsdefault Fields [] Ordered list of dimensions and measures. The list defines the default order in which to show the dimensions and measures in the user interface. Small, type The type of XMD. Values are: Small, main system user url The location where this XMD is stored. Small, XMD Date Filter Group and alias Alias of the Date column. Small, fields XMD Date Field Formatting information for the date fields. Small, 32

37 XMD Resource Filter Group and firstdayofweek What the first day of the week is. Small, fiscalmonthoffset Offset number of months for the fiscal year in relation to the calendar year. Small, fullyqualifiedname Fully qualified name of the date. Small, label Label of the Date column. Small, XMD Date Field day The day field. Small, epochday The epoch day field. Small, epochsecond The epoch second field. Small, fiscalmonth The fiscal month field. Small, fiscal Quarter The fiscal quarter field. Small, fiscalweek The fiscal week field. Small, fiscalyear The fiscal year field. Small, fullfield The full-field field. Small, hour The hour field. Small, minute The minute field. Small, month The month field. Small, quarter The quarter field. Small, second The second field Small, week The week field. Small, year The year field. Small, 33

38 XMD Resource XMD Dimension Filter Group and field The field name of the dimension (used in queries). Small, label The label for the dimension. Small, linktemplate The template for formatting a link. Small, linktemplateenabled Indicates whether the dimension has link templates enabled. Small, linktooltip The tooltip to be displayed for links. Small, members XMD Dimension Member[] The member overrides for a dimension. Small, recorddisplayfields [] Ordered list of dimensions and measures. The list defines the default order to in which to display the dimensions and measures in the user interface. Small, recordidfield The record ID for this dimension. Small, recordorganizationid Field The record organization ID for this dimension. Small, salesforceactions XMD Dimension Salesforce Action[] Salesforce actions linked to this dimension. Small, salesforceactions Enabled Indicates whether the dimension has Salesforce actions enabled. Small, showinexplorer Indicates whether the dimension is displayed in the explorer. Small, XMD Dimension Member color The color for the member. Small, label The label for the member. Small, member The member value. Small, 34

39 XMD Resource XMD Dimension Salesforce Action enabled Indicates whether the action is enabled for a specific dimension. Small, name The name of the action. Small, XMD Measure Filter Group and field The field name of the measure (used in queries). Small, format XMD Measure Format The format details for the measure. Small, label The label for the measure. Small, showinexplorer Indicates whether the measure is displayed in the explorer. Small, XMD Measure Format Filter Group and customformat The original (XMD 1.1) format array as a single string. Small, unitmultiplier Double The multiplier for the unit. Small, XMD Organization id The ID of the organization. Small, instanceurl The instance URL for the organization. Small, label The label for the organization. Small, 35

40 XMD Resource PUT Request Body dataset XmdDatasetInput Locale-specific information about the Dataset represented by this XMD. dates XmdDateInput [] List of dates with formatting information. derived Dimensions XmdDerived DimensionInput [] List of derived dimensions with formatting information. derived Measures XmdDerived MeasureInput [] List of derived measures with formatting information. dimensions XmdDimension Input [] List of dimensions with formatting information. measures XmdMeasureInput [] List of measures with formatting information. organizations XmdOrganization Input [] List of organizations for multi-organization support. showdetails DefaultFields [] Ordered list of Dimensions and Measures. Represents the default order to show them in the UI. XmdDatasetInput connector Connector source for the dataset. description of the dataset. fully QualifiedName Fully qualified name of the dataset version. origin Origin representing where this dataset version comes from. 36

41 XMD Resource XmdDateInput alias Alias of the Date column. fields XmdDateFieldsInput Formatting information for the date fields. firstdayof Week What the first day of the week is. fiscalmonth Offset Offset number of months for the fiscal year in relation to the calendar year. fullyqualifiedname Fully qualified name of the date. label Label of the Date column. XmdDateFieldsInput day day field. epochday epochday field. epochsecond epochsecond field. fiscalmonth fiscalmonth field. fiscalquarter fiscalquarter field. fiscalweek fiscalweek field. fiscalyear fiscalyear field. fullfield fullfield field. hour hour field. minute minute field. month month field. quarter quarter field. second second field. week week field. year year field. 37

42 XMD Resource XmdDerivedDimensionInput members XmdDerived DimensionMember Input [] Member overrides for a Derived Dimension. salesforce Actions XmdDerived Dimension SalesforceAction Input [] Salesforce Actions linked to this Derived Dimension. XmdDerivedDimensionMemberInput color Color for the member. label Label for the member. member Member value. XmdDerivedDimensionSalesforceActionInput enabled Whether the Action is enabled. name Name of the action. XmdDerivedMeasureInput format XmdDerived MeasureFormat Input Format details for the Derived Measure. field Field name of the Measure (used in queries). label Label for the Measure. 38

43 XMD Resource showin Explorer Whether the Measure should be shown in the Explorer. XmdDerivedMeasureFormatInput customformat Displays the original XMD 1.1 format array as a. unit Multiplier Double Multiplier for the unit. XmdDimensionInput field Field name of the Dimension (used in queries). label Label for the Dimension. linktemplate Template for formatting a Link. linktemplateenabled Whether the Dimension has link templates enabled. linktooltip Tooltip to be displayed for links. members XmdDimension MemberInput [] Member overrides for a Dimension. recorddisplayfields [] Ordered list of Dimensions and Measures. Represents the default order to show them in the UI. recordidfield Record Id for this dimension. recordorganizationidfield Record Organization Id for this dimension. salesforce Actions XmdDimension SalesforceAction Input [] Salesforce Actions linked to this Dimension. salesforceactionsenabled Whether the Dimension has salesforce actions enabled. 39

44 XMD Resource showinexplorer Whether the Dimension should be shown in the Explorer. XmdDimensionMemberInput color Color for the member. label Label for the member. member Member value. XmdDimensionSalesforceActionInput enabled Whether the Action is enabled. name Name of the action. XmdDimensionInput field Field name of the Dimension (used in queries). label Label for the Dimension. linktemplate Template for formatting a Link. linktemplate Enabled Whether the Dimension has link templates enabled. linktooltip Tooltip to be displayed for links. members XmdDimension MemberInput [] Member overrides for a Dimension. recorddisplay Fields [] Ordered list of Dimensions and Measures. Represents the default order to show them in the UI. recordidfield Record Id for this dimension. 40

45 XMD Resource record Organization IdField Record Organization Id for this dimension. salesforce Actions XmdDimension SalesforceAction Input [] Salesforce Actions linked to this Dimension. salesforce Actions Enabled Whether the Dimension has Salesforce actions enabled. showin Explorer Whether the Dimension should be shown in the Explorer. XmdMeasureInput format XmdMeasureFormat Input Format details for the Measure. field Field name of the Measure (used in queries). label Label for the Measure. showin Explorer Whether the Measure should be shown in the Explorer. XmdMeasureFormatInput customformat Displays the original XMD 1.1 format array as a. unit Multiplier Double Multiplier for the unit. 41

46 Lenses List Resource XmdOrganizationInput id ID ID of the organization. instanceurl Instance Url for the organization. label Label for the organization. Lenses List Resource Returns a list of Wave Analytics lenses (GET), or creates a lens (POST). Resource URL /wave/lenses Formats JSON HTTP Methods GET and POST GET Request Parameters Parameter Name folderid ID Filters the results to include only the contents of a specific folder. Can be the requesting user s ID for items in the user s private folder. page A generated token that indicates the view of the lenses to be returned. pagesize Int Number of items to be returned in a single page. Minimum is 1, maximum is 200, and default is 25. q Search terms. Individual terms are separated by spaces. Wild cards aren t supported. For example, if you have lenses with the following names: Opportunities_Created_2010 Opportunities_Created_