Administrative tasks

Introduction

Relution performs various automatic background tasks that are scheduled as one-time or recurring tasks. These tasks can be used for system maintenance or creating various reports or notifications.

Create organizations

You are logged in as a system administrator.

To create a new organization, you must log in to the web portal as the administrator of the system organization.

Go to Settings > Organization management.
Click on Add and fill in the necessary fields
- Organization.
- Organization administrators
Click Create to save the changes.
Optional: If your system organization is licensed, you can share a number of device licenses with the newly created organization.

After the organization is created, you can now log in as the organization administrator that you created in the previous step.

Either click the Log in as organization administrator button or log out and log in with the credentials you provided.

Configure multiclient capability

The Multi-client capability use case is primarily for the organizations administrator role.

You are logged in as a system administrator.

In order for a user to be able to switch between different organizations, the following steps must be performed:

Navigate to Users > Groups.
Select the desired group, e.g. Orga1\Administrator.
Click on Manage members.
Select the desired users or groups to be members of this group.
Click on Confirm.
Click Save.

💡

It is not possible to nest default groups.

The selected users and groups are now members of the organization that the group Orga1\Administrator group belongs to (Orga1).

If the selected users originally belong to a different organization (e.g. Orga2), the user can now switch between these two organizations. Likewise, the members of the selected groups can now switch between these two organizations.

The primary organization to which a particular user belongs is always the organization in which the user was created. When a user logs in, he is always logged in to his primary organization.

Certificate expiration notifications

Certificate expiration notifications are sent for all certificates in the Certificate store (see Settings > Certificates) and all APNS certificates of the organization (see Settings > Organization Certificates) are displayed in the Notification Center.

APNS certificates with the following UIDs are reported to the organization administrator(s) in the Notification Center. If they expire, Relution should be updated.

Types of certificate messages:

com.mwaysolutions.enterprise.mway.relutionclient,
com.mwaysolutions.store.relution and
com.apple.mgmt.mway.mwaysolutions

💡

If custom APNS certificates are used, it is mandatory to renew them BEFORE expiration. Otherwise, you may not be able to reach your devices and they will need to be re-enrolled. We recommend using the certificates provided with Relution.

System Portal

The Relution System Portal must be activated via application.yml. To do this, add the following section:

relution:
  spring-boot-admin:
    enabled: true

💡

The Relution System portal can only be opened by users with the ADMIN role.

If the entry is not displayed, the System Portal has not been enabled in the application.yml.

Using the Relution REST API (Application Programming Interface)

All of Relution’s functionality is available through an extensive REST API. You can use this API to control Relution from any other application or via script to control it.

Create API Access Tokens

You need an API Access Token to access Relution from third-party systems or scripts. You can create an Access Token by clicking on the username in the upper right corner of the Relution portal. Then click on Profile > Access Token > Add Access Token.

Name the token and copy it.

💡

The token will only be displayed once when it is created.

Example scripts

Here are some sample scripts that show how the API can be used:

Users in CSV file format

In the first line of the .csv file, insert a header line with a list of the desired property names. The order of the column names is not relevant. You can also omit properties that are not needed. Mandatory fields are:

userid,email,first name,last name,password.

💡

Make sure you follow the password policy when entering a password. This can be found under Settings > Password Policy. Also, the phone number, if used, must be in international format, i.e. +4912345.

In addition, you can set up to 15 custom properties. The corresponding header columns should be named as follows: custom1-custom15.

You can either use the example or download a sample file from the Relution Portal. To do so, click on ‘Users > Users > Three dots menu > Import users via CSV > Download template’.

userid,email,first name,last name,password,phone number,position,country,managed apple id,custom1,custom2
user1,user1@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user1 position,user1 country,user1.id@company.com,43,Operations
user2,user2@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user2 position,user2 country,user2.id@company.com,24,Marketing
user3,user3@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user3 position,user3 country,user3.id@company.com,30,HR
user4,user4@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user4 position,user4 country,user4.id@company.com,32,Sales
user5,user5@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user5 position,user5 country,user5.id@company.com,45,Finance
user6,user6@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user6 position,user6 country,user6.id@company.com,30,Purchase

Uploading users via the Relution portal

