# Administration (scripting)

# Introduction to Administration addon

## Introduction

The **administration** **addon** includes two very useful features for **Soffid administrators**.

<p class="callout success">On the one hand, we have the ability to generate **custom scripts** and launch them using different mechanisms.</p>

<p class="callout success">On the other hand, the **export** and **import** of Soffid data is enabled</p>

## What is custom scripts?

The Administration addon offers the possibility to <span style="text-decoration: underline;">generate and execute custom scripts</span> to perform any function or process available in the Soffid API.

Soffid 4 has introduced **AI** that allows administrators to <span style="text-decoration: underline;">generate scripts much more easily</span>, making this process accessible to all types of users.

Scripts can be run **manually**, **scheduled**, or enabled to run after certain user **events**.

The **use** of custom scripts depends on the requirements, the most important thing is that it offers the administrator maximum **flexibility** to execute whatever is needed.

Let's look at some **examples** of custom scripts.

- List all active accounts on a system with all their roles.
- Planning to deactivate users upon detecting a period of inactivity.
- Send an email to administrators when a specific role is granted or revoked.
- Perform additional actions when a user is deactivated.
- Apply a mass change to user attributes.
- Send a weekly email with the users who have roles with segregation of duties.

## What is export import?

The Administration addon includes the ability to **export** most Soffid objects and also **import** them.

This utility allows you to manually **backup** part of Soffid or all of its data, and the import function allows you to select some or all of the exported objects

These backups can be useful for different purposes:

- To **restore** the same environment
- To **populate** a new environment
- Or to **migrate** configurations between environments

# How to install the Administration addon in Soffid

## Installation

### Introduction

To use an addon in Soffid, you must download and install it in the Console. There are two ways to do this.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1. </span> The first option is to use the **Soffid 4 marketplace**. You can download and upload it directly from the [Licence and plugin](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/license-and-plugin "License and plugin") page.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">2. </span>The second option is to download the file from the Soffid **download** page and then **upload** it to the Console.

### Soffid 4 marketplace

<p class="callout success">Soffid 4 allows you to install and update plugins through the new Addons marketplace feature.</p>

<p class="callout warning">To access the marketplace, you must have a valid token to use Soffid and have configured the Console via https. Please check the [License and plugin](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/license-and-plugin#bkmrk-actions "License and plugin") page.</p>

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1.</span> Please **log in** to IAM Console.

<p class="callout info">You need to be an **administrator** user of the Soffid console or a user with permission to upload addons.</p>

<p class="callout info">It is recommended to upload the addons to the **master**, this is the way to maintain updated all, master and tenants if there are.</p>

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">2.</span> In the Soffid console, please **go to** the [License and plugin](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/license-and-plugin "License and plugin") page.

`Main Menu > <span class="link" id="bkmrk-configuration">Configuration</span> > Global Settings > License and plugin`

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">3.</span> Then, click the add button "**Add new**" button, open the "Soffid Addons" secction and select the "Instlla addon" option, Soffild will upload the addon file.

<details id="bkmrk-image-2"><summary>Image</summary>

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-08/scaled-1680-/zT1zIAZQODssapPc-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-08/zT1zIAZQODssapPc-image.png)

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-08/scaled-1680-/3uHXtG1pAm5kUzIA-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-08/3uHXtG1pAm5kUzIA-image.png)

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-08/scaled-1680-/uw0ef7PG97IxCUUu-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-08/uw0ef7PG97IxCUUu-image.png)

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-08/scaled-1680-/SnyiSzFTnWhDKIWL-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-08/SnyiSzFTnWhDKIWL-image.png)

</details><span style="color: #a6d100; font-weight: bold; font-size: 18px;">4.</span> Finally, when the addon is installed, the Consola has to be **restarted**, a popup will be displayed to perform this action, you can choose to do it now or later.

<details id="bkmrk-image-3"><summary>Image</summary>

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-09/scaled-1680-/SrBNuFbSm6g6boI8-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-09/SrBNuFbSm6g6boI8-image.png)

</details><span style="color: #a6d100; font-weight: bold; font-size: 18px;">5.</span> Once the Soffid console has restarted, you can **check** if the plugin was correctly uploaded on the "License and plugins" page.

`Main Menu > <span class="link" id="bkmrk-configuration-1">Configuration</span> > Global Settings > License and plugin`

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">6.</span> Now, you can **configure** the addon.

### Download an upload

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1. </span>You could **download** the addon at the following link [http://www.soffid.com/download/enterprise/](http://www.soffid.com/download/enterprise/) if you have a Soffid user with authorization, or in the following [http://download.soffid.com/download/](http://download.soffid.com/download/) by registering.

The addons are in the Addon seccion.

<details id="bkmrk-image"><summary>Image</summary>

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-09/scaled-1680-/dUXAMGDA0M6XJe3A-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-09/dUXAMGDA0M6XJe3A-image.png)

