Wall APIs Reference Topic

[Tom_Garrett]

Highlights of Wall APIs

• Provides a method to programmatically get wallIds for all Walls within an organization.
• Allows users to Send and Unsend their workspaces to a Wall client programmatically.
• Introduces a new user permission Send to Workspace that is automatically inherited by any role with the Edit permission.

API Examples

Get All Walls Owned By an Organization, v3

Authenticated User must have the Can List Organization Walls permission group to get all Walls in an organization. The query parameter ‘orderBy’ supports the ‘name’ field. You can define multiple ‘orderBy’ values. You can also specify the order in which your name field is displayed through the use of ‘asc’ and ‘desc’. The filter query parameter ‘filterBy’ supports fields ‘name’, ‘archived’. Only one filter parameter may be provided at a time; any extras will be ignored. Example: 'filterBy=name:testwall'.

Note: you must use the x-bluescape-internal:1 flag to use Wall APIs

Endpoint	/v3/organizations/{organizationId}/walls
Method	GET

Request

Node.js

// Node.js Javascript
var axios = require('axios');
/*
How to run:
node this_script_name.js

Requires "axios" module (0.19.0), run:
npm install axios

website: https://github.com/axios/axios
*/
const token = '<SET_TOKEN>';
const api_domain = 'https://api.apps.us.bluescape.com';
const api_version = 'v3';
const organizationId = '<SET_ORGANIZATION_ID>';
const api_endpoint = '/organizations/' + organizationId + '/walls';
//optional filter:
const filter_by = '?filterBy=name eq \'<WALL_NAME>\'';

const request_values = {
    method: 'GET',
    url: api_domain + '/' + api_version + api_endpoint + filter_by,
    headers : {
        'Authorization': "Bearer " + token,
        'x-bluescape-internal': '1'    
    }
};

axios(request_values)
    .then(function (response) {
    if (response.status == 200)
    {
        console.log("Success");
        console.log(response.data);
    }
   })
    .catch (function (error) {
        console.log('Error: ' + error.message);
    });
    // From here you will need to parse the response to get the ID of the desired wall.

Python

# Python Code (python 3.5+)
import requests
from requests.exceptions import HTTPError
import pprint

token = '<SET_TOKEN>'
api_domain = 'https://api.apps.us.bluescape.com'
organizationId = '<SET_ORGANIZATION_ID>'
API_endpoint = '/v3/organizations/' + organizationId + '/walls'
#optional filteryBy query param:
filter_by = '?filterBy=name eq \'<WALL_NAME>\''


if __name__ == "__main__":

    the_request = requests.get(
            api_domain + API_endpoint + filter_by,
            headers={"Authorization": "Bearer " + token,
                        "Content-Type": "application/json",
                        "x-bluescape-internal": "1"
                    }
        )

    if the_request.status_code != 200:
        # Error found        
        print("Error found:")
        pprint.pprint(the_request)
    else:
        json_response = the_request.json()
        pprint.pprint(json_response)   

    # From here you will need to parse your response to get the ID of the desired wall.

Response

If no extra parameters are used, a list of the top 25 results will be returned.

Element	Json	Comments
Wall ID	[‘walls’][N][‘id’]	Where N is the N-th Wall in the list.
Wall Name	[‘walls’][N][‘name’]	Where N is the N-th wall name in the list

Example JSON Output:

{
    "walls": [
        {
            "id": "cf0k2DmIcgk-Rdyd-Skw",
            "name": "org-1-testwall-1",
            "defaultWorkspaceId": null,
            "currentWorkspaceId": null,
            "archived": false,
            "organizationId": "5JIGySFmJpgen2Jnozqx"
        },
        {
            "id": "xOr1oAGHWce6ttS5_Qe_",
            "name": "org-1-testwall-2",
            "defaultWorkspaceId": null,
            "currentWorkspaceId": null,
            "archived": false,
            "organizationId": "5JIGySFmJpgen2Jnozqx"
        }
    ],
    "prev": null,
    "next": null,
    "totalItems": 2
}

Send Workspace to Wall

Send workspace to wall. Requires Send to Wall permission group. You can obtain the wallUid value by using the Wall API described above.

Note: To send a workspace to a Wall, you must use the elementary endpoint rather than the unified API through the API gateway. For example: https://elementary.apps.us.bluescape.com rather than https://api.apps.us.bluescape.com

Endpoint	/api/v3/workspaces/walls/{wall_id}
Method	POST
Body	workspaceUid

Request

Node.js

   // Node.js Javascript
var axios = require('axios');
/*
How to run:
node this_script_name.js

Requires "axios" module (0.19.0), run:
npm install axios

website: https://github.com/axios/axios
*/

const token = 'SET_YOUR_TOKEN_HERE';
const api_domain = 'https://elementary.apps.us.bluescape.com';
const api_version = 'v3';
const workspaceUid = '<THE_WORKSPACE_ID>';
const wall_id = '<THE_WALL_ID>'
const api_endpoint = '/api/' + api_version + '/workspaces/walls/' + wall_id + '/send';

