QPR ProcessAnalyzer API: Difference between revisions

From QPR ProcessAnalyzer Wiki
Jump to navigation Jump to search
 
(77 intermediate revisions by the same user not shown)
Line 1: Line 1:
QPR ProcessAnalyzer API's can be used to automate operations in process mining or create integration with other applications. QPR ProcessAnalyzer has two API:
QPR ProcessAnalyzer API can be used to build integrations with other applications and automate operations in the process mining system.
* '''Web API''': REST-based API used by the web UI.
* '''WCF API''': Older API used by the Excel Client and ScriptLauncher.


Prefer the Web API, because WCF API is a legacy API that will be removed in future.
QPR ProcessAnalyzer API is a JSON based API following the REST design principles. All methods (except the [[Web_API:_Token|token]] and [[Web_API:_Serverinfo|serverinfo]]) require a prior login to establish a session. The session is initialized with the [[Web_API:_Token|token]] call with username and password, and the access token is returned as a response for a successful login. The methods requiring prior authenticated session, need to have a HTTP request header ''Authorization'' with value ''Bearer <access token>'' to identify the session.


== Web API ==
Url for calling the API has the following form (replace the server hostname with a correct one):
The Web API uses JSON and it's based on the REST design principles. All operations require a login which is done with the ''Token'' operation with username and password.
 
Url has the following form:
<pre>
<pre>
http(s)://customer.onqpr.com/qprpa/api/operationName
https://customer.onqpr.com/qprpa/api/<methodName>
</pre>
</pre>


Following operations is available:
Following methods are available:
* [[Web_API:_Token|Token]]: Login user using username and password, and get a session token as a response.
{| class="wikitable"
* [[Web_API:_Signout|Sign out]]: Logs out a session.
!'''Method'''
* [[Web_API:_Analysis|Analysis]]: Run query in the server and returns results as a response.
! '''Description'''
* [[Web_API:_Cancel|Cancel]]: Cancels currently running operation.
|-
* [[Web_API:_Filters|Filters]]: Get all filters in system or filters in a model.
||[[Web_API:_Token|token]]
||Login user using username and password and get a session token as a response.
|-
||[[Web_API:_Signout|api/signout]]
||Logs out a user session.
|-
||[[Web_API:_Expression|api/expression]]
||Runs an expression.
|-
||[[Web_API:_Expression/query|api/expression/query]]
||Runs query written using the expression language and returns result data as response.
|-
||[[Web_API:_Filters|api/filters]]
||Get filters for all models or filters for a single model.
|-
||[[Web_API:_Serverinfo|api/serverinfo]]
||Returns common system information needed by UI, such as the default UI language and in whether SSO has been configured.
|-
||[[Web_API:_Importfile|api/importfile]]
||Import data into datatable from .csv, .xes or .pacm file.
|-
||[[Web_API:_Usersettings|api/usersettings]]
||Save user specific settings to the server.
|-
||[[Web_API:_Operations/terminate|api/operations/terminate]]
||Stops the defined tasks (by the task id) to save computing resources.
|-
||[[Web_API:_Cancel|api/analysis/cancel]]
||Stops currently running tasks (by the task identifier) to save computing resources.
|-
||[[Web_API:_saml2/acs|api/saml2/acs]]
||Identity provider (IdP) will send the SAML 2.0 assertion to this endpoint, which responses with 302 to redirect to QPR ProcessAnalyzer UI.
|-
||[[Web_API:_saml2|api/saml2]]
||Returns the SAML 2.0 service provider (SP) metadata, if SAML 2.0 authentication has been configured.
|}


== WCF API ==
In addition, there are methods for
All WCF API operations only accept HTTP POST method (HTTP GET is not allowed). WCF API can be used with ''wsHttp'' (SOAP) and ''webHttp'' endpoints.
* [[Web API for Workspace Elements|moving and deleting workspace elements]]
* [[Web_API_for_Projects|projects]]
* [[Web_API_for_Dashboards|dashboards]]
* [[Web_API_for_Models|models]]
* [[Web_API_for_Datatables|datatables]]
* [[Web_API_for_Scripts|scripts]]
* [[Web_API_for_User_Management|users, groups and roles]]


