Blue Prism API PostMan Configuration

User Guide

Document Revision 1.3

 Blue Prism API PostMan Configuration - User Guide
Trademarks and copyright

Trademarks and copyright

The information contained in this document is the proprietary and confidential information of Blue Prism Limited and should not
be disclosed to a third party without the written consent of an authorised Blue Prism representative. No part of this document
may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying without the
written permission of Blue Prism Limited.
© Blue Prism Limited, 2001 – 2021
®Blue Prism is a registered trademark of Blue Prism Limited
All trademarks are hereby acknowledged and are used to the benefit of their respective owners.
Blue Prism is not responsible for the content of external websites referenced by this document.
Blue Prism Limited, 2 Cinnamon Park, Crab Lane, Warrington, WA2 0XP, United Kingdom
Registered in England: Reg. No. 4260035. Tel: +44 870 879 3000. Web: www.blueprism.com

Commercial in Confidence Page ii

 Blue Prism API PostMan Configuration - User Guide
Contents

Table of Contents
Introduction ................................................................................................................................................................ 1
Pre-requisites............................................................................................................................................................. 2
Initial Configuration ................................................................................................................................................... 3
Using Endpoints ........................................................................................................................................................ 7
Troubleshooting ........................................................................................................................................................ 8
Useful References ..................................................................................................................................................... 9
Support ..................................................................................................................................................................... 10

Commercial in Confidence Page iii

 Blue Prism API PostMan Configuration - User Guide
Introduction