</details><span style="color: #a6d100; font-weight: bold; font-size: 18px;">2.</span> Once the addon is downloaded, please **log in** to IAM Console.

<p class="callout info">You need to be an **administrator** user of the Soffid console or a user with permission to upload addons.</p>

<p class="callout info">It is recommended to upload the addons to the **master**, this is the way to maintain updated all, master and tenants if there are.</p>

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">3.</span> In the Soffid console, please **go to** the [License and plugin](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/license-and-plugin "License and plugin") page.

Soffid 3:

`Main Menu > Administration > <span class="link" id="bkmrk-configuration-2">Configuration</span> > Global Settings > Plugins`

Soffid 4:

 `Main Menu > <span class="link" id="bkmrk-configuration-3">Configuration</span> > Global Settings > License and plugin`

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">4.</span> Then, click the add button "**Upload**" and pick the file and click the "Select" button and Soffild will upload the addon file.

<details id="bkmrk-image-1"><summary>Image</summary>

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-12/scaled-1680-/oSwSvpyjPfmRtugF-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-12/oSwSvpyjPfmRtugF-image.png)

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-12/scaled-1680-/1B3zySXyg11fM02e-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-12/1B3zySXyg11fM02e-image.png)

</details><span style="color: #a6d100; font-weight: bold; font-size: 18px;">5.</span> Finally, when the addon is installed, the Consola has to be **restarted**, a popup will be displayed to perform this action, you can choose to do it now or later.

<details id="bkmrk-image-4"><summary>Image</summary>

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-09/scaled-1680-/SrBNuFbSm6g6boI8-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-09/SrBNuFbSm6g6boI8-image.png)

</details><span style="color: #a6d100; font-weight: bold; font-size: 18px;">6.</span> Once the Soffid console has restarted, you can **check** if the plugin was correctly uploaded on the "License and plugins" page.

`Main Menu > <span class="link" id="bkmrk-configuration-4">Configuration</span> > Global Settings > License and plugin`

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">7.</span> Now, you can **configure** the addon.

# Custom scripts page

## Description

The Custom Scrips page provides the capacity to launch custom scripts to perform any functionality or process that the Soffid API has available.

<p class="callout info">Remember that you can consult the Soffid API at the following linkS: [Soffid 4 public API](https://download.soffid.com/doc/console/latest/iam-common/apidocs/allclasses.html) and [Data &amp; Service model](https://download.soffid.com/doc/console/latest/uml/).</p>

## Screen overview

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-08/scaled-1680-/3eNcxAzDtGiWOVN0-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-08/3eNcxAzDtGiWOVN0-image.png)

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-08/scaled-1680-/3UQA39BnBhzxsSeo-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-08/3UQA39BnBhzxsSeo-image.png)

## Related objects

- [Console log](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/console-log "Console log") : for more details in case an error has been returned if the script type is "On demand".
- [Syncserver monitoring](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/sync-server-monitoring "Sync server monitoring") : for more details in case an error has been returned if the script type is "Shceduled.
- [Scheduled tasks](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/scheduled-tasks "Scheduled tasks") : to manage and execute custom script when the type is "Scheduled".
- [Users](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/users "Users") : 
    - After a user change, the "On user change" is executed.
    - After a grant permission, the "On grant permission" is executed.
    - After a revoke permission, the "On revoke permission" is executed.

## Standard attributes

- **Name** : name of the custom script.
- **Type** : type of the custom sccript. 
    - **Scheduled** : the script is executed in a Sync server and can be scheduled as a task to manage it from the Scheduled tasks page.
    - **On demand** : the script is executed in the Console.
    - **On user change** : the script is executed after any user change (except for granting and revoking roles).
    - **On grant permission** : the script is executed after a grant permission.
    - **On revoke permission** : the script is executed after a revoke permission.

## Actions

### Table actions

<table border="1" id="bkmrk-ai-assistant-ask-our" style="border-collapse: collapse; width: 100%; height: 129.307px;"><colgroup><col style="width: 17.7923%;"></col><col style="width: 82.3161%;"></col></colgroup><tbody><tr style="height: 46.5057px;"><td style="height: 46.5057px;">**Add new**</td><td style="height: 46.5057px;">Allows you to add a new custom script.

To add a new custom script it will be mandatory to fill in the required fields.

</td></tr><tr style="height: 53.0994px;"><td style="height: 53.0994px;">**Delete script**</td><td style="height: 53.0994px;">Allows you to remove one or more custom scripts by selecting one or more records and next clicking the button.