The following methods are available in the WCF API:
== Examples ==
* [[QPR ProcessAnalyzer API: Authenticate|Authenticate]]: Tries to authenticate given user with given password and authentication parameters.
Following function written in Python starts a script in QPR ProcessAnalyzer by calling the REST API. The function does following: (1) login to QPR ProcessAnalyzer, (2) start the script, and (3) log out. The call just starts the script without waiting for it to complete (asynchronous behavior).
* [[QPR ProcessAnalyzer API: CancelQueryOperation|CancelQueryOperation]]: Cancels running operation using query identifier.
* [[QPR ProcessAnalyzer API: DeleteModel|DeleteModel]]: Deletes a model.
* [[QPR ProcessAnalyzer API: DeleteProject|DeleteProject]]: Deletes a project.
* [[QPR ProcessAnalyzer API: GetAnalysis|GetAnalysis]]: Calculates and returns QPR ProcessAnalyzer analysis.
* [[QPR ProcessAnalyzer API: GetAnalysisImageAsByteArray|GetAnalysisImageAsByteArray]]: Get [[Flowchart_Analysis|Flowchart Analysis]] as image.
* [[QPR ProcessAnalyzer API: GetModel|GetModel]]: Can be used to query QPR ProcessAnalyzer model data.
* [[QPR ProcessAnalyzer API: GetModels|GetModels]]: Can be used to query QPR ProcessAnalyzer model related information.
* [[QPR ProcessAnalyzer API: GetModelAsStream|GetModelAsStream]]: Exports a model or a filtered data as a .pacm file.
* [[QPR ProcessAnalyzer API: GetStream|GetStream]] can be used to query contents of a stream bound to the given session identified by given stream id.
* [[QPR ProcessAnalyzer API: GetUsers|GetUsers]]: can be used to get user related information.
* [[QPR ProcessAnalyzer API: ImportModelFromStream|ImportModelFromStream]]: Import data to QPR ProcessAnalyzer.
* [[QPR ProcessAnalyzer API: LogOff|LogOff]]: Logs off the user session.
* [[QPR ProcessAnalyzer API: QueryObjectProperties|QueryObjectProperties]] returns all the listed properties queried for all the listed objects identified by unique identifiers.
* [[QPR ProcessAnalyzer API: ResetModelCache|ResetModelCache]]: Can be used to clear all cached model information of the given model.
* [[QPR ProcessAnalyzer API: RunScript|RunScript]] can be used to execute given PA script using given parameters.
* [[QPR ProcessAnalyzer API: SetModel|SetModel]]: Can be used to set model related information.
* [[QPR ProcessAnalyzer API: SetUser|SetUser]]: Can be used to set user information.
* [[QPR ProcessAnalyzer API: ValidateModel|ValidateModel]] can be used to perform all the pending tasks stored in the work queue of the given model.
* [[QPR ProcessAnalyzer API: GetUserPermissions|GetUserPermissions]] can be used to query permissions given user has for a set of objects.
* [[QPR ProcessAnalyzer API: ModifyUserRelations|ModifyUserRelations]] can be used to modify permissions given user.
* [[QPR ProcessAnalyzer API: GetUserRoles|GetUserRoles]] can be used to get available user roles.


== WCF API Usage Examples ==
<syntaxhighlight lang="python" line>
=== JavaScript Examples ===
def startQprProcessAnalyzerScript(serverUrl: str, username: str, password: str, scriptId: int):
<pre>
  loginData = {
//login               
      "grant_type": "password",
$.ajax({
      "username": username,
  "method": "POST",
      "password": password
  "url": "http://localhost/qprpa/Mainservice.svc/webHttp/Authenticate",
  }
  "dataType": "json", "contentType": "application/json; charset=utf-8",
  loginResponse = requests.post(
  "data": JSON.stringify({
    url = serverUrl + "/token",
     'logOnName': '<username>',
    data = loginData
    'password': '<password>',
  )
    'parameters': ''
  loginResponse.raise_for_status()
   })
  sessionToken = loginResponse.json().get("access_token")
});                     
 
</pre>
  startScriptResponse = requests.post(
    url = serverUrl + "/api/scripts/run/" + str(scriptId),
    headers = {
      "Authorization": "Bearer " + sessionToken,
      "Content-type": "application/json"
     }
   )
  startScriptResponse.raise_for_status()


<pre>
  logOutResponse = requests.post(
//create user
      url = serverUrl + "/api/signout",
$.ajax({
      headers = {
  "method": "POST",
        "Authorization": "Bearer " + sessionToken,
  "url": "http://localhost/qprpa/Mainservice.svc/webHttp/SetUser",
        "Content-type": "application/json"
  "dataType": "json", "contentType": "application/json; charset=utf-8",
      }
  "data": JSON.stringify({
     )
    "sessionId": sessionId,
   logOutResponse.raise_for_status()
    "user": {"Name": "user", "FullName": "first last" },
</syntaxhighlight>
     "parameters": [{"Key": "Password", "Value": "demo"}]
   })
});
</pre>


<pre>
The function can be called as follows:
//add user to group, value 8:12:0 is user:group:member type
<syntaxhighlight lang="python" line>
$.ajax({
startQprProcessAnalyzerScript(
   "method": "POST",
   serverUrl = "https://server.onqpr.com/qprpa",
  "url": "http://localhost/qprpa/Mainservice.svc/webHttp/ModifyUserRelations",
   username = "qpr",
   "dataType": "json", "contentType": "application/json; charset=utf-8",
   password = "demo",
   "data": JSON.stringify({
   scriptId = 1
    "sessionId": sessionId,
)
    "parameters": [{"Key": "AddGroups", "Value": "8:12:0"}]
</syntaxhighlight>
   })
The script id can be found in the scripts list in the Workspace.
});
</pre>


<pre>
__NOTOC__
//log off
$.ajax({
  "method": "POST",
  "url": "http://localhost/qprpa/Mainservice.svc/webHttp/LogOff",
  "dataType": "json", "contentType": "application/json; charset=utf-8",
  "data": JSON.stringify({
    "sessionId": sessionId
  })
});
</pre>
 
