Like what you see? Have a play with our trial version.

Error rendering macro 'rw-search'

null

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. Linked with an existing user synchronization process
    In this approach, a user is created at the same time as  a user is created in the external system. This means the user is created before the user attempts to login to Yellowfin for the first time. Updates to the user in the external system would also be propagated to Yellowfin via services immediately.
  2. On-Demand (or Lazy) synchronization
    The on-demand  approach will only create a user in Yellowfin as they are about to login for the first time. This can be done in conjunction with an SSO login process. A common pattern is to have the SSO code perform the following process when the user first attempts to log in: -
  • Check whether the user attempting to log in to Yellowfin exists
  • If the user does not exist in Yellowfin, create the user
  • If the user does exist in Yellowfin, update the user if any details have changed
  • Check that the user has the correct security access
  • If the user access differs from the external system, then adjust the user's group membership so that it is correct.
  • Perform SSO, and direct the user into Yellowfin.

    One issue with on-demand synchronization is that group membership will only be updated when a user logs in. If the user is a recipient of broadcasts via group membership, then they may continue to receive broadcasts after they have been removed from the group in an external system until they login. However an administrator can remove a user from a group manually within Yellowfin.

When using REST services to create and manage users, a user JSON model needs to be provided. This is the format of the User JSON model:

...

Users are also assigned a role which determines their access to various functions within the application. Available Roles can be requested via another API call https://developers.yellowfinbi.com/dev/api-docs/current/#operation/getRoles ).

Retrieving a User

Fetch the details of an existing user from the application. This can also be used to check whether a user already exists. Retrieve user details by querying GET /api/rpc/users/user-details-by-username/{user-name} Get a user by username

The following examples illustrate how to retrieve an existing user (via username) in various programming languages.

Code Block
languagejava
titleJava
Code Block
languagec#
titleC#
Code Block
titleGo
Code Block
languagejs
titleJavaScript
Code Block
languagephp
titlePHP
Code Block
languagepy
titlePython

Creating a User

Create a new user by providing an array of user models to POST /api/admin/users createUserAdmin . Pass multiple user models to create multiple users simultaneously.

The following examples create a new user in various programming languages.

This Java Code example uses Apache HTTP Client and GSON for handling REST calls and JSON serialization.
Code Block
languagejava
titleJava
package rest.code.examples;

import java.io.IOException;
import java.util.Random;
import org.apache.hc.client5.http.fluent.Content;
import org.apache.hc.client5.http.fluent.Request;
import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
/**
 * Create a user using the Yellowfin REST API
 */