Users can be imported on the basis of a .csv file in the Relution UI at Users > Users > Three dots menu > Import users via CSV.

Select your CSV file and the separator used.
In the second step of the wizard, select one or more groups to which the imported users should be added as members.
The users will be imported and will be visible in the overview.

Creating users via the Relution API

To create users in Relution via the API based on a .csv file, you need to create two files. The first is the users.csv file, which must contain one line for each user in the format described above.

The second file you need is a bash script file (.sh). Copy the following example and replace the following attributes with your values:

<valid_Relution_API_Key>
<relution_URL>

Save both files.
Supplementary, the script must be made executable:

    chmod +x ./relutionCSVupload.sh

Execute the script in the terminal as follows:

./relutionCSVupload.sh -f users.csv

    #!/bin/bash
    #--------------------------------------------------------------------------------

    # headers

    ACCESS_TOKEN="<valid_Relution_API_Key>"

    while getopts "a:h:f:r:" opt; do
      case $opt in
        a) # apikey
        APIKEY="$OPTARG"
        ;;

        h) # host
        HOST="$OPTARG"
        ;;

        f) # file
        FILE="$OPTARG"
        ;;

        r) # Role
        ROLE="$OPTARG"
        ;;

        \?)
        echo "Unknown option -$OPTARG" >&2
        ;;
      esac
    done

    APIKEY=$ACCESS_TOKEN
    HOST='https://<relution_URL>'
    # Remember to avoid the last backslash
    echo $HOST

    if [[ -z $APIKEY ]]; then
      echo "Please specify an API Key (-a)".
      exit 1
    fi

    if [[ -z $HOST ]]; then
      echo "Please specify a Host URL (-h)"
      exit 1
    fi

    if [[ ! -f $FILE ]]; then
      echo "Please specify an existing csv file (-f)"
      exit 1
    fi

    if [[ -z $ROLE ]]; then
      ROLE=Organame%20Device%20User
    fi

    ERRORS=0

    echo -n "Importing users from $FILE to Relution server ${HOST} as '${ROLE//%20/ }'... "
    echo
    echo
    # On missing errors information, you can try to run the following curl expression directly to see the full output
    # curl -X POST -H "Accept: application/json" -H "X-User-Access-Token: $APIKEY" -F "file=@$FILE" "$HOST/gofer/security/user/import?overwrite&role=$ROLE"
    HTTP_ERROR=$(curl -X POST -H "Accept: application/json" -H "X-User-Access-Token: $APIKEY" -F "file=@$FILE" -sw "%{http_code}" "$HOST/gofer/security/user/import?overwrite&role=$ROLE")
    echo $HTTP_ERROR
    HTTP_ERROR=${HTTP_ERROR: -6}
    HTTP_ERROR=${HTTP_ERROR: 3}

    if [[ $HTTP_ERROR -ne 200 ]]; then
      ERRORS=$((ERRORS + 1))
      echo "$HTTP_ERROR"
      else
        echo "Done. No Errors."
    fi

    if [[ $ERRORS -gt 0 ]]; then
      echo "Error(s) during upload: ($ERRORS)"
      exit $ERRORS
    fi

    echo "All done."
    echo

