REST Service URLs

Management server settings

The Rest web service must be activated as an independent role in the respective client.

This must also be activated in the master/central client.

General

The “Content-Type” header is decisive for access. Browsers report with “text/html”. Programmatic access, i.e. not browsers, must use “application/json”.
This is particularly important for logging in.

As browsers cannot simply upload a JSON, a web form-based login is performed for access without “application/json”.
The formatting of the response is different. For browsers, the JSON is generated with line breaks and indentations. This means that more spaces are transferred. For programmatic access, the JSON is as compact as possible.

URL structure overview

{baseUrl} is the host name of the server on which the unimate role is active and the port from the unimate configuration. e.g. https://ogitix-mgmt01.ogitix.local:8443

URL	Description	GET	POST	PUT	DELETE
{baseUrl}/config/language	Pre login: Returns the languages supported. Which language is the default one. For example for the login screen. The languages are configured in the unimate Studio.	✔	❌	❌	❌
{baseUrl}/config/colorschema	Pre login: Returns information about the preferred color schema and icon sets. For example for the login screen. The languages are configured in the unimate Studio.	✔	❌	❌	❌
{baseUrl}/login	Login: For browsers an interactive login with HTML. JSON requests receive a JSON at GET that must be filled out and posted back. If you know the JSON and assemble it directly, you can also post it directly.	✔	✔	❌	❌
{baseUrl}/login/domainlist	Provides a list of available domains for login.	✔	❌	❌	❌
{baseUrl}/logout	Logout. Optional. frees up resources more quickly.	✔	❌	❌	❌
{baseUrl}/clients	Minimal information (ID and name, URL) Leads to client URL. See below.	✔	❌	❌	❌
{baseUrl}/system/stats	Provides statistics on the running environments. Expandable.	✔	❌	❌	❌
{baseUrl}/system/client/{id}/stop {baseUrl}/system/client/{id}/start {baseUrl}/system/client/{id}/restart	{id} is “master” or the key of the client. Requires admin or client admin rights in the master client.	✔	❌	❌	❌
{baseUrl}/{client}/schema/datatypes	To retrieve the client's current schema.	✔	❌	❌	❌
{baseUrl}/{client}/schema/userdata	This URL is used to create new resources.	✔	✔	❌	❌
{baseUrl}/{client}/schema/userdata/{id}	URL of a resource. For retrieving, updating and deleting. A resource has a specific data type and could therefore be below the {data-type-id}. As this resource URL will occur relatively frequently and the ID of the data type does not make the URL any more unique, it is omitted.	✔	❌	✔	✔
baseUrl}/{client}/schema/userdata/{id}/attachment	List of all attachments of a resource.	✔	❌	❌	❌
baseUrl}/{client}/schema/userdata/{id}/attachment/{Name}	URL of a resource attachment. For retrieving, updating and deleting. The name must be unique. Multiple attachments, e.g. of different types and the same name, will not work. When uploading, the content type of the file must also be specified. See example.	✔	❌	✔	✔
{baseUrl}/{client}/schema/query	To search for resources with certain properties. Like “Retrieve data” in the workflow. See example 2.	✔	✔	❌	❌
{baseUrl}/{client}/schema/bulk	To retrieve multiple resources. For example, as a result of the search from above.	❌	✔	✔	❌
{baseUrl}/{client}/workflow
{baseUrl}/{client}/workflow/category	List of workflow categories.	✔	❌	❌	❌
{baseUrl}/{client}/workflow/category/{id1} {baseUrl}/{client}/workflow/category/{id1}/{id2} {baseUrl}/{client}/workflow/category/{id1}/.../{idN}	List of workflow category combinations of the n-th level Each workflow is assigned to at least one category.	✔	❌	❌	❌
{baseUrl}/{client}/workflow/category/{id1}/.../{idN}/list	Workflow URLs that match the specified combination.	✔	❌	❌	❌
{baseUrl}/{client}/workflow/category/{id1}/.../{idN}/catalog	A list with the complete content of the workflows for the specified combination. i.e. name, description, image, ....	✔	❌	❌	❌
{baseUrl}/{client}/workflow/definition	List of all current revisions to which the logged-in account has read rights.	✔	❌	❌	❌
{baseUrl}/{client}/workflow/definition/{id}	To retrieve a workflow definition.	✔	❌	❌	❌
{baseUrl}/{client}/workflow/definition/{id}/form	Retrieve the available forms of a workflow definition.	✔	❌	❌	❌
{baseUrl}/{client}/workflow/definition/{id}/form/{form name}	To retrieve the form {form name} of the corresponding workflow and the variables used.	✔	❌	❌	❌
{baseUrl}/{client}/workflow/definition/{id}/form/$start	$start is always the website start form, no matter what it is called in the workflow.	✔	❌	❌	❌
{baseUrl}/{client}/workflow/definition/{id}/form/$external	In the case of a workflow with a “microservice” entry point, $external is a pseudo-form from the variable assignment.	✔	❌	❌	❌
{baseUrl}/{client}/workflow/definition/{id}/execute	A POST to this URL with the variables from {baseUrl}/{client}/workflow/definition/{id}/form/$start starts the workflow.	❌	✔	❌	❌
{baseUrl}/{client}/workflow/definition/query	POST to this URL to search for workflow definitions that match the uploaded search criteria. Currently “name” is the only parameter. Wildcards are allowed.	❌	✔	❌	❌
{baseUrl}/{client}/rbac/role	This URL is used to create a new RBAC role. (Not to be confused with Management Server role)	✔	✔	❌	❌
{baseUrl}/{client}/rbac/role/{id}	To retrieve a role.	✔	❌	❌	❌
{baseUrl}/{client}/rbac/role/{id}/identities	List of assigned identities. POST to add, DELETE to remove transferred identity urls.	✔	✔	❌	✔
{baseUrl}/{client}/rbac/identity	This URL is used to create a new RBAC identity. (Do not confuse with unimate data identity)	✔	✔	❌	❌
{baseUrl}/{client}/rbac/identity/{id}	To retrieve an identity.	✔	❌	❌	✔
{baseUrl}/{client}/rbac/identity/{id}/roles	List of assigned roles. POST to add, DELETE to remove transferred role urls.	✔	✔	❌	✔
{baseUrl}/{client}/task/active/{id}	To retrieve a task. Requires unimate admin role or affiliation.	✔	❌	❌	❌
{baseUrl}/{client}/task/active/{id}/commit/finished {baseUrl}/{client}/task/active/{id}/commit/yes {baseUrl}/{client}/task/active/{id}/commit/abort {baseUrl}/{client}/task/active/{id}/commit/no	POST Urls to complete the task The post body can be empty.	❌	✔	❌	❌
{baseUrl}/{client}/task/active/all	Retrieve all active tasks. Requires unimate admin role.	✔	❌	❌	❌
{baseUrl}/{client}/task/category	List of task categories.	✔	❌	❌	❌
{baseUrl}/{client}/task/active/my/list	Retrieve assigned task urls.	✔	❌	❌	❌
{baseUrl}/{client}/task/active/my/{id1} {baseUrl}/{client}/task/active/my/{id1}/[id2} {baseUrl}/{client}/task/active/my/{id1}/.../{idN}	List of task-category combinations of the nth level Tasks receive the categories of a workflow, i.e. at least one.	✔	❌	❌	❌
{baseUrl}/{client}/task/active/my/{id1}/.../{idN}/list	Task URLs that match the specified combination.	✔	❌	❌	❌
{baseUrl}/{client}/variable/runtime/{id}/values	To retrieve the values of a variable. GET possible for variables without filters or default values. The values can be retrieved in blocks using the URL parameters “index” and “size”. The default value of “size” is 1000. Example POST for uploading variable values that are to be used for the filter. The POST body is a key/value list: { “VariableA": ‘ValueA’, “VariableB": ”ValueB” etc. } Next version: There are four special, optional key/value pairs: $FilterValue, $FilterValueOperator, $FilterDisplayText, $FilterDisplayTextOperator $FilterValueOperator is only effective if $FilterValue is specified and $FilterDisplayTextOperator is only effective if $FilterDisplayText is specified. For the operators, “equals”, “contains”, “startswith” and “endswith” are supported. $FilterValue is case-sensitive and $FilterDisplayText is case-insensitive. The standard operator of $FilterValueOperator is “equals” and that of $FilterDisplayTextOperator is “contains”.	✔	✔	❌	❌
{baseUrl}/{client}/variable/definition/query	POST to this URL to search for variables that match the uploaded search criteria. Currently “name” is the only parameter. Wildcards are allowed.	❌	✔	❌	❌
{baseUrl}/{client}/variable/definition	Retrieve all variables and create a variable	✔	✔	❌	❌
{baseUrl}/{client}/variable/definition/{id}	To retrieve a variable.	✔	❌	✔	✔
{baseUrl}/{client}/variable/definition/catalog {baseUrl}/{client}/variable/definition/catalog?sortby=(key\|name\|displayname)	Display of VariableUrl + name and display name	✔	❌	❌	❌
2025.1
{baseUrl}/login/token/{accesstoken}	Login: Use access token instead of sending username and password. The returned session token must be passed in the “Authorization” header like this: "Bearer " + sessionToken	✔	❌	❌	❌
2025.2
{baseUrl}/config/information	Pre login: Provides a JSON summary of Pendo and license configuration for the current system, suitable for administrative or integration purposes.	✔	❌	❌	❌
{baseUrl}/{client}/whoami	Returns details about the currently authenticated user.	✔	❌	❌	❌
{baseUrl}/{client}/whoami/profileimage	GET: Returns the user's profile image as a JPEG. PUT: Uploads a new profile image for the user. The request body must be a JPEG image (max 5MB). The image gets converted to 128x128px dimensions.	✔	❌	✔	❌
{baseUrl}/{client}/whoami/profileimage/base64	Same as above, but Base64 encoded. The string starts with "data:image/jpeg;base64," followed by the Base64 encoded image.	✔	❌	✔	❌
{baseUrl}/{client}/scim/v2/Groups {baseUrl}/{client}/scim/v2/Groups?startIndex=x&count=y	Read-Only access to BOBs as groups and HR-records/contracts as members. JSON formatting in SCIM standard.	✔	❌	❌	❌
{baseUrl}/{client}/scim/v2/Users {baseUrl}/{client}/scim/v2/Users?startIndex=x&count=y	Read-Only access to HR records as users and BOB-records as members. JSON formatting in SCIM standard.	✔	❌	❌	❌
2025.3
{baseUrl}/{client}/scim/v2/Groups {baseUrl}/{client}/scim/v2/Groups?startIndex=x&count=y	Read-Write access to BOBs as groups and HR-records/contracts as members. JSON formatting in SCIM standard. PUT is full update, PATCH is incremental update.	✔	✔	✔ and PATCH	❌
{baseUrl}/{client}/scim/v2/Users {baseUrl}/{client}/scim/v2/Users?startIndex=x&count=y	Read-Write access to HR records as users and BOB-records as members. JSON formatting in SCIM standard. PUT is full update, PATCH is incremental update.	✔		✔	✔ and PATCH
Future Release
{baseUrl}/{client}/schema/graphql	GraphQL to retrieve multiple resources.	❌	✔	❌	❌

