Wall APIs Reference Topic

Developer
#1

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 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'.

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 portal = 'https://api.apps.us.bluescape.com';
const api_version = 'v3';
const organizationId = '<SET_ORGANIZATION_ID>';
const api_endpoint = '/organizations/' + organizationId + '/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 ID of the desired wall.
Python 
# Python Code (python 3.5+)
import requests
from requests.exceptions import HTTPError
import pprint

token = '<SET_TOKEN>'
portal = 'https://api.apps.us.bluescape.com'
organizationId = '<SET_ORGANIZATION_ID>'


if __name__ == "__main__":

    API_endpoint = '/v3/organizations/' + organizationId + '/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 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
}

Get All Walls Owned By an Organization, v2

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

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 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.
Python 
# 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.

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

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

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

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 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);
    });
Python 
# 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!")

*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

collaborators_permissions_list
collaborators_permissions_list621×769 46 KB

Where to Next?

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

Attachments APIs for v2
API Documentation Landing Page