Create a new organization

    #!/bin/bash
    #--------------------------------------------------------------------------------

    # Web service URL, change the server name as needed
    SVR_URL="https://<myserver>/api/v1/security/organizations/creationWizardRequests"

    # Access token of System Admin, create it by opening https://<server>/#/profile
    # Open this URL in your browser while logged in as System Administrator.
    # NOTE: This is not an URL you can reach through clicking through the portal!
    ACCESS_TOKEN="<sysadmin_api_token>"

    # HTTP Headers
    ACCEPT="application/json"
    ACCEPT_CHARSET="UTF-8"

    # Query example
    read -r -d '' JSON_BODY << 'EOF'
    {
        "limit": 10,
        "offset": 0,
        "getNonpagedCount": true,
        "sortOrder": {
            "sortFields": [
                {
                    "name": "lastConnectionDate",
                    "ascending": false
                }
            ]
        },
        "filter": {
            "type": "logOp",
            "operation": "AND",
            "filters": [
                {
                    "type": "stringEnum",
                    "fieldName": "platform",
                    "values": [
                        "ANDROID",
                        "ANDROID_ENTERPRISE",
                        "IOS"
                    ]
                },
                {
                    "type": "stringEnum",
                    "fieldName": "status",
                    "values": [
                        "COMPLIANT",
                        "INACTIVE"
                    ]
                }
            ]
        }
    }
    EOF

    echo "Querying devices at $SVR_URL..."
    echo

    # No changes should be required beyond this line...

    RESPONSE=$(curl -X POST \
        ${SVR_URL}${FILTER} \
        -H "X-User-Access-Token: $ACCESS_TOKEN" \
        -H "Accept: $ACCEPT" \
        -H "Accept-Charset: $ACCEPT_CHARSET" \
        -H "Content-Type: $ACCEPT" \
        --write-out " HTTP_STATUS=%{http_code}" \
        --silent \
        -d "$JSON_BODY")
    if [[ $RESPONSE =~ HTTP_STATUS=([0-9]+) ]]; then
        HTTP_STATUS=${BASH_REMATCH[1]}
    fi

    if [[ $HTTP_STATUS -lt 200 || $HTTP_STATUS -gt 299 ]]; then
        echo "HTTP status: $HTTP_STATUS"
    else
        echo "Done. Parsing ouput..."
        echo
        echo "${RESPONSE%HTTP_STATUS*}" | jq '.results[].name'
    fi

Query the devices registered in a particular organization

    #!/bin/bash
    #--------------------------------------------------------------------------------

    # Web service URL, change the server name as needed
    SVR_URL="https://<myserver>/api/v2/devices/baseInfo/query"

    # Access token of an Orga Admin, create it by clicking on the user name in the top right corner of the portal.
    # Then click "Profile", "Access tokens", "Add".
    ACCESS_TOKEN="<orga_admin_access_token>"

    # HTTP Headers
    ACCEPT="application/json"
    ACCEPT_CHARSET="UTF-8"

    # Query example
    read -r -d '' JSON_BODY << 'EOF'
    {
        "limit": 100,
        "offset": 0,
        "getNonpagedCount": true,
        "sortOrder": {
            "sortFields": [
                {
                    "name": "lastConnectionDate",
                    "ascending": false
                }
            ]
        },
        "filter": {
            "type": "logOp",
            "operation": "AND",
            "filters": [
                {
                    "type": "stringEnum",
                    "fieldName": "platform",
                    "values": [
                        "ANDROID",
                        "ANDROID_ENTERPRISE",
                        "IOS"
                    ]
                },
                {
                    "type": "stringEnum",
                    "fieldName": "status",
                    "values": [
                        "COMPLIANT"
                    ]
                }
            ]
        }
    }
    EOF

    echo "Querying devices at $SVR_URL..."
    echo

    # No changes should be required beyond this line...

    RESPONSE=$(curl -X GET \
      ${SVR_URL}${FILTER} \
      -H "X-User-Access-Token: $ACCESS_TOKEN" \
      -H "Accept: $ACCEPT" \
      -H "Accept-Charset: $ACCEPT_CHARSET" \
      -H "Content-Type: $ACCEPT" \
      --write-out " HTTP_STATUS=%{http_code}" \
      --silent \
      -d "$JSON_BODY")
    if [[ $RESPONSE =~ HTTP_STATUS=([0-9]+) ]]; then
      HTTP_STATUS=${BASH_REMATCH[1]}
    fi

    if [[ $HTTP_STATUS -lt 200 || $HTTP_STATUS -gt 299 ]]; then
      echo " HTTP status: $HTTP_STATUS"
    else
        echo "Done. Parsing ouput..."
        echo ${RESPONSE%HTTP_STATUS*} | jq '.results[].name'
    fi
    echo

Administrative tasks

Introduction #

Create organizations #

Configure multiclient capability #

Certificate expiration notifications #

System Portal #

Using the Relution REST API (Application Programming Interface) #

Create API Access Tokens #

Example scripts #

Users in CSV file format #

Uploading users via the Relution portal #

Creating users via the Relution API #

Create a new organization #

Query the devices registered in a particular organization #