=== PowerShell Examples ===
==== [[Move Data from QPR ProcessAnalyzer to Database using PowerShell]] ====
==== List Users ====
<pre>
$paService=New-WebServiceProxy –Uri "http://localhost/qprpa/MainService.svc"
$connection=$paService.Authenticate("username", "password", @())
$token=$connection.GetValue(0).Value
 
$param=@()
$users=$paService.GetUsers($token, $null, $param)
$users
$paService | get-member | ? {$_.definition -match "GetAnalysis"}
</pre>
 
==== Update Model Configuration ====
<pre>
$paService=New-WebServiceProxy –Uri "http://localhost/qprpa/MainService.svc"
$connection=$paService.Authenticate("username", "password", @())
$token=$connection.GetValue(0).Value
$param=@()
$modelId=@(2)
$model=$paService.GetModels($token,$modelId, $param)


$model[0]
[[Category: QPR ProcessAnalyzer]]
$model[0].ConfigurationJson = "{}"
 
$paService.SetModel($token,$model[0], $param)
</pre>
 
==== Get Flowchart Image ====
<pre>
$paService=New-WebServiceProxy –Uri "http://localhost/qprpa/MainService.svc" -Namespace "WebServiceProxy" -Class "PaService"
$connection=$paService.Authenticate("username", "password", @())
$token=$connection.GetValue(0).Value
 
$ids = new-object WebServiceProxy.ModelViewId
$ids.ViewId = 13
$ids.ViewIdSpecified = 1
 
$analysisType = 0
$processAnalysisType = 4
$minTransitionPercentage = 0.0
 
$png=  $paService.GetAnalysisImageAsByteArray($token, $ids,  $analysisType,1,  $processAnalysisType,1 , $minTransitionPercentage,1)
[IO.File]::WriteAllBytes('c:\tmp\image.png', $png)
</pre>
 
__NOTOC__

Latest revision as of 20:06, 14 December 2023

QPR ProcessAnalyzer API can be used to build integrations with other applications and automate operations in the process mining system.

QPR ProcessAnalyzer API is a JSON based API following the REST design principles. All methods (except the token and serverinfo) require a prior login to establish a session. The session is initialized with the token call with username and password, and the access token is returned as a response for a successful login. The methods requiring prior authenticated session, need to have a HTTP request header Authorization with value Bearer <access token> to identify the session.

Url for calling the API has the following form (replace the server hostname with a correct one): 

https://customer.onqpr.com/qprpa/api/<methodName>

Following methods are available:

Method Description
token Login user using username and password and get a session token as a response.
api/signout Logs out a user session.
api/expression Runs an expression.
api/expression/query Runs query written using the expression language and returns result data as response.
api/filters Get filters for all models or filters for a single model.
api/serverinfo Returns common system information needed by UI, such as the default UI language and in whether SSO has been configured.
api/importfile Import data into datatable from .csv, .xes or .pacm file.
api/usersettings Save user specific settings to the server.
api/operations/terminate Stops the defined tasks (by the task id) to save computing resources.
api/analysis/cancel Stops currently running tasks (by the task identifier) to save computing resources.
api/saml2/acs Identity provider (IdP) will send the SAML 2.0 assertion to this endpoint, which responses with 302 to redirect to QPR ProcessAnalyzer UI.
api/saml2 Returns the SAML 2.0 service provider (SP) metadata, if SAML 2.0 authentication has been configured.

In addition, there are methods for

Examples

Following function written in Python starts a script in QPR ProcessAnalyzer by calling the REST API. The function does following: (1) login to QPR ProcessAnalyzer, (2) start the script, and (3) log out. The call just starts the script without waiting for it to complete (asynchronous behavior). 

def startQprProcessAnalyzerScript(serverUrl: str, username: str, password: str, scriptId: int):
  loginData = {
      "grant_type": "password",
      "username": username,
      "password": password
  }
  loginResponse = requests.post(
    url = serverUrl + "/token",
    data = loginData
  )
  loginResponse.raise_for_status()
  sessionToken = loginResponse.json().get("access_token")
  
  startScriptResponse = requests.post(
    url = serverUrl + "/api/scripts/run/" + str(scriptId),
    headers = {
      "Authorization": "Bearer " + sessionToken,
      "Content-type": "application/json"
    }
  )
  startScriptResponse.raise_for_status()

  logOutResponse = requests.post(
      url = serverUrl + "/api/signout",
       headers = {
         "Authorization": "Bearer " + sessionToken,
         "Content-type": "application/json"
       }
    )
  logOutResponse.raise_for_status()

The function can be called as follows: 

startQprProcessAnalyzerScript(
  serverUrl = "https://server.onqpr.com/qprpa",
  username = "qpr",
  password = "demo",
  scriptId = 1
)

The script id can be found in the scripts list in the Workspace.

Retrieved from "https://wiki.onqpr.com/pa/index.php?title=QPR_ProcessAnalyzer_API&oldid=23960"