How to call configuration services using Postman
Glossary Item Box
Introduction
To integrate with bpm’online configuration services you need to execute HTTP requests to these services. Requests can be compiled in any programming language: C#, PHP, etc. However, it is recommended to use HTTP request debugging tools, such as Postman or Fiddler for better understanding of general principles for request formatting. This article provides examples of requests to bpm’online configuration services using Postman.
NOTE
An example of a request to bpm’online service using Fiddler is described in the “Executing OData queries using Fiddler” article.
Preliminary settings
This article uses a custom configuration service created as described in the “How to create custom configuration service article. Use the following link to access the package for setting up configuration service to your application. The package setup procedure is covered in the “Installing marketplace applications from a zip archive” article.
Authentication
Before making requests to configuration service, a third party application must be authenticated and receive the corresponding cookies. Bpm’online authentication uses a separate AuthService.svc web service (see “The AuthService.svc authentication service”).
NOTE
Authentication is not needed to access the anonymous services.
To execute a request to AuthService.svc using Postman, do the following (Fig. 1):
Fig. 1. Authentication service request
1. Select the POST HTTP method.
2. Specify the authentication service URL. URL is generated according to the following mask:
http(s)://[bpm'online application address]/ServiceModel/AuthService.svc/Login
Example:
https://009189-studio.bpmonline.com/ServiceModel/AuthService.svc/Login
3. Select the “raw” method of request body generation on the [Body] tab.
4. Specify the request body type (JSON (application/json)).
5. Add the request body – a JSON object with the authentication data (login and password):
{"UserName": "User01", "UserPassword":"User01"}
6. Click the [Send] button to send the request to the service.
ATTENTION
The cookies received in the HTTP response (BPMLOADER, .ASPXAUTH, BPMCSRF and UserName) are to be used in all further requests to bpm'online services that require authentication data. You can view the received cookies on the [Cookies] tab (Fig. 1, 7).
Using the BPMCSRF cookie and BPMCSRF token (see below) is required when protection from CSRF attacks is enabled. For more information, see “Protection from CSRF attacks during integration with bpm'online”. If BPMCSRF token is not specified, the server will return error with code 403.
Protection from CSRF attacks is disabled on bpm’online trial websites. Therefore, there is no need to use both BPMCSRF cookie and token in the request titles.
If the authentication has been successful, the response body will contain a JSON object whose Code property will be set to “0” (Fig. 1, 8). In case of errors, JSON object properties will contain corresponding code and message. For example, if a user specified in step 5 is not added to the application, the authentication service will return an incorrect login and password error (Fig. 2).
Fig. 2. Authentication service request containing invalid user data
Configuration service request
NOTE
The UsrCustomConfigurationService configuration service used in this article (see “Preliminary settings”, “How to create custom configuration service”) can only process HTTP requests via the GET method. Such requests do not have any body. Add the corresponding request body (for example, as described in step 5 of the “Authentication” section), if you need to execute other types of requests.
To generate the UsrCustomConfigurationService configuration service request (Fig. 3):
Fig. 3. Configuration service request
1. Select the GET HTTP method.
2. Specify the configuration service URL. URL is generated according to the following mask:
[Application Address]/0/rest/[Configuration Service Name]/[Custom Service Endpoint]?[Optional Parameters]
Example:
https://009189-studio.bpmonline.com/0/rest/UsrCustomConfigurationService/GetContactIdByName?Name=User01
3. Add the necessary cookies BPMLOADER, .ASPXAUTH, BPMCSRF and UserName) received in the HTTP authentication service response (Fig. 4).
Fig. 4. Adding cookie to a request
ATTENTION
Using the BPMCSRF cookie and BPMCSRF token (see below) is required when protection from CSRF attacks is enabled. Add the “key-value” pair to the request caption. Use “BPMCSRF” as a key and the BPMCSRF cookie value as a value (Fig. 5).
Fig. 5. Adding the BPMCSRF token to the request
4. Add the BPMSESSIONID cookie to all requests except for the first one after the authentication.
ATTENTION
User session will only be created when executing the first configuration service request. The BPMSESSIONID cookie will be returned in the HTTP response (see the [Cookies] tab of the HTTP response fig. 3, 4). Therefore, there is no need to add the BPMSESSIONID cookie to the title of the first request (Fig. 6, 4).
If you do not add the BPMSESSIONID cookie to each subsequent request, each new request will create a new user session. Significant frequency of requests (several or more requests per minute) will increase the RAM consumption which will decrease the performance.
5. Click the [Send] button to send the request to the service.
If the contact specified in the Name parameter is not detected in bpm’online, the “GetContactIdByNameResult” property of the JSON object that was returned in the HTTP response will contain the “” value (fig. 3, 4). If the contact exists, the service will return its identifier (fig. 6).
Fig. 6. Request result