Start a Workflow

For security reasons, the variable values that are transferred at the start are checked. If one of the values does not pass the check, the REST service call fails with 400 (bad request).

Only variables that are listed in the self-service, subservice entry point or microservice are permitted.
Variables that allow a validation rule to be stored are checked against this rule.
Variables for which no validation rule has been or can be stored are checked against the standard rule “No quotation marks”. If the variable is not required, it may be empty.
For the variable types “TextBox”, “TextEditor”, “ComboBox” and “Password”, the values are checked for the set maximum text length. The value “0” stands for unlimited.

If it is not possible to transfer a value to a variable even though it is required, the “Microservice” can be configured with an alternative (TextBox) variable so that this variable is assigned to the target variable later in the service.

NOTE:

Variables of the date type must be passed as a UTC string (.ToString(“u”)), analogous to the FX functions. It is not enough to simply assign the powershell date variable to the variable.

For example: [DateTime]::Now.ToString("u")

Example

Powershell

Example 1 - Login

Authentication is always required. Therefore, this example also serves as the template for the header of all subsequent scripts:

Login

Copy

1
2
3
4
5
6
7
8
9
10
$baseUrl = "https://<hostname>:<port>"Import-Module "Microsoft.PowerShell.Utility"# Für das Security Token Cookie
$session = [Microsoft.PowerShell.Commands.WebRequestSession]::new()