Introduction
This asset is created to allow easy consumption of Blue Prism© REST APIs being offered from Blue
Prism v7.0 onwards. The configuration files are designed to be consumed by the PostMan software
(https://www.postman.com), a popular API client that simplifies each step of building an API and
streamlines collaboration. The main audiences of the asset are those who wish to get familiarised with
how various Blue Prism REST API endpoints can be utilised. It may also be used on an ad-hoc basis to
perform some simple tasks programmatically against a Blue Prism instance via the available API
endpoints.
It is the intention of the author to provide regular updates to this asset for all upcoming Blue Prism REST
API releases. Please note that the organisation of the asset may subject to change as the API endpoints
evolve over time.

Commercial in Confidence Page 1 of 10

 Blue Prism API PostMan Configuration - User Guide
Pre-requisites

Pre-requisites
Before you can take advantage of the PostMan configuration files, please make sure the following
conditions are met:
• Blue Prism v7.0 or above is installed with at least one Blue Prism Application Server.
• Blue Prism API is installed for the corresponding version of Blue Prism.
• Blue Prism Hub v4.3 or above is installed.
• Blue Prism Hub has been configured to work with Blue Prism API.
• Blue Prism v7.0 or above has been configured to use Authentication Server option new to v7.0.
• An API service account is created in Blue Prism Hub after configuration of Authentication Server
is completed. As a result of this, you must be able to view the API service account appearing in
Blue Prism v7.0 under System tab > Security > Users. Check here for more details.
• Appropriate permissions have been granted to the API service account for Blue Prism access.
This is often done by associating the API service account with appropriate Blue Prism security
roles.
• PostMan is installed and updated to the latest version.
• The machine where PostMan is installed has access to Blue Prism API web server.
For documentation associated with various Blue Prism REST API endpoints, please refer to the BP API
documentation of your Blue Prism release. For example, the URL to Blue Prism API can be found at
https://bpdocs.blueprism.com/bp-7-0/en-us/api-spec.html. BP Docs home page
(https://bpdocs.blueprism.com/home.htm) is a good entry point to look for the documentation.
For any PostMan specific questions, you may refer to PostMan Learning Center
(https://learning.postman.com/) to find your answer.

Commercial in Confidence Page 2 of 10

 Blue Prism API PostMan Configuration - User Guide
Initial Configuration

Initial Configuration
1. Download the asset and extract all files found in the zip file onto your local machine.
2. Download and install PostMan (https://www.postman.com) if you have not already done so.
3. Open PostMan, import all JSON files into PostMan.
• Choose File > Import...
• Upload JSON file one at a time and click the Import button.
• Repeat the above process until all Json files have been imported.

4. Click Environments tab on the left.

5. Click the version of the Blue Prism API you wish to modify, e.g. 7.0. Please kindly ensure the API
version selected is indeed what you have deployed in your Blue Prism environment.
6. Set an appropriate value for each environment variable under the CURRENT VALUE column.
• BPAPI_BASEURL: the base URL to the Blue Prism API service, e.g. https://bpapi.local/api/v7.

Commercial in Confidence Page 3 of 10

 Blue Prism API PostMan Configuration - User Guide
Initial Configuration

• BPAPI_CLIENTID: this is the API service account Client Id set in Blue Prism Hub.
• BPAPI_CLIENTSECRET: this is the API service account secret key, or client secret that can
be obtained at the time of API service account creation. The secret can be regenerated by
using Blue Prism Hub if needed.
• BPAPI_OAUTH2URL: the URL to obtain the oAuth 2.0 access token from. This URL should
point to Blue Prism Authentication Server service, e.g.
https://authentication.local/connect/token.
7. Click the environment dropdown at the top right corner of PostMan and select the same API
version you have just modified at step 5.

8. Click Collections Tab on the left.

9. Expand the BPAPI folder if not already done so. Select the first-level subfolder with the same
name as the API version you have just selected at step 5.
10. Click Authorization tab at the top section of the right-hand side panel.
11. Click Get New Access Token button at the bottom of the panel.

Commercial in Confidence Page 4 of 10

 Blue Prism API PostMan Configuration - User Guide
Initial Configuration

12. Once you have seen a prompt indicating Authentication complete, click Proceed button to
arrive at the Manage Access Tokens screen.

13. On Manage Access Tokens screen, pick an access token named BP API Token from the left
hand side, ensure the text BP API Token is not in a strikethrough state, as such token has already
expired.

Tips: you can always use Manage Access Tokens screen to remove tokens that have already
expired. To do so, move the mouse cursor onto the BP API Token strikethrough text and click
the bin icon to delete it from PostMan.

Commercial in Confidence Page 5 of 10

 Blue Prism API PostMan Configuration - User Guide
Initial Configuration

14. Click Use Token button at the top right.

15. By this step you should have managed to obtain an oAuth 2.0 JWT access token from Blue Prism
Authentication Server and are in a position to work with any endpoints offered by the
configuration files.

Commercial in Confidence Page 6 of 10

 Blue Prism API PostMan Configuration - User Guide
Using Endpoints

Using Endpoints
Please ensure you have managed to obtain a valid access token before using any endpoints. All Blue
Prism endpoints will only work once there is a valid oAuth 2.0 bearer token found included in the request
header. Note that each access token is only valid for a set period, which means you must obtain a new
access token when the existing token has expired. A good way of telling if you need a new token is to
inspect the returned HTTP status code after you have received response back from any endpoint calls.
An HTTP status code 401 often indicates an invalid/expired bearer token.
To run a specific endpoint, select it from the left-hand side panel where all endpoints are listed. For
certain endpoints, you must make modifications in the following areas:
• Params > Query Params
• Params > Path Variables
• Body

Tips: a green dot to the right of the Params tab indicates there is either query parameter or path
variable available to configure. The same goes for the green dot to the right off the Body tab.

For example, the following screenshot shows an endpoint where a Path Variable must be supplied.

The following screenshot shows an endpoint where the request body in JSON must be provided.

For details of what is necessary for each endpoint, please refer to Blue Prism API Reference document.
For v7.0, such document can be found at https://bpdocs.blueprism.com/bp-7-0/en-us/api-spec.html.

Commercial in Confidence Page 7 of 10

 Blue Prism API PostMan Configuration - User Guide
Troubleshooting

Troubleshooting
I received an error “unable to verify first certificate” from the PostMan console window and would
not be able to proceed.
This error is related to the trust between PostMan and the machine BP API and/or BP Authentication
Server are being hosted. You can try to resolve this by installing the right certificate on PostMan to
establish that trust; alternatively, you may choose to ignore the error by turning off SSL certificate
verification option in the PostMan Settings section (see below).

Commercial in Confidence Page 8 of 10

 Blue Prism API PostMan Configuration - User Guide
Useful References

Useful References
• Blue Prism BP Docs (Blue Prism documentation website):
https://bpdocs.blueprism.com/home.htm
• HTTP Status Code: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
• PostMan: https://www.postman.com/
• PostMan Learning Center: https://learning.postman.com/

Commercial in Confidence Page 9 of 10

 Blue Prism API PostMan Configuration - User Guide
Support

Support
This asset is provided free-of-charge by Blue Prism. Blue Prism does not provide formal support of this
asset. Please direct any questions you have, related to this asset, to the Digital Exchange Community
page:
https://community.blueprism.com/communities/community-home?CommunityKey=1e516cfe-4d1f-4de9-
a9eb-58d15bf38c81

Commercial in Confidence Page 10 of 10