To perform that action, Soffid will ask you for confirmation, you could confirm or cancel the operation.

</td></tr><tr style="height: 29.7017px;"><td style="height: 29.7017px;">**Download CSV file**</td><td style="height: 29.7017px;">Allows you to download a csv file with the data included in the table.</td></tr></tbody></table>

### Detail action

<table border="1" id="bkmrk-ai-assistant-ask-our-1" style="border-collapse: collapse; width: 100%; height: 118.807px;"><colgroup><col style="width: 17.7923%;"></col><col style="width: 82.3161%;"></col></colgroup><tbody><tr style="height: 29.7017px;"><td style="height: 29.7017px;">**AI assistant**</td><td style="height: 29.7017px;">Ask our AI for help to generate scripts more quickly and efficiently. </td></tr><tr style="height: 29.7017px;"><td style="height: 29.7017px;">**Delete script**</td><td style="height: 29.7017px;">Allows you to remove the custom script.

To perform that action, Soffid will ask you for confirmation, you could confirm or cancel the operation.

</td></tr><tr style="height: 29.7017px;"><td style="height: 29.7017px;">**Undo**</td><td style="height: 29.7017px;">Allows you to quit without applying any changes.</td></tr><tr style="height: 29.7017px;"><td style="height: 29.7017px;">**Execute now**</td><td style="height: 29.7017px;">Run the script.  
If it is of the ‘On demand’ type, it runs immediately in the Console.  
If it is of the ‘Scheduled’ type, it must be run from the ‘Scheduled tasks’ screen.</td></tr></tbody></table>

## Others

### Soffid APIs

Below you could find a list of helpful links related to the building of custom scripts.

<p class="callout info">Pubic API for of the classes of Soffid: https://download.soffid.com/doc/console/latest/iam-common/apidocs/allclasses.html</p>