$loginForm = @{}
$loginForm.UserName = "<username>@<domain>"$loginForm.Password = "<password>"# This requests sets the cookie of the session
$userInfo = Invoke-RestMethod -Uri "$baseUrl/login" -Method Post -Body (ConvertTo-Json $loginForm) -WebSession $session

$client = $userInfo.Clients.Where({$_.Name -eq "<Name des Mandanten>"}).link

# For here on each Invoke-RestMethod requires a $session, otherwise the request will be denied.

Example 2 - Get data

RevisionType	CommittedOnly, IncludeWorkingCopy, WorkingCopyOnly, CommittedOrDeletedOnly, IncludeWorkingCopyAndDeleted. Groß-/Kleinschreibung wird nicht beachtet.
DocumentPath	Data type plus optional link. e.g. HumanIdentity.Manager.
Operator	Like, NotLike, Lt, LessThan, Le, LessOrEqual, Gt, GreaterThan, Ge, GreaterOrEqual, Contains, StartsWith, EndsWith, IsEmpty, IsNotEmpty, Eq, Equal, Ne, NotEqual. Groß-/Kleinschreibung wird nicht beachtet.

Query Identities

Copy

1
2
3
4
5
6
7
8
9
10
# Requires login first. See above.
$query = "{RevisionType:`"IncludeWorkingCopy`",DocumentPath:`"HumanIdentity`",Backward:false,Conditions:[{Key:`"HumanIdentity.SamAccountName`",Operator:`"startswith`",Value:`"j`"}]}" # Sucht nach allen Identitäten mit einem SamAccountName der mit j beginnt.

