Wall APIs

Highlights of Wall APIs

  • Provides a method to programmatically get wallUids 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.

Table of Contents:

Get All Walls Owned By an Organization
Send To Wall
Unsend From Wall
Permissions


API Examples

Get All Walls Owned By an Organization

Authenticated User must have the Can List Organization Walls permission group to get all Walls in an organization. The query parameter 'order_by' supports fields 'name' and 'location'. You can define multiple 'order_by' and 'order_direction' values. Example: '[ASC, DESC]'. The filter parameter 'filter_by' supports fields 'name', 'location'. Only one filter parameter may be provided at a time, any extras will be ignored. Example: 'filter_by=name:testwall'.
Endpoint /v2/organizations/<organization_uid>/walls                                                      
Method GET

Request

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

    token = 'SET_YOUR_TOKEN_HERE'
    portal = 'https://api.apps.us.bluescape.com'
    organization_uid = 'SET_ORGANIZATION_UID_HERE'


    if __name__ == "__main__":

        API_endpoint = '/v2/organizations/' + organization_uid + '/walls'

        data_load = {                  # Example showing how to use the filter_by field
            'filter_by=name' : 'NAME_TO_FILTER_BY' 
        }

        the_request = requests.get(
                portal + API_endpoint,
                headers={"Authorization": "Bearer " + token,
                            "Content-Type": "application/json"
                        },
                params = 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)    

        # From here you will need to parse your response to get the UID of the desired wall.
    // 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 portal = 'https://api.apps.us.bluescape.com';
    const api_version = 'v2';
    const api_endpoint = '/organizations/' + workspace_uid + '/walls';

        const data_load = {
        'filter_by=name' : 'NAME_TO_FILTER_BY' 
        }

    request_values = {
        method: 'GET',
        url: portal + '/' + api_version + api_endpoint,
        headers : {
            'Authorization': "Bearer " + token,
            'Content-Type' : 'application/json'    
        },
        data: data_load
    };

    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 UID 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 UID ['walls'][N]['uid'] 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': [{'location': None,
        'name': 'Z270-test-tiki2-asset1237',
        'uid': 'JqsR29S2osjPax75szsb'}]}

*Note: You need to save the wall uid that is returned to be able to send and unsend the workspace to a Wall.

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.
Endpoint /v2/workspaces/<workspace_uid>/session/send_to_wall
Method POST
Body wallUID

Request

    # Python Code (python 3.5+)
    import requests
    from requests.exceptions import HTTPError
    
    '''
    Required modules:
        requests 2.22.0
    '''

    token = 'ADD_YOUR_TOKEN_HERE'    
    portal = 'https://api.apps.us.bluescape.com'
    workspace_uid = 'ADD_YOUR_WORKSPACE_UID'  # REMEMBER TO ADD WORKSPACE UID
    API_version = 'v2'
    API_endpoint = '/' + API_version + '/workspaces/' + workspace_uid + '/session/send_to_wall'

    data_load = {
        'wallUid' : 'SET_WALLUID_HERE'
    }

    the_request = requests.put(
            portal + API_endpoint,
            headers={"Authorization": "Bearer " + token,
                        "Content-Type": "application/json"
                    },
            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)     

    // 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 portal = 'https://api.apps.us.bluescape.com';
    const workspace_uid = 'SET_YOUR_WORKSPACE_UID'
    const api_version = 'v2';
    const api_endpoint = '/workspaces/' + workspace_uid + '/session/send_to_wall';
    const wallUid = 'SET_WALL_UID_HERE' // Example: 68734
    
    const data_load = {
        'wallUid': wallUid
    }
    
    request_values = {
        method: 'GET',
        url: portal + '/' + api_version + api_endpoint,
        headers : {
            'Authorization': "Bearer " + token,
            'Content-Type' : 'application/json'    
        },
        data: data_load
      };
    
    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);
        });

Response

        {'wallName': 'hq_wall_client_asset_4',
        'wallUid': '1mgrGsuTr29Qq-9Gjpls'}

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 /v2/workspaces/<workspace_uid>/session/unsend_from_wall
Method POST
Body wallUID

Request

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

    '''
    Required modules:
        requests 2.22.0
    '''

    token = 'ADD_YOUR_TOKEN_HERE'    
    portal = 'https://api.apps.us.bluescape.com'
    workspace_uid = 'ADD_YOUR_WORKSPACE_UID'  # REMEMBER TO ADD WORKSPACE UID
    API_version = 'v2'    
    API_endpoint = '/' + API_version + '/workspaces/' + workspace_uid + '/session/unsend_from_wall'
    
    data_load = {
        'wallUid' : 'SET_WALLUID_HERE' 
    }

    the_request = requests.put(
            portal + API_endpoint,
            headers={"Authorization": "Bearer " + token,
                        "Content-Type": "application/json"
                    },
            json=data_load
        )

    if the_request.status_code != 200:
        # Error found        
        print("Error found:")
        pprint.pprint(the_request)
    else:
        # Successful execution returns Null
        print("Execution successful!")    
    // 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 portal = 'https://api.apps.us.bluescape.com';
    const workspace_uid = 'SET_WORKSPACE_UID_HERE'
    const api_version = 'v2';
    const api_endpoint = '/workspaces/' + workspace_uid + '/session/send_to_wall';
    const wallUid = 'SET_WALL_UID_HERE'

    const data_load = {
        'wallUid': wallUid
    }

    request_values = {
        method: 'GET',
        url: portal + '/' + api_version + api_endpoint,
        headers : {
            'Authorization': "Bearer " + token,
            'Content-Type' : 'application/json'    
        },
        data: data_load
    };

    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);
        });

*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

       none

Permissions

Workspace owners may now extend the ability to Send to Wall to various users in their workspace. 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 permissions to Edit a workspace will inherit this Send to Wall permission.

Send to Wall Unsend From Wall
Owner Always Always
Admin With Edit Permissions Yes if Sender*
User With Edit Permissions Yes if Sender*
Guest No, must be invited No

*Note: A workspace User can only unsend a workspace from a Wall if they were the ones who sent the workspace to the wall in the first place, however a workspace Owner can ALWAYS unsend their workspace from a Wall regardless of who sent it there.

You can verify if your user has the required permissions by following these steps:
  • Log into Bluescape
  • Go to the list of Collaborators for a specific workspace
  • On the header of the list of users, click the question mark icon at the right of "Workspace Role"
  • You will get a popup with the permissions of your Collaborators
  • Verify that you can see the Send to Wall permission

If you have any questions or comments, please contact us at Bluescape support.