<p class="callout info">API for the internal classes of Soffid: [https://download.soffid.com/doc/console/latest/uml/](https://download.soffid.com/doc/console/latest/uml/)</p>

<p class="callout info">Custom utility classes: [https://bookstack.soffid.com/books/soffid-3-reference-guide/page/utility-classes](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/utility-classes)</p>

### Script examples

Below you will find examples of scripts that will help you understand programming and the possibilities it offers.

<p class="callout info">[Script examples](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/sample-scripts "Sample scripts").</p>

# Custom scripts samples

## Introduction

<p class="callout info">Note that Soffid supports different scripting languages, you can configure it in the [Smart engine settings](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/smart-engine-settings "Smart engine settings") screen. **Soffid 4** configures the smart engine with **Javascript** scripting language as the default.</p>

Additionally, in the initial configuration of the container, we can configure the SOFFID\_TRUSTED\_SCRIPTS environment variable to allow the use of insecure classes. You can find this information visiting [the Installing IAM Console page](https://bookstack.soffid.com/link/27#bkmrk-4.-installation).

## Custom scripts page

The following **examples** of custom scripts can be run directly on the [Custom script](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/custom-scripts-addon-admin "Custom scripts (addon admin)") page.

These scripts can also be used in any other Soffid script component.

The scripts have been generated for the **Javascript engine**.

### Identity scripts

#### Recover a user for userName

```Java
var u = serviceLocator.getUserService().findUserByUserName("admin");
out.print("User: " + u.firstName);
```

#### Print some attributes

```Java
var u = serviceLocator.getUserService().findUserByUserName("test");
out.println("UserName: " + u.userName);
out.println("Name: " + u.firstName);
out.println("LastName: " + u.lastName);
```

#### Print by user the email

```Java
var u = serviceLocator.getUserService().findUserByUserName("test");
out.print("Email: " + u.shortName + "@" + u.mailDomain);
```

#### Print by user some additional data

```Java
llistaDadesUsuari = serviceLocator.getUserService().findUserDataByUserName("test");
for (var i=0; i<llistaDadesUsuari.size(); i++) {
  var dadaUsuari = llistaDadesUsuari.get(i);
  out.println("Atributs " + dadaUsuari.attribute + " = " + dadaUsuari.value);
}
```



#### Recover users from a json query with AI

```Java
/** Print on screen the names of all users whose username contains the letter a
 **/
var userService = serviceLocator.getService("com.soffid.iam.base.service.UserService");
var query = new com.soffid.zkdb.api.Query();
query.setFilter('userName co "a"'); // SCIM filter for username containing 'a'

var pagedResult = userService.findUsers(query);
var users = pagedResult.getResources();

if (users && users.size() > 0) {
  out.println("Users whose username contains 'a':");
  for (var i = 0; i < users.size(); i++) {
    var user = users.get(i);
    out.println(user.userName);
  }
} else {
  out.println("No users found with 'a' in their username.");
}
```

#### Create a new identity

```Java
var newUser = new com.soffid.iam.base.api.User();

newUser.userName = "jkepler";
newUser.firstName = "Johannes";
newUser.lastName = "Kepler";
newUser.userType = "I";
newUser.primaryGroup = "world";
newUser.active = true;
 
serviceLocator.getUserService().create(newUser);
out.println("Created "+newUser.userName);
```

#### Update an identity

```Java
var  u = serviceLocator.getUserService().findUserByUserName("jkepler");
u.userType = "E";
u = serviceLocator.getUserService().update(u);
out.println("Updated "+u.userName);
```

#### Delete an identity

```Java
var u = serviceLocator.getUserService().findUserByUserName("jkepler");
if (u!=null) {
  serviceLocator.getUserService().delete(u);
  out.println("Deleted "+u.userName);
} else {
  out.println("User not found");
}
```

### Account scripts

#### Recover accounts of users in Soffid 3

```Java
la = serviceLocator.getAccountService().findAccountByJsonQuery("users.user.userName eq \"02\" ");
for(a:la) {
  out.println("Cuenta: " + a.name);
  out.println("ID: " + a.id);
  out.println("System: " + a.system + "\n");
}
```

#### Recover accounts of users in Soffid 4 with AI with pagination

```Java
/** search all account whose owner's userName contains the letter 'd' and print the name of the account and the system by the screen
 **/
var query = new com.soffid.zkdb.api.Query();
query.filter = "users.user.userName co \"a\"";
query.pageSize = 2;
query.startIndex = 0;

var pagedResult;
do {
    pagedResult = serviceLocator.getAccountService().findAccounts(query);
    var accounts = pagedResult.resources;

    for (var i = 0; i < accounts.size(); i++) {
        var account = accounts.get(i);
        out.println("Account: " + account.name + ", System: " + account.system);
    }

    query.startIndex += query.pageSize;
} while (query.startIndex < pagedResult.totalResults);
```

#### Remove attribute values of a metadata in Soffid 3

```Java
public void removeUnAttributeValues(String attribute, String system) {
  la = serviceLocator.getAccountService().findAccountByJsonQuery("system eq \""+system+"\"");
  for (a : la) {
    laa = serviceLocator.getAccountService().getAccountAttributes(a);
    for (aa : laa) {
      if (aa.attribute.equals(attribute)) {
        if (aa.value!=null) {
          out.print("accountName: "+accountName+", attribute.value: "+aa.value);
          serviceLocator.getAccountService().removeAccountAttribute(aa);
          out.println(" ---> removed");
        }
      }
    }
  }
}
removeUnAttributeValues("manager","AD");
```

#### Remove attribute values of a metadata in Soffid 4

```javascript
function removeUnAttributeValues(attribute, system) {
  var query = new com.soffid.zkdb.api.Query();
  query.filter = "system eq \"" + system + "\"";
  
  var pagedResult = serviceLocator.getAccountService().findAccounts(query);
  var la = pagedResult.getResources();
  
  for (var i = 0; i < la.size(); i++) {
    var a = la.get(i);
    var laa = serviceLocator.getAccountService().getAccountAttributes(a);
    for (var j = 0; j < laa.size(); j++) {
      var aa = laa.get(j);
      if (aa.attribute == attribute) {
        if (aa.value != null) {
          out.print("accountName: " + a.name + ", attribute.value: " + aa.value);
          serviceLocator.getAccountService().removeAccountAttribute(aa);
          out.println(" ---> removed");
        }
      }
    }
  }
}
removeUnAttributeValues("manager", "AD");
```

### Role scripts

#### Recover roles of a user

```Java
user = serviceLocator.getUserService().findUserByUserName("Ivan");
out.println("Usuari: " + user.userName + "\n");
rolsUser = serviceLocator.getUserService().findUserRolesHierachyByUserName(user.userName);
for(listrRolsUser:rolsUser){
  out.println("Nombre: " + listrRolsUser.name);
  out.println("Descripcion: " + listrRolsUser.description);
  out.println();
}
```

#### Print the associated roles for each account


```Java
var queryUsuaris = new com.soffid.zkdb.api.Query();
queryUsuaris.filter = "userName eq \"david.gomez\"";
var pagedUsuaris = serviceLocator.getUserService().findUsers(queryUsuaris);
var llistaUsuaris = pagedUsuaris.getResources();

for (var i = 0; i < llistaUsuaris.size(); i++) {
  var usuari = llistaUsuaris.get(i);

  var queryComptes = new com.soffid.zkdb.api.Query();
  queryComptes.filter = "users.user.userName eq \"" + usuari.userName + "\"";
  var pagedComptes = serviceLocator.getAccountService().findAccounts(queryComptes);
  var llisstacuentas = pagedComptes.getResources();

  for (var j = 0; j < llisstacuentas.size(); j++) {
    var cuenta = llisstacuentas.get(j);
    out.print("   Cuenta : " + cuenta.name);

    var llistaRole = serviceLocator.getApplicationService().findRoleAccountByAccount(cuenta.id);
    for (var k = 0; k < llistaRole.size(); k++) {
      var role = llistaRole.get(k);
      out.print("      Role: " + role.roleName + "\n");
    }
  }
}
```

#### Print for an account the roles and applications for each of them


```Java
var queryUsuaris = new com.soffid.zkdb.api.Query();
queryUsuaris.filter = "userName eq \"david.gomez\"";
var pagedUsuaris = serviceLocator.getUserService().findUsers(queryUsuaris);
var llistaUsuaris = pagedUsuaris.getResources();

for (var i = 0; i < llistaUsuaris.size(); i++) {
  var usuari = llistaUsuaris.get(i);

  var queryComptes = new com.soffid.zkdb.api.Query();
  queryComptes.filter = "users.user.userName eq \"" + usuari.userName + "\"";
  var pagedComptes = serviceLocator.getAccountService().findAccounts(queryComptes);
  var llisstacuentas = pagedComptes.getResources();

  for (var j = 0; j < llisstacuentas.size(); j++) {
    var cuenta = llisstacuentas.get(j);
    out.print("   Cuenta : " + cuenta.name);
    out.println("   ID: " + cuenta.id);

    var llistaRole = serviceLocator.getApplicationService().findRoleAccountByAccount(cuenta.id);
    for (var k = 0; k < llistaRole.size(); k++) {
      var role = llistaRole.get(k);
      out.print("      Role: " + role.roleName + "\n");
      out.println("          Aplicacion: " + role.informationSystemName);
    }
  }
}
```

#### Print the roles associated with each account


```Java
var query = new com.soffid.zkdb.api.Query();
query.filter = "";
var paged = serviceLocator.getUserService().findUsers(query);
var usuCuenta = paged.getResources();

for (var i = 0; i < usuCuenta.size(); i++) {
  var listaUsuCuenta = usuCuenta.get(i);

  out.println("Usuario: " + listaUsuCuenta.userName);
  out.println("Nombre: " + listaUsuCuenta.firstName);

  var rolsUser = serviceLocator.getUserService().findUserRolesHierachyByUserName(listaUsuCuenta.userName);
  for (var j = 0; j < rolsUser.size(); j++) {
    var listaRolsUser = rolsUser.get(j);
    out.println("Nombre del Rol: " + listaRolsUser.name);
    out.println("Descripcion: " + listaRolsUser.description);
    out.println();
  }
}
```

#### Create a new role

```Java
try {
  var newRol = new com.soffid.iam.iga.api.Role();  
  newRol.name = "Rol_New_Script";
  newRol.description = "Rol Script";
  newRol.informationSystemName = "SOFFID";
  newRol.system = "soffid";
  serviceLocator.getApplicationService().create(newRol);
  out.println("Created: " + newRol.name);

} catch(e) {
    out.println("Error: " + e);
}
```

#### Update a role

```Java
var query = new com.soffid.zkdb.api.Query();
query.filter = "name eq \"Rol editado por script\" and informationSystemName eq \"APPLICATION01\"";

var pagedResult = serviceLocator.getApplicationService().findRoles(query);
var editRole = pagedResult.getResources();

for (var i = 0; i < editRole.size(); i++) {
    var role = editRole.get(i);
    out.println(role.name);
    role.name = "ROL01";
    try {
        role = serviceLocator.getApplicationService().update(role);
        out.println(role.name);
    } catch(e) {
        out.println("Error: " + e.message);
        out.println("Stack: " + e.stack);
    }
}
```

#### Delete a role

```Java
try {
  var editRole = serviceLocator.getApplicationService().findRoleById(16576);
  serviceLocator.getApplicationService().delete(editRole);
} catch(e) {
    out.println("Error: " + e.message);
}
```

#### List the roles of an application

```Java
var query = new com.soffid.zkdb.api.Query();
query.filter = "informationSystemName eq \"SOFFID\"";

var pagedResult = serviceLocator.getApplicationService().findRoles(query);
var list = pagedResult.getResources();

for (var i = 0; i < list.size(); i++) {
    var role = list.get(i);
    out.println(role.name);
}
```

### Mail scripts

#### Send a simple email

```Java
serviceLocator.getMailService().sendTextMail("user@domian.com", "Test", "Hello world!");
out.println("Mail sent!");
```

#### Send emails with attached files

```JavaScript
import javax.mail.BodyPart;
import javax.mail.internet.MimeBodyPart;
import javax.activation.DataHandler;
import javax.activation.FileDataSource;
import java.util.ArrayList;
path = "/tmp/";
name = "file.txt";
BodyPart att = new MimeBodyPart();
att.setDataHandler(new DataHandler(new FileDataSource(path+name)));
att.setFileName(name);
to = "aretha@soffid.com";
cc = "etaylor@soffid.com";
subject = "This is an email with attachment ";
body = "In this email you can see an attachment.";
mimeBodyParts = new ArrayList();
mimeBodyParts.add(att);

serviceLocator.getMailService().sendHtmlMail(to, subject, body, mimeBodyParts);
serviceLocator.getMailService().sendHtmlMail(to, cc, subject, body, mimeBodyParts);
serviceLocator.getMailService().sendTextMailToActors(new String[]{"aretha"}, subject, body, mimeBodyParts);
serviceLocator.getMailService().sendTextMailToActors(new String[]{"aretha"}, cc, subject, body, mimeBodyParts);
out.println("Mails sent!");
```

### Event Sample scripts

#### On grant permission

Update a user attribute when assigning a specific permission

```shell
if (grant.roleName.equals("RS002")) {
  user = serviceLocator.getUserService().findUserByUserName(grant.user);
  if (user != null) {
    attributes = serviceLocator.getUserService().findUserAttributes(user.userName);
    if (attributes == null) {
        attributes = new HashMap();
    }
    attributes.put("language", "Spanish");
    serviceLocator.getUserService().updateUserAttributes(user.userName, attributes); 
  } 
}
```

#### On user change

Run a Python script when the user has assigned an specific role

```javascript
if (user != null) {
  roleGrantList = serviceLocator.getApplicationService().findEffectiveRoleGrantByUser(user.id);
  for(roleGrant:roleGrantList){
    if (roleGrant.roleName.equals("SOFFID_TEST")) {
      // RUN SCRIPT
      String command = "python3 /opt/soffid/iam-console-3/conf/exampleScript.py > /opt/soffid/iam-console-3/conf/resultscript01.txt";
      Process process = Runtime.getRuntime().exec(command);
      user.comments = "ADD comments";
      user = serviceLocator.getUserService().update(user);
    }
  }
}
```

### Agent scripts

#### User full name

```Java
return firstName + lastName;
```

#### Create mainDomain if it doesn't exit

```Java
var mailDomain = "exampledomain";
if (mailDomain != null && mailDomain.contains("@")) {
    var mailTokens = email.split("@");
    mailDomain = mailTokens[1];
}

var service = serviceLocator.getMailListsService();
var domain = service.findMailDomainByName(mailDomain);

if (domain == null) {
    domain = new com.soffid.iam.iga.api.MailDomain();  // ← iga.api
    domain.setCode(mailDomain);
    domain.setDescription(mailDomain);
    domain.setObsolete(new java.lang.Boolean(false));
    domain = service.create(domain);
}

return mailDomain;
```

#### Recover active agents

```Java
var llistaAgents = serviceLocator.getDispatcherService().findAllActiveDispatchers();
for (var i = 0; i < llistaAgents.size(); i++) {
    var agent = llistaAgents.get(i);
    out.println("Nom: " + agent.name);
    out.println("Class Name: " + agent.className + "\n");
}
```

#### Show by a user the agents that have associates

```Java
var queryUsuaris = new com.soffid.zkdb.api.Query();
queryUsuaris.filter = "userName eq \"admin\"";
var pagedUsuaris = serviceLocator.getUserService().findUsers(queryUsuaris);
var llistaUsuaris = pagedUsuaris.getResources();

for (var i = 0; i < llistaUsuaris.size(); i++) {
    var usuari = llistaUsuaris.get(i);
    out.println("Usuario: " + usuari.userName);

    var queryComptes = new com.soffid.zkdb.api.Query();
    queryComptes.filter = "users.user.userName eq \"" + usuari.userName + "\"";
    var pagedComptes = serviceLocator.getAccountService().findAccounts(queryComptes);
    var llisstacuentas = pagedComptes.getResources();

    for (var j = 0; j < llisstacuentas.size(); j++) {
        var cuenta = llisstacuentas.get(j);
        out.print("   Cuenta : " + cuenta.name);
        out.println("   ID: " + cuenta.id);

        var llistaRole = serviceLocator.getApplicationService().findRoleAccountByAccount(cuenta.id);
        for (var k = 0; k < llistaRole.size(); k++) {
            var role = llistaRole.get(k);
            out.print("      Role: " + role.roleName + "\n");
            out.println("          Aplicacion: " + role.informationSystemName);
            out.println("             Agente: " + role.system);
        }
    }
}
```

# Export settings and objects page

## Description

<p class="callout success">Soffid has the functionality that allows you to **export configuration**, Soffid objects, and objects from target systems in a ZIP file.</p>

Every object or configuration will be downloaded into the ZIP in a binary file. This ZIP file could be imported into another Soffid tenant to be used.

<p class="callout info">For more information, you can visit the [Import settings and objects](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/import-settings-and-objects-admin-addon "Import settings and objects (admin addon)") page.</p>

Once you open the **Export settings and objects**, you must select the configuration, objects, and target system objects you want to export. Then you only need to click the **Generate export file** button to download the ZIP that will contain all the previous information selected.

<p class="callout warning">It is not allowed to export the basic configuration and configuration parameters of an agent for security reasons. You must create them manually and make sure you put the same names as in the source system if you are going to import accounts.</p>

## Screen overview

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-12/scaled-1680-/scQrXhae1WZlbrAH-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-12/scQrXhae1WZlbrAH-image.png)

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-12/scaled-1680-/52y0fw1Jrc4Z40hV-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-12/52y0fw1Jrc4Z40hV-image.png)

## Related objects

#### Configuration

- [Metadata](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/metadata "Metadata")
- [Plugins](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/license-and-plugin "License and plugin")
- [Business process definition](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/business-process-definition "Business process definition")
- [Custom scripts](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/custom-scripts-addon-admin "Custom scripts (addon admin)")
- [User types](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/user-types "User types")
- [Group types](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/group-types "Group types")
- [<span style="color: rgb(0, 0, 0);">Account naming rules</span>](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/account-naming-rules "Account naming rules")
- [Password policies](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/password-policies "Password policies")
- [Mail domains](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/mail-domains "Mail Domains")
- [Authorizations](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/authorizations "Authorizations")

#### Objects

- [Users](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/users "Users")
- [Information systems](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/information-systems "Information systems")
- [Groups](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/groups "Groups")
- [Hosts](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/hosts "Hosts")
- [Networks](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/networks "Networks")
- [Mail lists](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/mail-lists "Mail Lists")
- [Role assignment rules](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/role-assignment-rules "Role assignment rules")
- [Segregation of duties](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/segregation-of-duties "Segregation of Duties")
- [Application access tree](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/application-access-tree "Application access tree")
- [Custom objects](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/custom-objects "Custom objects") : the custom objects created on the Metadata page

#### Web SSO settings

- [Attributes](https://bookstack.soffid.com/books/federation/page/attribute-definition "Attribute definition")
- [Policies](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/attribute-sharing-policies-addon-federation "Attribute sharing policies (addon federation)")

#### Target system objects

- [Systems](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/agents "Agents")
- [Accounts](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/accounts "Accounts")
- [Roles](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/roles "Roles")
- [Granted permissions](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/roles "Roles")
- [Attribute mappings](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/agents "Agents")


## Actions

<table border="1" id="bkmrk-expand-all-displays-" style="border-collapse: collapse; width: 100%; height: 119.514px;"><colgroup><col style="width: 20.3052%;"></col><col style="width: 79.5909%;"></col></colgroup><tbody><tr style="height: 29.8785px;"><td style="height: 29.8785px;">**Expand all**</td><td style="height: 29.8785px;">Displays all the attributes of the different blocks.</td></tr><tr style="height: 29.8785px;"><td style="height: 29.8785px;">**Collapse all**</td><td style="height: 29.8785px;">Hide all attributes of the different blocks.</td></tr><tr style="height: 29.8785px;"><td style="height: 29.8785px;">**"Types of views"**</td><td style="height: 29.8785px;">Change the view type: Classic view, Modern view, Compact design.</td></tr><tr style="height: 29.8785px;"><td style="height: 29.8785px;">**Generate export file**</td><td style="height: 29.8785px;">By clicking this button, Soffid will generate a ZIP file with the objects and configuration that you have selected and will download it to your computer.</td></tr></tbody></table>

## Others

#### Exporting and importing

You can **export all the components** you are using in your Soffid implementation, so <span style="text-decoration: underline;">you can use them as a backup</span> in case something happens, <span style="text-decoration: underline;">or to generate a new test environment</span>.

Once the zip file has been generated, you can import it on the [Import settings and objects](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/import-settings-and-objects-admin-addon "Import settings and objects (admin addon)") page, but do not worry about the exported objects. On the import screen itself, once the zip file has been uploaded, <span style="text-decoration: underline;">the screen will allow you to choose the objects you want to update</span> in your Soffid instance.

<div id="bkmrk--2"></div>

# Import settings and objects page

## Description

<p class="callout success">Soffid has the functionality that allows you to **import configuration**, Soffid objects, and objects from target systems from a ZIP file.</p>

This ZIP file must be generated by the export action from another Soffid tenant.

<p class="callout info">For more information, you can visit the [Export settings and objects](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/export-settings-and-objects-admin-addon "Export settings and objects (admin addon)") page.</p>

Once you **pick the file to import**, Soffid will display all the objects and configurations that you can load. You must select the proper objects and settings to import or enable the Load everything option. And finally, you must click the Proceed buttons to launch the import process. Once the process is finished, Soffid will display the result and allows you to download the log file.

<p class="callout warning">It is not allowed to import the basic configuration and configuration parameters of an agent for security reasons. You must create them manually and make sure you put the same names as in the source system if you are going to import accounts.</p>

## Screen overview

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-12/scaled-1680-/SkppodKgmSSTs14S-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-12/SkppodKgmSSTs14S-image.png)

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-12/scaled-1680-/6obcjZdoEbNz6ZbI-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-12/6obcjZdoEbNz6ZbI-image.png)

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2025-12/scaled-1680-/KhgglS0osEMdjUtQ-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2025-12/KhgglS0osEMdjUtQ-image.png)