$identityKeys = Invoke-RestMethod -Uri "$client/schema/query" -Method Post -Body $query -WebSession $session

$query = @{}
$query.Recursive = $false # Optional. Default: false
$query.Keys = $identityKeys.ForEach({$_}) # powershell bug

$identities = Invoke-RestMethod -Uri "$client/schema/bulk" -Method Post -Body (ConvertTo-Json $query -Compress)  -WebSession $session

The same example again. This time using the current schema. The search for the correct data type makes it possible to avoid name conflicts.

Query data using data schema

Copy

# Requires login first. See above.
$dataTypes = Invoke-RestMethod -Uri "$client/schema/datatypes" -WebSession $session

$humanIdentity = $dataTypes.Where({$_.Name -eq "HumanIdentity"}).Key # Search by full name or other criteria is possible. The key is more likely to be unique rather than the name.
$query = "{RevisionType:`"IncludeWorkingCopy`",DocumentPath:`"$humanIdentity`",Backward:false,Conditions:[{Key:`"$humanIdentity.SamAccountName`",Operator:`"startswith`",Value:`"j`"}]}"$identityKeys = Invoke-RestMethod -Uri "$client/schema/query" -Method Post -Body $query -WebSession $session

$query = @{}
$query.Recursive = $false # Optional. Default: false
$query.Keys = $identityKeys.ForEach({$_}) # powershell bug

$identities = Invoke-RestMethod -Uri "$client/schema/bulk" -Method Post -Body (ConvertTo-Json $query -Compress)  -WebSession $session

Example 3 - Start workflow

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$find = @{}
$find["Name"] = "Unit Test Website"$devWorkflows = Invoke-RestMethod -Uri "$client/workflow/definition/query" -Method Post -Body (ConvertTo-Json $find) -WebSession $session

