Introduction
This example shows how one can call Spotfire Server Web Services using a curl script. The example is based on the OAuth authentication for Spotfire Server Web Services introduced in version 7.13. The example uses cygwin, bash and curl on Windows. The script should work on Linux with little to no changes. Even if the exact script is not useful, the pattern can be taken and reused. A Python script is also included at the end of the article for doing the same in Python.
The basic steps are:
- Register the API Client - this step is down outside the script
-
Steps in the Script
- Call the OAuth2 token endpoint and retrieve the access token
- Call the web service with the access token
Other Resources
- Spotfire Server Web Services API Overview
- Calling the Spotfire UpdateAnalysisService Web Service
- Spotfire Server Web Services API Examples - Library and User Directory Services
- Spotfire Support Knowledge Base Article: How to Obtain an OAuth Access Token Using Curl
Register the API Client
Register the API client using the config register-api-client command on a Spotfire Server. The register-api-client command is run using the config.bat/sh that is in the Spotfire Server <install directory>/tomcat/bin or <install directory>/tomcat/spotfire-bin for 10.3 and later.
One must pass in the scopes (APIs) that the client needs to access. The scopes define which web services the client can call and request. The scopes are listed in the Spotfire Server Web Services documentation. Here are a few examples of the possible scopes:
- api.soap.update-analysis-service
- api.soap.library-service
- api.soap.user-directory-service
For this example, I used the following register-api-client command to register the client for the update analysis service scope:
config register-api-client --name="TestUpdateAnalysis" -Sapi.soap.update-analysis-service
This returns a client id and client secret and registers a user and scope information in the Spotfire Server database. After running the register-api-client command, a user will show up in Spotfire that matches the --name parameter, e.g. TestUpdateAnalysis in this example. One can assign the "user" to groups as needed.
Note that the registered user for the UpdateAnalysisService needs to have the Spotfire Consumer -> "External updates of analysis files in Spotfire web clients" license or be a member of the Administrator group. In Spotfire 10.3, this can be done by a Spottifre administrator via the Spotfire Web Administration Users & Groups interface or via the Administration Manager in Spotfire Analyst. Other scopes may have other access and license requirements based on what the client program needs to do.
Walkthrough of Script
Call the web service with the scope required and the client_id:client_secret in the authorization header. In this example, the scope is for the update analysis service.
NOTE: If using HTTPS and calling a server with a self-signed certificate, you will need to add the -k
or --insecure
to the curl command to disable certificate verification. Do not turn off certificate verification in other scenarios.
RESULT=`curl -k --data "grant_type=client_credentials&scope=api.soap.update-analysis-service" -u <CLIENT_ID>:<CLIENT_SECRET> -H 'Accept:application/json' http://<SPOTFIRE URL>/spotfire/oauth2/token`
This returns a JSON result that contains the access_token:
{"access_token":"<ACCESS_TOKEN>","token_type":"Bearer","expires_in":"7200"}
This line pulls the access token out:
TOKEN=`echo $RESULT | sed 's/.*access_token":"\([^"]*\).*/\1/'`
One then uses the access token in the bearer authorization header in the call to the web service with the parameters for the web service:
curl -H "Authorization: Bearer $TOKEN" --request POST --url http://<SPOTFIRE URL>/spotfire/api/soap/UpdateAnalysisService \ --data '<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">; <Body> <loadAnalysis xmlns="http://spotfire.tibco.com/ws/2015/08/externalScheduledUpdate.xsd">; \ <updateAnalysis xmlns=""> \ <path>/Demo/Analysis Files/Medical Performance/Medical Performance</path> \ <clientUpdate>manual</clientUpdate> \ <keepAliveMinutes>120</keepAliveMinutes> \ <resourcePool></resourcePool> \ </updateAnalysis></loadAnalysis> \ </Body> \ </Envelope>'
This example is calling the update analysis service which allows one to trigger Web Player Scheduled Updates to load a given analysis file.
Complete Example Script
Here is the complete example script. One will need to replace the tags <CLIENT_ID> and <CLIENT_SECRET> with the values obtained from the register-api-client call and replace the <SPOTFIRE URL> with the machine and port to your Spotfire Server. Other edits to the script may be needed based on your environment, but the pattern should help with the scripting environment that you are using.
############# COMPLETE SCRIPT RESULT=`curl -k --data "grant_type=client_credentials&scope=api.soap.update-analysis-service" -u <CLIENT_ID>:<CLIENT_SECRET> -i -H 'Accept:application/json' http://<SPOTFIRE URL>/spotfire/oauth2/token` TOKEN=`echo $RESULT | sed 's/.*access_token":"\([^"]*\).*/\1/'` curl -H "Authorization: Bearer $TOKEN" --request POST --url http://<SPOTFIRE URL>/spotfire/api/soap/UpdateAnalysisService \ --data '<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">; <Body> <loadAnalysis xmlns="http://spotfire.tibco.com/ws/2015/08/externalScheduledUpdate.xsd">; \ <updateAnalysis xmlns=""> \ <path>/Demo/Analysis Files/Medical Performance/Medical Performance</path> \ <clientUpdate>manual</clientUpdate> \ <keepAliveMinutes>120</keepAliveMinutes> \ <resourcePool></resourcePool> \ </updateAnalysis></loadAnalysis> \ </Body> \ </Envelope>'
Python Example Script
This example is here in case one needs similar functionality using Python.
# Python script for calling Spotfire Server web services - specifically import requests import json from requests.auth import HTTPBasicAuth headers1 = { 'Accept':'application/json' } data1 = {'grant_type':'client_credentials', 'scope':'api.soap.update-analysis-service' } id = '<CLIENT_ID>' secret = '<CLIENT_SECRET>' ## if connecting to a server with a self-signed certificate, add verify=False to the parameter list to requests.post result_json = requests.post('https://<SPOTFIRE_URL>/spotfire/oauth2/token';, auth = HTTPBasicAuth(id,secret), headers=headers1, data=data1) result =result_json.json() headers2 = { 'Authorization': "Bearer " + result["access_token"] } data2 = '<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/"><Body>; \ <loadAnalysis xmlns="http://spotfire.tibco.com/ws/2015/08/externalScheduledUpdate.xsd">; \ <updateAnalysis xmlns=""> \ <path>/Test/test_scheduled</path> \ <clientUpdate>automatic</clientUpdate> \ <keepAliveMinutes>0</keepAliveMinutes> \ <resourcePool></resourcePool> \ </updateAnalysis></loadAnalysis> \ </Body></Envelope>' ## if connecting to a server with a self-signed certificate, add verify=False to the parameter list to requests.post response2 = requests.post('https://<SPOTFIRE_URL>/spotfire/api/soap/UpdateAnalysisService',headers=headers2, data=data2) print(response2)
Recommended Comments
There are no comments to display.