public class CreateAUser {
    public static void main(String[] args) throws Exception {

        String host = "http://localhost:8080/Yellowfin";
        String restUsername = "admin@yellowfin.com.au";
        String restPassword = "test";

        String createUserPayload = "[ {" +
                "  \"userId\": \"user1\"," +
                "  \"emailAddress\": \"user1@yellowfin.com.au\"," +
                "  \"roleCode\": \"Consumer & Collaborator\"," +
                "  \"password\": \"test\"," +
                "  \"firstName\": \"User\"," +
                "  \"lastName\": \"One\"," +
                "  \"languageCode\": \"EN\"," +
                "  \"timeZoneCode\": \"AUSTRALIA/SYDNEY\"" +
                " } ]";




        String token = generateToken(host, restUsername, restPassword);
        System.out.println("Payload: " + createUserPayload);
        Content c = Request.post(host + "/api/admin/users")
Code Block
languagec#
titleC#
namespace YellowfinAPIExamples;

using System.Net.Http.Headers;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

public class CreateAUser
{
    static async Task Main(string[] args)
    {
        string host = "http://localhost:8080/Yellowfin";
        string restUsername = "admin@yellowfin.com.au";
        string restPassword = "test";
            
        string createUserPayload = "[ {" +
                                   "  \"userId\": \"user1\"," +
                                   "  \"emailAddress\": \"user1@yellowfin.com.au\"," +
                                   "  \"roleCode\": \"Consumer & Collaborator\"," +
                                   "  \"password\": \"test\"," +
                                   "  \"firstName\": \"User\"," +
                                   "  \"lastName\": \"One\"," +
                                   "  \"languageCode\": \"EN\"," +
                                   "  \"timeZoneCode\": \"AUSTRALIA/SYDNEY\"" +
                                   " } ]";

        string token = await GenerateToken(host, restUsername, restPassword);

        Console.WriteLine("Payload: " + createUserPayload);

        using (HttpClient client = new HttpClient())
        {
            long nonce = new Random().NextInt64();
            HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, host + "/api/admi
Code Block
titleGo
package main

import (
        "bytes"
        "encoding/json"
        "fmt"
        "io/ioutil"
        "math/rand"
        "net/http"
        "time"
)

func main() {
        host := "http://localhost:8080/Yellowfin"
        restUsername := "admin@yellowfin.com.au"
        restPassword := "test"

        createUserPayload := `[{
                "userId": "user1",
                "emailAddress": "user1@yellowfin.com.au",
                "roleCode": "Consumer & Collaborator",
                "password": "test",
                "firstName": "User",
                "lastName": "One",
                "languageCode": "EN",
                "timeZoneCode": "AUSTRALIA/SYDNEY"
        }]`

        token, err := generateToken(host, restUsername, restPassword)
        if err != nil {
                fmt.Println("Error generating token:", err)
                return
        }

        fmt.Println("Payload:", createUserPayload)

        client := &http.Client{}
        request, err := http.NewRequest("POST", host+"/api/admin/users", bytes.NewBuffer([]byte(createUserPayload)))
        if err != nil {
Code Block
languagejs
titleJavaScript
const fetch = require("node-fetch");

async function main() {
    const host = "http://localhost:8080/Yellowfin";
    const restUsername = "admin@yellowfin.com.au";
    const restPassword = "test";

    const createUserPayload = JSON.stringify([{
        userId: "user1",
        emailAddress: "user1@yellowfin.com.au",
        roleCode: "Consumer & Collaborator",
        password: "test",
        firstName: "User",
        lastName: "One",
        languageCode: "EN",
        timeZoneCode: "AUSTRALIA/SYDNEY"
    }]);

    const token = await generateToken(host, restUsername, restPassword);

    if (token === null) {
        console.error("Failed to retrieve access token");
        return;
    }

    console.log("Payload:", createUserPayload);

    const nonce = Math.floor(Math.random() * Number.MAX_SAFE_INTEGER);

    const headers = {
        'Authorization': `YELLOWFIN ts=${Date.now()}, nonce=${nonce}, token=${token}`,
        'Accept': 'application/vnd.yellowfin.api-v1+json',
        'Content-Type': 'application/json'
    };

    try {
        const response = await fetch(`${host}/api/admin/users`, {
Code Block
languagephp
titlePHP
<?php
function main() {
    $host = "http://localhost:8080/Yellowfin";
    $restUsername = "admin@yellowfin.com.au";
    $restPassword = "test";

    $createUserPayload = json_encode(array(
        array(
            "userId" => "user1",
            "emailAddress" => "user1@yellowfin.com.au",
            "roleCode" => "Consumer & Collaborator",
            "password" => "test",
            "firstName" => "User",
            "lastName" => "One",
            "languageCode" => "EN",
            "timeZoneCode" => "AUSTRALIA/SYDNEY"
        )
    ));

    try {
        $token = generateToken($host, $restUsername, $restPassword);
    } catch (Exception $e) {
        echo "Error generating token: " . $e->getMessage();
        return;
    }

    echo "Payload: " . $createUserPayload . "\n";

    $nonce = mt_rand();
    $headers = array(
        'Authorization: YELLOWFIN ts=' . intval(microtime(true) * 1000) . ', nonce=' . $nonce . ', token=' . $token,
        'Accept: application/vnd.yellowfin.api-v1+json',
        'Content-Type: application/json'
    );

    try {
        $response = httpRequest('POST', "$host/api/admin/users", $headers, $createUserPayload);
        echo $response;
    } catch (Exception $e) {
Code Block
languagepy
titlePython
import json
import random
import time

import requests

def main():
    host = "http://localhost:8080/Yellowfin"
    rest_username = "admin@yellowfin.com.au"
    rest_password = "test"

    create_user_payload = json.dumps([{
        "userId": "user1",
        "emailAddress": "user1@yellowfin.com.au",
        "roleCode": "Consumer & Collaborator",
        "password": "test",
        "firstName": "User",
        "lastName": "One",
        "languageCode": "EN",
        "timeZoneCode": "AUSTRALIA/SYDNEY"
    }])

    try:
        token = generate_token(host, rest_username, rest_password)
    except Exception as e:
        print(f"Error generating token: {e}")
        return

    print("Payload:", create_user_payload)

    nonce = random.randint(0, 2 ** 63 - 1)

    headers = {
        'Authorization': f'YELLOWFIN ts={int(time.time() * 1000)}, nonce={nonce}, token={token}',
        'Accept': 'application/vnd.yellowfin.api-v1+json',
        'Content-Type': 'application/json'
    }

    try:


Java | C# | Go | JavaScript | PHP | Python

Updating a User

Updating a user uses the same JSON model specified above. A model including the required changes can be consumed by PATCH /api/admin/users/{userId} (https://developers.yellowfinbi.com/dev/api-docs/current/#operation/updateUser ), where the {userId} is the integer identifier, as returned by GET /api/rpc/users/user-details-by-username )The following examples illustrate how to retrieve an existing user (via username) in various programming languages./{user-name}

The update end-point supports only a single User JSON model, compared to the create user end-point which can accept an array of User JSON models.

The following examples update an existing user in various programming languages:

Java | C# | Go | JavaScript | PHP | Python

Changing a user’s role 

A user’s role can be updated with the standard update end-point. This is done by setting the roleCode in the User JSON model when calling PATCH /api/admin/users/{userId} (https://developers.yellowfinbi.com/dev/api-docs/current/#operation/updateUser ) . The following example introduces the GET /api/roles end-point to retrieve available roles. The example code will modify a user’s role to the first role returned by GET /api/roles.

The following examples change a user’s role in various programming languages:

Java | C# | Go | JavaScript | PHP | Python

Change a user’s password

A user's password can generally only be updated by a user themselves, or by an administrator who has sufficient rights. Passwords are updated by calling PUT /api/admin/users/{userId}/password (https://developers.yellowfinbi.com/dev/api-docs/current/#operation/setUserPasswordAdmin ).

The payload for this REST call can consist of a simple JSON entry that includes the password:

{ "password": "test"}

The following examples update an existing user in various programming languages.

Java | C# | Go | JavaScript | PHP | Python