## Related objects

#### Configuration

- [Metadata](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/metadata "Metadata")
- [Plugins](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/license-and-plugin "License and plugin")
- [Business process definition](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/business-process-definition "Business process definition")
- [Custom scripts](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/custom-scripts-addon-admin "Custom scripts (addon admin)")
- [User types](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/user-types "User types")
- [Group types](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/group-types "Group types")
- [Account naming rules](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/account-naming-rules "Account naming rules")
- [Password policies](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/password-policies "Password policies")
- [Mail domains](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/mail-domains "Mail Domains")
- [Authorizations](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/authorizations "Authorizations")

#### Objects

- [Users](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/users "Users")
- [Information systems](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/information-systems "Information systems")
- [Groups](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/groups "Groups")
- [Hosts](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/hosts "Hosts")
- [Networks](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/networks "Networks")
- [Mail lists](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/mail-lists "Mail Lists")
- [Role assignment rules](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/role-assignment-rules "Role assignment rules")
- [Segregation of duties](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/segregation-of-duties "Segregation of Duties")
- [Application access tree](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/application-access-tree "Application access tree")
- [Custom objects](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/custom-objects "Custom objects") : the custom objects created on the Metadata page

#### Web SSO settings

- [Attributes](https://bookstack.soffid.com/books/federation/page/attribute-definition "Attribute definition")
- [Policies](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/attribute-sharing-policies-addon-federation "Attribute sharing policies (addon federation)")

#### Target system objects

- [Systems](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/agents "Agents")
- [Accounts](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/accounts "Accounts")
- [Roles](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/roles "Roles")
- [Granted permissions](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/roles "Roles")
- [Attribute mappings](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/agents "Agents")



## Actions

#### Pick up page

<table border="1" id="bkmrk-pick-a-file-select-t" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 21.9719%;"></col><col style="width: 77.9242%;"></col></colgroup><tbody><tr><td>**Pick a file**</td><td>Select the backup's file</td></tr></tbody></table>

#### Configuration page

<table border="1" id="bkmrk-load-eveything-enabl" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 21.9338%;"></col><col style="width: 78.0795%;"></col></colgroup><tbody><tr><td style="width: 184.976px; height: 29.8785px;">**Load eveything**</td><td style="width: 624px; height: 29.8785px;">Enable it if you want to load all the backup, disable it if you want to select the object to import</td></tr><tr><td style="width: 184.976px; height: 29.8785px;">**Remove objects not present in the export file**</td><td style="width: 624px; height: 29.8785px;">Remove the Soffid objects not present in the export file, enable it if you want the exact image of the source system, disable it if you want to keep the object that only exist in this Soffid instance</td></tr><tr><td style="width: 184.976px; height: 29.8785px;">**Back**</td><td style="width: 624px; height: 29.8785px;">Go back to "Pick a file"</td></tr><tr><td style="width: 184.976px; height: 29.8785px;">**Proceed**

</td><td style="width: 624px; height: 29.8785px;">Allows you to start the import process.</td></tr></tbody></table>

#### Results page

<table border="1" id="bkmrk-restart-go-back-to-t" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 21.9338%;"></col><col style="width: 77.9603%;"></col></colgroup><tbody><tr><td style="width: 184.976px; height: 29.8785px;">**Restart**</td><td style="width: 624px; height: 29.8785px;">Go back to the configuration page</td></tr><tr><td style="width: 184.976px; height: 46.6667px;">**Download log**</td><td style="width: 624px; height: 46.6667px;">Allows you to download a log with the details of the importation</td></tr></tbody></table>