foreach ($definition in $devWorkflows)
{
   $form = Invoke-RestMethod -Uri ($definition["self"] + '/form/$start') -WebSession $session
   $formdata = $form.Form

   $data = $form.ExecuteData
   $values = $data.Values
   $values.LDAP_General_Displayname = "Beispielswert"   $values.UNIT_TEST_SCRIPT = @("1st value", "2nd value")
   $data.Values = $values
   $data.Wait = $true # $true: Wait for execution done and return result. $false: Fire & Forget
   $result = Invoke-RestMethod -Uri ($definition["self"] + "/execute") -Method Post -Body (ConvertTo-Json $data) -WebSession $session
   break
}

If the post request is rejected with 400, this may have the following reasons:

The triggers are case-sensitive.
Variables were transferred that are not in the list of the trigger provided. Variables that are not contained in ExecuteData in the Get-Request are also not accepted.
Required variables are empty.
Date variables are not empty, but do not result in a date.
Number variables are not empty, but do not result in a number.
The value of the variable does not match the validation rule. Variables for which no validation rule can be specified in the Studio are checked against “No quotation marks”.

Example 4 - Get and set attachment (update)

Copy

# Get attachment. In this case a PNG-Image.
$image = Invoke-WebRequest -Uri "$client/schema/userdata/44D851A0ADFB4F9C92DEA2B61C674AAE00000000/attachment/ProfileSmallImage" -Method Get -WebSession $session # Die ID (hier 44D851A0ADFB4F9C92DEA2B61C674AAE00000000) erhalten Sie z.B. wie in Beispiel 2
$image = $image.RawContentStream.ToArray()
[System.IO.File]::WriteAllBytes("Pictures\Profile.png", $image)

# Add attachment / create / update
$image = [System.IO.File]::ReadAllBytes("Pictures\admin_level_32.png")
Invoke-WebRequest -Uri "$client/schema/userdata/44D851A0ADFB4F9C92DEA2B61C674AAE00000000/attachment/ProfileSmallImage" -Method Put -Body $image -ContentType "image/png" -WebSession $session
# The content type is required, otherwise the request will be denied with error code 400 (Bad Request).

Javascript

jQuery AJAX

The following example is a pure HTML page. It can, but does not have to, be hosted on a web server. It also works from the file system.

The jQuery-Script can be downloaded from here https://jquery.com/download/ . You might need to change the version.

Enter the hostname, port as well as the username and password.

Default.htm

Copy

<!DOCTYPE html>

<html lang="de" xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="utf-8" />
  <title></title>
  <script type="text/javascript" src="jquery-3.5.1.js"></script>
  <script type="text/javascript" src="login.js"></script>
</head>
<body onload="javascript:login()">
  <form id="form1">
    <h1>unimate ReST Webservice jQuery AJAX</h1>
    <div id="loginData"></div>
  </form>
</body>
</html>

Copy

var userinfo = null;
var serviceUrl = "https://<hostname>:<port>";
var jsonContentType = "application/json; charset=utf-8";
function login() {
  try {
    $.ajax({
      url: serviceUrl + "/login",
      data: JSON.stringify({ UserName: "<username>@<domain>", Password: "<password>" }),
      contentType: jsonContentType,
      type: "POST",
      success: function (data) {
        userinfo = data;
        $("#loginData").text(JSON.stringify(data));
      },
      error: function (x, y, z) {
        alert("error: " + x.responseText + " Status: " + x.status);
      }
    });
  }
  catch (e) {
    alert("Exception: " + e);
  }
}

This HTML code should look something like this: (name and number of clients may vary)

Copy

<div style="border: groove; border-width: 1px; padding: 8px; border-color: lightgray">
<h1>unimate ReST Webservice jQuery AJAX</h1>
<div>{"UserName":"service@ogitix.local","Clients":[{"link":"https://ogitix-dev8.ogitix.local:4567/13bccd01276a46179fc66a2913399dd8","Name":"Entwicklung","Key":"13bccd01276a46179fc66a2913399dd8","IsDevelopment":true,"IsTestEnvironment":false}]}</div>
</div>