//optional filter:
let data = JSON.stringify({
    "workspaceUid": workspaceUid
  });

let request_values = {
    method: 'POST',
    url: api_domain + api_endpoint,
    headers : {
        'Authorization': "Bearer " + token,
        'Content-Type': 'application/json',
        'x-bluescape-internal': '1'    
    },
    data : data
};

axios(request_values)
    .then(function (response) {
        if (response.status == 200) {
            console.log("Success");
            console.log(response.data);
        }
    })
    .catch(function (error) {
        console.log('Error: ' + error.message);
    });

Python

# Python Code (python 3.5+)
import requests
from requests.exceptions import HTTPError
import pprint


token = '<ADD_YOUR_TOKEN_HERE>'
api_domain = 'https://elementary.apps.us.bluescape.com'
api_version = 'v3'
workspaceUid = '<THE_WORKSPACE_ID>'
wall_id = '<THE_WALL_ID>'
api_endpoint = '/api/' + api_version + '/workspaces/walls/' + wall_id + '/send'

data_load = {
    'workspaceUid': workspaceUid 
}

if __name__ == "__main__":

    the_request = requests.post(
            api_domain + api_endpoint,
            headers={"Authorization": "Bearer " + token,
                        "Content-Type": "application/json",
                        "x-bluescape-internal": "1"
                    },
            json=data_load
        )

    if the_request.status_code != 200:
        # Error found        
        print("Error found:")
        pprint.pprint(the_request)
    else:
        json_response = the_request.json()
        pprint.pprint(json_response)  

Response

{'workspaceUid': 'Sv1JUoiNcFzYhz3stnbt'}

Unsend Workspace From Wall

Unsend workspace from a Wall. A workspace Owner can unsend the workspace from any wall. A workspace user with Editor or Editor+ role can unsend the workspace if they were the sender of the workspace previously.

Endpoint	/api/v3/workspaces/walls/{wall_id}/unsend
Method	POST
Body	workspaceUid

Request

Node.js

// Node.js Javascript
var axios = require('axios');
/*
How to run:
node this_script_name.js

Requires "axios" module (0.19.0), run:
npm install axios

website: https://github.com/axios/axios
*/

token = '<ADD_YOUR_TOKEN_HERE>'
api_domain = 'https://elementary.apps.us.bluescape.com'
api_version = 'v3'
workspaceUid = '<THE_WORKSPACE_ID>'
wall_id = '<THE_WALL_ID>'
api_endpoint = '/api/' + api_version + '/workspaces/walls/' + wall_id + '/unsend'

let data = JSON.stringify({
    "workspaceUid": workspaceUid
  });

let request_values = {
    method: 'POST',
    url: api_domain + api_endpoint,
    headers : {
        'Authorization': "Bearer " + token,
        'Content-Type': 'application/json', 
        'x-bluescape-internal': '1'    
    },
    data : data
};

axios(request_values)
    .then(function (response) {
        if (response.status == 200) {
            console.log("Success");
            console.log(response.data);
        }
    })
    .catch(function (error) {
        console.log('Error: ' + error.message);
    });

Python

# Python Code (python 3.5+)
import requests
from requests.exceptions import HTTPError
import pprint


token = '<ADD_YOUR_TOKEN_HERE>'
api_domain = 'https://elementary.apps.us.bluescape.com'
api_version = 'v3'
workspaceUid = '<THE_WORKSPACE_ID>'
wall_id = '<THE_WALL_ID>'
api_endpoint = '/api/' + api_version + '/workspaces/walls/' + wall_id + '/unsend'

data_load = {
    'workspaceUid': workspaceUid 
}

if __name__ == "__main__":

    the_request = requests.post(
            api_domain + api_endpoint,
            headers={"Authorization": "Bearer " + token,
                        "Content-Type": "application/json",
                        "x-bluescape-internal": "1"
                    },
            json=data_load
        )

    if the_request.status_code != 200:
        # Error found        
        print("Error found:")
        pprint.pprint(the_request)
    else:
        json_response = the_request.json()
        pprint.pprint(json_response)

*Note: The wallUid used as the body for the request is the one that was saved from the returned values from Send to Wall request.

Response

{'workspaceUid': 'Sv1JUoiNcFzYhz3stnbt'}

Permissions

Workspace owners may extend the ability to Send to Wall to various users. Initially, only workspace owners can send and unsend their workspace to a wall. This can be extended to allow different levels of users to perform this action. By default, any user with permission to Edit a workspace will inherit this Send to Wall permission.

Learn more: Workspace Roles

Where to Next?

• Application Registration information
• Bluescape API Guides
• Bluescape API Overview
• Latest Developer topics

Not what you were looking for? Reply below or Search the community and discover more Bluescape.