# Configuration > Integration engine

Configuration > Integration engine

# Smart engine settings

## Description

<p class="callout success">This page gathers several mechanisms related to soffid's smart engine.</p>

Administrator users will be able to configure the engine mechanism for synchronisation tasks; a task limit to prevent unsupervised mass changes; and the language of the scripts.

## Screen overview

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

## Related objects

- [Agents](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/agents "Agents") : to test the synchronization of an object
- [Syncserver monitoring](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/sync-server-monitoring "Sync server monitoring") : to check if a task is on hold
- [Users](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/users "Users") : to propagate changes manually
- [Custom scripts](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/custom-scripts-addon-admin "Custom scripts (addon admin)") : affected by the language script
- All pages with script type attributes.

## Standard attributes

1. **Task engine mode**: allows you to select the synchronization mode. There are three available options: 
    - **Read only**: it is the option by default in the Soffid installation. No task is synchronized to external systems.
    - **Manual**: only selected synchronization tasks are performed. You could synchronize manually a user, check the "Propagates the changes" action on the Users page. Or also synchronize a whole target system, check the Agents page.
    - **Automatic**: each change is automatically send to target systems.
2. **Tasks limit per transaction**: if a single transaction creates more than this number of tasks, tasks will be held until Soffid administrator releases them. The administrator could check them in the "<span id="bkmrk-sync-server-monitori">Sync server monitoring"</span> page, "Not scheduled tasks" button.
3. **Scripting language**: Soffid allows you to create scripts and you can choose the scripting language: 
    - Beanshell
    - Javascript (by default)
    - Autodetected

<p class="callout info">Soffid offers a set of sample scripts. You can find examples visiting [the Sample scripts page](https://bookstack.soffid.com/books/administration-scripting/page/custom-scripts-samples).</p>

<p class="callout info">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).</p>

## Actions

<table border="1" id="bkmrk-apply-changes-allow-" style="width: 793px;"><tbody><tr><td style="width: 171px;">**Confirm changes**</td><td style="width: 622px;">Allows you to update the engine settings.</td></tr><tr><td style="width: 171px;">**Undo**</td><td style="width: 622px;">Allows you to cancel the changes made and not confirmed.</td></tr></tbody></table>

## Tips

### Task engine mode

Use the task engine mode for these scenarios:

<p class="callout info">**Read Only**: use this option after the Soffid installation until you have at least one target system configured to test the synchronization.</p>

<p class="callout info">**Manual**: use this option for testing environments, or at the beginning of a live release.</p>

<p class="callout info">**Automatic**: use this option for live environments, or also for the testing environments when the platform is mature.</p>

Tasks limit per transaction:

<p class="callout info">Use a high task limit when you are comfortable with the configured processes of Soffid, for instance, 1000 or 10000 depending on the number of accounts of these external systems.</p>

# Agents

## Description

<p class="callout success">Soffid agents are the tool that allows the connection between Soffid and the target systems. To establish the connection with target systems, Soffid provides a large number of connectors that will be able to set up into the Soffid console.</p>

<p class="callout info">You could see the complete list of [Synchronization Server Connectors](https://bookstack.soffid.com/books/connectors "Connectors"). </p>

Soffid administrator has the chance to easily customize attribute mappings for some connectors addons, without having to code it using Java. Soffid provides a graphical interface to perform attribute mapping.

An agent will appear disabled when this agent won't have a server assigned. Bear in mind to select the “Disabled” flag on Server URL criteria when you will query if you want to search for disabled, but defined agents.

<p class="callout warning"><span style="color: rgb(0, 0, 0);">Soffid has an internal agent called **soffid** that does not need to be assigned to a sync server in order to function correctly.</span></p>

## Screen overview

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

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

## Related objects

- <span class="ILfuVd"><span class="hgKElc">[Synchronization servers](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/synchronization-servers "Synchronization servers") : the syncservers availables in the platform, could be primary or proxy type.</span></span>
- <span class="ILfuVd"><span class="hgKElc">[Smart engine settings](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/smart-engine-settings "Smart engine settings") : to configure the engine mode of the synchronization tasks</span></span>
- [User type](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/user-types "User types") : to be used in the provisioning policies
- [Groups](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/groups "Groups") : to be used in the provisioning policies
- <span class="ILfuVd"><span class="hgKElc">[Account naming rules](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/account-naming-rules "Account naming rules") : to configure the user domain</span></span>
- <span class="ILfuVd"><span class="hgKElc">[Password policies](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/password-policies "Password policies") : to configure the password domain</span></span>

## Standard attributes

### Basics tab

- **Task engine mode**: shows the current task engine configuration. For more information visit the <span id="bkmrk-smart-engine-setting">[Smart engine settings](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/smart-engine-settings "Smart engine settings") page.</span>
- **Name:** agent's identifying name.
- **Description**: a brief description of the agent.
- **Usage**: identify whether the accounts created are to be used for IAM or PAM. The IAM and PAM tasks will be managed in separate queues. 
    - <span style="text-decoration: underline;">IAM</span>: for standard provisioning
    - <span style="text-decoration: underline;">PAM</span>: for PAM provisioning 
        - The PAM accounts will be managed as a Shared thread internally.
        - The PAM accounts will be shared accounts and never will be single user accounts.
- **Type**: Identify the connector type to use. Different implementations of the server plugins are included in the connectors installed into Soffid. Each type has a Java class bound, the name of the Java class implementing the connector is displayed next to the connector name.
- **Class name** : class name to identigy the agent type.
- **Server URL**: synchronization will be performed with the selected server. It is allowed to select two servers in cases high disponibility will be necessary. If you choose two servers, when one fails, the other will be used. 
    - If “*Each main synchronization server*” is selected, the agent will be run by every sync server.
    - If *"-disabled-"* is selected, the agent will be disabled.
    - If you select a single sync-server, the agent only will be run on that server.
- **Alternative** URL: segond syncserver to be used in case that the one in the server url will be not available.
- **Shared Thread**: if it is enabled, the same thread will be shared to several synchronization servers.
- **Dedicated Thread**: if "Shared thread" is disabled, it will be available the option to choose the number of threads to dedicate to the synchronization process.
- **Task timeout (ms)**: add a timeout to the synchronization server tasks (query, insert, update, delete, update password, etc). If you add a timeout, when the connection gets this timeout, the synchronization server will stop the request and add it to the queue for a new retry later.
- **Long task timeout (ms)**: add a timeout to the reconciliation server tasks (user, group, role, account, grants, etc). If you add a timeout, when the connection gets this timeout, the synchronization server will stop the request (no retry is added).
- **Read-only**: if it is checked (the selected option is Yes), no change will be applied to the managed system. Only read operations will be allowed.
- **Paused task**: if it is checked (the selected option is Yes), the system remains connected, but the tasks in the queue will be retained. It is very useful when conducting tests and ensuring that no tasks propagate, except the ones we are manually triggering (we pause, make the changes, and when everything is fine, we remove the pause). As a rule, you should pause when making configuration changes in production.
- **Manual account creation**: 
    - If you check NO, Soffid will create the new user accounts applying the defined policies.
    - Check YES if you don't want Soffid to create automatically new accounts for the users.
- **Role-based**: when "Manual account creation" is not checked (option selected is No), it will show "Role-based". Check it if only users with any role on this agent should be created. When the identity or account loses its permissions, the account will be disabled. Uncheck to allow users with no role on it.
- **Delta changes:** to use delta changes in the synchronization, when it is enabled, Soffid perform a merge between the image of the target system and Soffid
- **Remove roles from disabled accounts**: when the agent detects a disabled account all the granted roles are removed in the target system
- **User Type**: when "Manual account creation" is not checked (option selected is No), it will show User Type. Only users of the selected types will be created. Any change made in this field involves all accounts to be recalculated. New ones will be added to the repository and managed systems. Some accounts will get disabled if the owner user no longer belongs to any authorized user type.
- **Groups**: when "Manual account creation" is not checked (option selected is No), it will show "Groups". Identify the business units that are allowed to have an account on this system.
- **User domain**: it is the rule used to determine how to generate account names. If the account name is the same as the user name (as is normally the case), the “Default user domain” should be used. The user domain values are defined on the [Account naming rules](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/account-naming-rules "Account naming rules") page.
- **Password domain**: determines the password policies that will be used. If the "Default password domain" is selected, Soffid passwords will be shared with the managed systems. The user domain values are defined on the [Password policies](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/password-policies "Password policies") page.

<p class="callout info">When uploading authoritative data for identities from a managed system, firstly, users will be created in Soffid as indicated in the attribute mapping, and secondly, accounts will be created for the managed systems only if the agent option "Manual account creation" is not checked and only for User Types indicate.</p>

#### Connector parameters

The custom attributes depend on the used plugin.

Here you will find all the information needed about the available Soffid connectors to integrate external managed systems.

1. [AWS Connector](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/aws-connector "AWS Connector")
2. [CSV Connector](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/csv-connector "CSV Connector")
3. [Google Apps Connector](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/google-apps-connector "Google Apps Connector")
4. [JSON REST Web Services Connector](https://bookstack.soffid.com/books/connectors/chapter/json-rest-web-services-connector "JSON REST Web Services Connector")
5. [LDAP Connector](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/ldap-connector "LDAP Connector")
6. [Oracle Connector](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/oracle-connector "Oracle Connector")
7. [Oracle EBS Connector](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/oracle-ebs-connector "Oracle EBS Connector")
8. [SAP Connector](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/sap-connector "SAP Connector")
9. [SCIM Connector](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/scim-connector "SCIM Connector")
10. [Shell Connector](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/shell-connector "Shell Connector")
11. [SQL Connector](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/sql-connector "SQL Connector")
12. [Windows Connector](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/windows-connector "Windows Connector")
13. [Zarafa Connector](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/zarafa-connector "Zarafa Connector")
14. [SQL Server Connector](https://bookstack.soffid.com/books/connectors/page/sql-server-connector)

### Integration flows tab

Some connector addons have associated integration workflows. On the Integration flows tab you can view the integration flows related to the agent.

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

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

</details>You also can view in detail the workflows.

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

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

</details>Is it posible to If you select any node or component, you will be able to view its configuration and even perform some tests.

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

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

</details><p class="callout info">All the configurations shown on this screen are part of the configuration made on the ‘Attribute mappings’ screen. On this screen, they are filtered according to your needs, and you can also modify them.</p>

### Attribute mapping tab

The attribute mapping tab only appears when the agent allows such customization. Soffid administrators have the chance to easily customize attribute mappings without having to code them using Java. The administrator users can select system objects and the Soffid objects related, manage their attributes, and make either inbound and outbound attribute mappings.

There is an action that creates all the default mapping depending on the agent connector type. That option creates automatically system objects with their attributes and properties, you can select them by clicking on "three points" icon and then the **Create default mapping** option. Once created the default mapping, those can be customized as required.

#### Objects

On this screen, you must configure the objects to be retrieved or synchronised. The objects to be configured depend on each agent.

For each object, you must configure its properties, methods, attributes, or triggers. Their configuration also depends on each agent.

The list of possible objects is as follows, with the most important ones indicated in bold

- **user**
- **account**
- **role**
- **grant**
- **group**
- grantedRole
- allGrantedRoles
- grantedGroup
- allGrantedGroup
- authChange
- mailList
- custom
- host
- network

#### Properties

Some agents require to configure some custom attributes in their properties section.

<p class="callout warning">These properties are specific for each type of connector. You could see all these properties by visiting each connector type page.</p>

#### Methods

This option is only available on some types of connectors. It is used to define methods that can be called using the defined properties.

#### Attributes

Each object mapping defines an agent object name and one bound Soffid object type.

The left hand side attributes are managed system attributes, so they are agent dependent that is being configured. The right side attributes are Soffid attributes and must be selected from an existing list.

<p class="callout warning">It is allowed to use script expressions in the source, but they can only be used in a one-way mapping.</p>

##### System attributes

A configuration agent must define object types that can be created on it. Each object mapping defines an agent object name and needs bound Soffid object type.

At this column, the system's attribute name will be displayed.

When evaluating any expression, either the system or soffid attributes are available as script variables. Moreover, the following variables are available:

<table id="bkmrk-variable-content-ser" style="border-collapse: collapse; width: 100%; height: 285.172px;"><tbody><tr bgcolor="#ddd" style="height: 29.7969px;"><td class="align-center" style="width: 11.7284%; height: 29.7969px;">**Variable**</td><td class="align-center" style="width: 20.7406%; height: 29.7969px;">**Content**</td></tr><tr style="height: 57.7969px;"><td style="width: 11.7284%; height: 57.7969px;">serverService

</td><td style="width: 20.7406%; height: 57.7969px;">Server API that enables an easy object query \[ Search the link "Public API Module" or "Data &amp; Service model" \]

</td></tr><tr style="height: 57.7969px;"><td style="width: 11.7284%; height: 57.7969px;">serviceLocator

</td><td style="width: 20.7406%; height: 57.7969px;">Spring Singleton that gets access to any published service bean. Only available on the main syncserver

</td></tr><tr style="height: 35.3906px;"><td style="width: 11.7284%; height: 35.3906px;">remoteServiceLocator

</td><td style="width: 20.7406%; height: 35.3906px;">Singleton that gets access to any remotely published service bean.

</td></tr><tr style="height: 57.7969px;"><td style="width: 11.7284%; height: 57.7969px;">THIS

</td><td style="width: 20.7406%; height: 57.7969px;">HashMap that contains any soffid or system managed attribute. It can be used when the attribute name is not a valid java identifier.

</td></tr><tr style="height: 46.5938px;"><td style="width: 11.7284%; height: 46.5938px;">dispatcherService

</td><td style="width: 20.7406%; height: 46.5938px;">Service that allows the script to get or update information in the target system.

</td></tr></tbody></table>

<details id="bkmrk-script-example-1-%2F%2Aj"><summary>Script Example 1</summary>

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

```javascript
/*js*/
var name = new javax.naming.ldap.LdapName(distinguishedName);
var rdns = name.rdns;
var g = null;
var rn = null;
for (var i = rdns.length - 2; i > 0; i--) {
  if (rdns[i].type == "DC") break;
  if (g == null) {g = "", rn = ""}
  else {g = g + "/"; rn = "," + rn}
  g += rdns[i].value.toLowerCase();
  rn = rdns[i].type+"="+rdns[i].value;
}
var gi = serviceLocator.groupService.findGroupByGroupName(g);
if (gi == null) {
  var parent = ! rn.contains("/") ?
    "world":
   rn.substring(0, rn.lastIndexOf("/"));
  gi = new com.soffid.iam.api.Group();
  gi.name = g;
  gi.description = rn;
  gi.parentGroup = parent;
  serviceLocator.groupService.create(gi);
}
return g;
```

</details>##### Directions

At the center column, an arrow will show the direction of the information flows.

When the information flows from the system (left) to Soffid (right), the left column name can be replaced by a script expression. This expression will be evaluated on the system object prior to uploading it to Soffid.

When the information flows from Soffid (right) to the managed system (left), the right column can contain a script expression that will be evaluated prior to provisioning the user.

Here are some examples:

<table id="bkmrk-system-attribute-dir" style="border-collapse: collapse; width: 97.8182%;"><tbody><tr bgcolor="#ddd" style="height: 29px;"><td class="align-center" style="width: 18.8576%; height: 29px;">**System attribute**</td><td class="align-center" style="width: 6.08033%; height: 29px;">**Direction**</td><td class="align-center" style="width: 50%; height: 29px;">**Soffid attribute**</td><td class="align-center" style="width: 25.062%;">**Meaning**</td></tr><tr style="height: 29px;"><td style="width: 18.8576%; height: 29px;">cn

</td><td style="width: 6.08033%; height: 29px;">&lt;=&gt;

</td><td style="width: 50%; height: 29px;">accountName</td><td style="width: 25.062%;">The account name is the CN attribute of the LDAP

</td></tr><tr style="height: 29px;"><td style="width: 18.8576%; height: 29px;">departmentNumber

</td><td style="width: 6.08033%; height: 29px;">&lt;=

</td><td style="width: 50%; height: 29px;">```javascript
for (group: secondaryGroups) {
  if  (group.get("name").equals(primaryGroup)) {
    return group.get("description");
  }
}
return null;
```

</td><td style="width: 25.062%;">Assigns the group description of the primary group to the departmentNumber attribute

</td></tr><tr style="height: 29px;"><td style="width: 18.8576%; height: 29px;">baseDN

</td><td style="width: 6.08033%; height: 29px;">=&gt;

</td><td style="width: 50%; height: 29px;">"ou="+primaryGroup+",dc=soffid,dc=org"</td><td style="width: 25.062%;">Assigns the base dn of the user to the proper organization unit that is below dc=soffd,dc=org.

</td></tr></tbody></table>

##### Soffid attributes

<p class="callout info">The Soffid attributes that can be used can be found at the following links.</p>

- [User Object](https://bookstack.soffid.com/link/75#bkmrk-user-object)
- [Account Object](https://bookstack.soffid.com/link/75#bkmrk-account-object)
- [Group Object](https://bookstack.soffid.com/link/75#bkmrk-group-object)
- [Role Object](https://bookstack.soffid.com/link/75#bkmrk-role-object)
- [Grant Object](https://bookstack.soffid.com/link/75#bkmrk-grant-object)
- [Maillist Object](https://bookstack.soffid.com/link/75#bkmrk-maillist-object)
- [Membership Object](https://bookstack.soffid.com/link/75#bkmrk-membership-object)

When evaluating any expression, either the system or soffid attributes are available as script variables. Moreover, the following variables are available:

<table border="1" id="bkmrk-variable-content-ser-1" style="border-collapse: collapse; height: 274px;"><tbody><tr bgcolor="#ddd" style="height: 29.8px;"><td class="align-center" style="width: 11.7284%; height: 29.8px;">**Variable**</td><td class="align-center" style="width: 20.7406%; height: 29.8px;">**Content**</td></tr><tr style="height: 57.8px;"><td style="width: 11.7284%; height: 57.8px;">serverService

</td><td style="width: 20.7406%; height: 57.8px;">Server API that enables an easy object query \[ Search the link "Public API Module" or "Data &amp; Service model" \]

</td></tr><tr style="height: 57.8px;"><td style="width: 11.7284%; height: 57.8px;">serviceLocator

</td><td style="width: 20.7406%; height: 57.8px;">Spring Singleton that gets access to any published service bean. Only available on the main syncserver

</td></tr><tr style="height: 35.4px;"><td style="width: 11.7284%; height: 35.4px;">remoteServiceLocator

</td><td style="width: 20.7406%; height: 35.4px;">Singleton that gets access to any remotely published service bean.

</td></tr><tr style="height: 57.8px;"><td style="width: 11.7284%; height: 57.8px;">THIS

</td><td style="width: 20.7406%; height: 57.8px;">HashMap that contains any soffid or system managed attribute. It can be used when the attribute name is not a valid java identifier.

</td></tr><tr style="height: 35.4px;"><td style="width: 11.7284%; height: 35.4px;">dispatcherService

</td><td style="width: 20.7406%; height: 35.4px;">Service that allows the script to get or update information in the target system.

</td></tr></tbody></table>

<details id="bkmrk-script-example-1-fir"><summary>Script Example 1</summary>

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

```javascript
firstName + " " + lastName
```

</details><details id="bkmrk-script-example-2-att"><summary>Script Example 2</summary>

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

```javascript
attributes = serviceLocator.getUserService().findUserAttributes(userName);
return attributes.get("position");
```

</details>##### Test

With the definition of an object, you can check the system attributes defined, in both the final system and in Soffid.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1. </span>First of all, you need to click the Test button, then Soffid will display a text field and some buttons to perform new actions.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">2. </span>Secondly, the text field must be filled in with the appropriate data. It can be a user, an account, a group or another system object. It depends on the system object you are checking.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">3. </span>Then, you can choose the action to perform.

**Text expression**: allows you to test a system object. Soffid will display a new column with the data already mapped that will be sent during synchronisation to the final system. This data will only be displayed when the address is &lt;= or &lt;=&gt;.

**Synchronize now**: this allows you to synchronize the data object to the target system. This action would be the same as that performed automatically by the task engine; in this case, the agent executes the entire process.

**Fetch system raw data**: brings the data of an object from a target system. The data is displayed in a pop-up window. The data retrieved may depend on the agent's programming or the configuration settings in the properties.

**Fetch Soffid object**: brings the data of a specific system object with processed data to update into Soffid. As with the previous option, it retrieves data from an object in an end system, but then applies the mappings configured in Soffid (with direction =&gt; or &lt;=&gt;), and finally displays the attributes and their exact values that would be saved in Soffid.

#### Triggers

It is allowed to define BeanShell or JavaScript scripts that will be triggered when data is loaded into the target system (**outgoing triggers**).

**The trigger result will be a boolean value**, true to continue or false to stop.

A configuration agent can configure triggers related to the operation to be performed. There are different trigger type, that determines the specific moment at which the script will be triggered.

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation on target objects.

To access Soffid data, you can use<span style="color: #34b4c7;"> **source{"attributeName"}**</span>, which recovers the value of the attributeName. That object will be Soffid format.

Also, you can use<span style="color: #34b4c7;"> **newObject{"attributeName"}**</span> to create the new value or <span style="color: #34b4c7;">**oldObject{"attributeName"}**</span> to get the old value of the target system, those objects will be target system format.

The available triggers that can be configured are as follows:


<table border="1" id="bkmrk-trigger-%C2%A0-preinsert--0" style="border-collapse: collapse; height: 227px;"><tbody><tr bgcolor="#ddd" style="height: 29px;"><td class="align-center" style="width: 133px; height: 29px;">**Trigger**</td><td class="align-center" style="width: 656px; height: 29px;">  
</td></tr><tr style="height: 29px;"><td style="width: 133px; height: 29px;">preInsert

</td><td style="width: 656px; height: 29px;">It will be triggered just before the insert action. It will be used to validate or prevent the insert action, and also to prepare objects or actions when a new object will be inserted

</td></tr><tr style="height: 29px;"><td style="width: 133px; height: 29px;">preUpdate

</td><td style="width: 656px; height: 29px;">It will be triggered just before the update action. It will be used to validate or prevent update an object.

</td></tr><tr style="height: 35px;"><td style="width: 133px; height: 35px;">preDelete

</td><td style="width: 656px; height: 35px;">It will be triggered just before the delete action. It will be used to validate or prevent delete an object.

</td></tr><tr style="height: 35px;"><td style="width: 133px; height: 35px;">postInsert

</td><td style="width: 656px; height: 35px;">It will be triggered just after the insert action. It will be used to trigger or prevent an action.

</td></tr><tr style="height: 35px;"><td style="width: 133px; height: 35px;">postUpdate

</td><td style="width: 656px; height: 35px;">It will be triggered just after the update action. It will be used to trigger or prevent an action.

</td></tr><tr style="height: 35px;"><td style="width: 133px; height: 35px;">postDelete

</td><td style="width: 656px; height: 35px;">It will be triggered just after the delete action. It will be used to trigger or prevent an action.

</td></tr><tr><td style="width: 133px;">preSetPassword

</td><td style="width: 656px;">It will be triggered just after the set password action. It will be used to trigger or prevent an action.

</td></tr><tr><td style="width: 133px;">postSetPassword

</td><td style="width: 656px;">It will be triggered just after the set password action. It will be used to trigger or prevent an action.

</td></tr></tbody></table>

##### Example 1

Get the attribute company option 1:

```Java
company = source{"attributes"}{"company"};
```

Get the attribute company option 2

```Java
userName = source{"userName"};
attributes = serviceLocator.getUserService().findUserAttributes(userName);
company = attributes.get("company");
```

##### Example 2

```Java
role = serviceLocator.getAplicacioService ().findRoleByNameAndSystem ( "Domain Users", "AcitveDirectory");
rg = new java.util.HashMap();
rg.put ("grantedRoleId", role.getId ());

list = new java.util.LinkedList ();
list.add (rg);
newObject{"ownedRoles"} = list;

return newObject{"name"} != null
```

##### Example 3

```Java
if (oldObject.get("userPrincipalName") != null)   {
	newObject.remove("userPrincipalName");   
    newObject.put("groupType", oldObject{"groupType"});
}
```

<p class="callout info">For more examples, you can visit the [Incoming Triggers examples page](https://bookstack.soffid.com/books/connectors/page/incoming-triggers-examples).</p>

### Incoming data tab

On the Incoming data tab, it is allowed to set up a specific configuration for the agent and define BeanShell or JavaScript scripts that will be triggered when data is loaded into Soffid (**incoming triggers**).

#### Incoming data

- **Trust passwords**: check if you can trust it to propagate their passwords to Soffid. Trusted password agents differ from the non-trusted ones in: 
    - Temporary passwords generated from the console only propagate to agents that have trusted passwords checked. In the other case, the agents only receive definitive passwords.
    - When a password has reached its expiry date, it will automatically be disabled on agents where the trusted password is not checked, so the user can no longer access it.
    - When the managed system detects a change in the user request password, the password will be propagated to Soffid only if the agent associated trusted password is checked.
- If you want to forward the authentication requests to trusted target systems, you must enable the Trust passwords option and the proper feature on the [Authentication page](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/authentication "Authentication").
- <span style="color: rgb(0, 0, 0);">**Authoritative identity source**: check if the agent will be used as the source for users' information. It is usually checked for the first load of users into Soffid, and then it is unchecked, being Soffid that manages users. Optionally, you can select a custom workflow to process incoming changes. </span>
- **Full reconciliation**: switch off to enable incremental load process and disable Soffid object removal.
- **Propagate changes**: switch off to prevent sync-server to create synchronization tasks after loading incoming changes.

#### Load triggers

To add a new trigger, it is mandatory first of all, to select a Soffid object on which the action will be performed. Then to select the trigger, that determines the moment at which the script will be triggered. Finally, define the script that will be executed.

The available objects are the following:

- User
- Account
- Group
- Role
- Granted role

Triggers can be used to validate or perform a specific action just before performing an operation or just after performing an operation into Soffid objects. **The trigger result will be a boolean valu**e, true to continue or false to stop.

In a Load Trigger, it is not possible to access to mapping definitions configured on the attribute mapping tab. It will be necessary to use <span style="color: #34b4c7;">**newObject{"attributeName"}**</span> to get the new value, or <span style="color: #34b4c7;">**oldObject{"attributeName"}**</span> to get the old value. Those objects will be in Soffid format.

<p class="callout info">For more info about the Soffid format, you can visit the [Soffid Objects](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/soffid-objects-for-agent-mappings "Soffid Objects (for agent mappings)") page.</p>

<table border="1" id="bkmrk-trigger-%C2%A0-preinsert-" style="border-collapse: collapse; height: 227px; width: 94.0476%;"><tbody><tr bgcolor="#ddd" style="height: 29px;"><td class="align-center" style="width: 15.3393%; height: 29px;">**Trigger**</td><td class="align-center" style="width: 84.6748%; height: 29px;">  
</td></tr><tr style="height: 29px;"><td style="width: 15.3393%; height: 29px;">preInsert

</td><td style="width: 84.6748%; height: 29px;">It will be triggered just before the insert action. It will be used to validate or prevent the insert action.

</td></tr><tr style="height: 29px;"><td style="width: 15.3393%; height: 29px;">preUpdate

</td><td style="width: 84.6748%; height: 29px;">It will be triggered just before the update action. It will be used to validate or prevent update an object.

</td></tr><tr style="height: 35px;"><td style="width: 15.3393%; height: 35px;">preDelete

</td><td style="width: 84.6748%; height: 35px;">It will be triggered just before the delete action. It will be used to validate or prevent delete an object.

</td></tr><tr style="height: 35px;"><td style="width: 15.3393%; height: 35px;">postInsert

</td><td style="width: 84.6748%; height: 35px;">It will be triggered just after the insert action. It will be used to trigger or prevent an action.

</td></tr><tr style="height: 35px;"><td style="width: 15.3393%; height: 35px;">postUpdate

</td><td style="width: 84.6748%; height: 35px;">It will be triggered just after the update action. It will be used to trigger or prevent an action.

</td></tr><tr style="height: 35px;"><td style="width: 15.3393%; height: 35px;">postDelete

</td><td style="width: 84.6748%; height: 35px;">It will be triggered just after the delete action. It will be used to trigger or prevent an action.

</td></tr></tbody></table>

##### Example 1

```Java
userName = newObject {"userName"};
system = "ActiveDirectory";

accounts = serviceLocator.getAccountService()
  .findAccountByJsonQuery("(system eq \"" + system + "\") AND name eq \"" + userName + "\" AND (type eq \"I\")");
.....
user = serviceLocator.getUserService().findUserByUserName(userName);
.......
```

##### Example 2

```Java
...........
if (isFound) {
  newObject{"id-indicator"} = "1";
} else {
  if (contFalse > 0) {
    newObject{"id-indicator"} = "0"; 
  } else if (contNull > 0) {
    newObject{"id-indicator"} =  null;
  } 
} 

```

<p class="callout info">For more examples, you can visit the [Outgoing Triggers examples page](https://bookstack.soffid.com/books/connectors/page/incoming-triggers-examples).</p>

### Massive actions

Massive Actions refer to bulk or large-scale operations that can be performed across multiple identities, accounts, or resources managed by an agent within the Soffid platform. Agents in Soffid are components responsible for interacting with external systems (like directories, databases, or applications) to manage and synchronize identity-related data. Massive actions allow administrators to execute operations on a large number of items simultaneously, making it easier to manage and maintain the system efficiently.

#### Provisioning all users on to managed systems

One of the main features of identity and access management (IAM) is automated user provisioning. User provisioning is the process that ensures the users are created, with proper permissions, updated, disabled, or deleted on to managed systems.

All managed systems must have an agent configuration, which will determine the way to perform the provisioning.

Soffid shows information about the last time that the option was run and a report with the details. You can access the report by clicking the verification icon (✓).

#### Provisioning groups to agent

This proces process that ensures the groups are created, updated, disabled, or deleted on to managed systems.

Soffid shows information about the last time that the option was run and a report with the details. You can access the report by clicking the verification icon (✓).

#### Provisioning roles to agent

This proces process that ensures the roles are created, updated, disabled, or deleted on to managed systems.

Soffid shows information about the last time that the option was run and a report with the details. You can access the report by clicking the verification icon (✓).

#### Propagate groups to agent

This option allows pushing to the managed system all the defined groups in Soffid.

Soffid shows information about the last time that option was run and a report with the details. You can access the report by clicking the verification icon (✓).

#### Reconcile (load target system objects)

The main purpose of reconciling process is to provide a mechanism to ensure that all users are aligned on the specific roles and responsibilities. Reconcile process discovers new, changed, deleted, or orphaned accounts to determine user access privileges.

Not every system connector has the capabilities needed to execute the reconcile process.

When "Read only" property, in Basic parameters, is checked (selected value is Yes), the reconcile process only considers unmanaged accounts.

Soffid shows information about the last time that the option was run and a report with the details. You can access the report by clicking the verification icon (✓).

#### Generate target system potential impact

That option allows you to generate a report with all the potential changes that would be performed on the managed system with the current agent configuration

If that option was performed previously, Soffid will show information about the last time that the option was run and the report with the potential impact. You can access the report by clicking the verification icon (✓).

#### Load authoritative data for identities and groups

Identities use to live on authoritative identity sources and they do in Soffid as well. Each identity may have any number of accounts on each managed system.

When "Authoritative identity source" is checked (option selected is Yes) Soffid will show the option that allows the load authoritative data for identities and groups.

That option performs the operations to **load data of groups and data of identities** from the managed system into Soffid, following the rules configured in the agent.

Soffid shows information about the last time that the option was run and a report with the details. You can access to the report by clicking the verification icon (✓).

Also, Soffid creates a parameter on the [Soffid parameters](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/soffid-parameters "Soffid parameters") page, with information about the version of the data. If you need to perform the load authoritative action, it will be mandatory to delete this parameter before perform the action.

#### Apply system policies

This task retrieves all agent accounts and checks that they have the correct status according to the rules configured in the agent itself.

### Account metadata tab

Agents allow you to create additional data on the "Account metadata" tab, to customize the accounts created for that agent. This additional information will be loaded with the agent's information, or calculated as defined in the mappings. The additional data can be used in both mappings and triggers.

To get the Account Metadata value, or to put value, you need to use <span style="color: #34b4c7;">**accountAttributes{"ATT\_NAME"}**</span>

#### Basics attributes

- **Code**: short name used by scripts and connectors to access the underlying information. It is suggested to use short names without blanks or special characters to make it easier to use.
- **Label**: text displayed just beside the attribute value. It is advised to use short descriptions in order to keep the screen cleaner.
- **Data type**: The attributes can have different data types
- **User hint**: user hint displayed in the screens
- **Description**: description for the

#### Metadata attributes

- **Required**: If the attribute is required, it must have a value in order to save; otherwise, an error message will be displayed.
- **Prevent duplicated values**: mark this field as a unique key for the object type. There is no chance of two objects with the same attribute value. Soffid smart engine will avoid the creation of duplicated objects.
- **Multiple values**: some attributes can contain multiple values for the same object. For instance, an attribute containing the languages a user can speak can be multi-valued, as a user can speak multiple languages.
- **Maximum number of rows to display**: when an attribute is multivalued, the screen size can grow a lot. To prevent such a big form, the system will only display a maximum number of values, and a scroll bar will appear to browse through the attribute values.
- **Size**: primarily for string attributes, specify the maximum length in characters of the attribute value.
- **Values**: primarily for string attributes, you can specify the allowed values for the attribute. Then, the text box that the user has to fill in the data will be replaced by a drop-down list.

#### Dynamic attributes

- **Visibility expression**: write an optional BeanShell expression to check if the field should be displayed or not. The expression should return true or false. The following variables are exposed to the expression: 
    - ownerObject: current object owning the attribute.
    - value: current attribute value.
    - requentContext: tip about the screen using the attribute.
    - inputField: the ZK input object (ZK Framework).
    - inputFields: a map to get access to any other ZK input object (ZK Framework).
    - serviceLocator: locator to use any Soffid engine microservice.
- **Validation expression**: write an optional BeanShell expression to check if the field value is acceptable or not. The expression should return true if the value is acceptable. If the expression returns false or any other object, a warning message will be displayed. When the expression returns a string value, the return value will be considered the warning message to present to the end-user. The following variables are exposed to the expression: 
    - ownerObject: current object owning the attribute
    - value: current value to evaluate.
    - requentContext: tip about the screen using the attribute
    - inputField: the ZK input object (ZK Framework).
    - inputFields: a map to get access to any other ZK input object (ZK Framework).
    - serviceLocator: locator to use any Soffid engine microservice.
- **onLoad trigger**: write an optional BeanShell expression that will be executed just after preparing the user interface. The script can modify in any way the inputField object before it is displayed, but cannot modify other input fields. The following variables are exposed to the expression:
    
    
    - - ownerObject: current object owning the attribute
        - value: current value to evaluate.
        - requentContext: tip about the screen using the attribute
        - inputField: the ZK input object (ZK Framework).
        - inputFields: a map to get access to any other ZK input object (ZK Framework).
        - serviceLocator: locator to use any Soffid engine microservice.
- **onChange trigger**: write an optional BeanShell expression that will be executed just after the user has changed the object value. The script can modify in any way the inputField object or any other input fields. The following variables are exposed to the expression:
    
    
    - - - ownerObject: current object owning the attribute.
            - value: current value to evaluate.
            - requentContext: tip about the screen using the attribute.
            - inputField: the ZK input object (ZK Framework).
            - inputFields: a map to get access to any other ZK input object (ZK Framework).
            - serviceLocator: locator to use any Soffid engine microservice.


##### Example 1

Into the attribute mappings save the value of account metadata:

```
varX <= accountAttributes{"att_name"}
```

##### Example 2

Get the value from the attribute account metadata to use it into a trigger

```Java
strValue = source.get("attributes").get("att_name");
if (strValue != null) {
	.....
	.....
} else {
	.....
    .....
}
```

## Actions

#### Agents query actions

<table border="1" id="bkmrk-add-or-remove-column"><tbody><tr style="height: 28px;"><td style="width: 187.273px; height: 28px;">**"Query"**

</td><td style="width: 620.909px; height: 28px;">Allows you to query roles through different search systems, [Basic and Advanced](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/search-types "Search Types").

</td></tr><tr style="height: 44px;"><td style="width: 187.273px; height: 44px;">**Add new**

</td><td style="width: 620.909px; height: 44px;">Allows you to add a new agent to the system.

To add a new role it will be mandatory to fill in the required fields

</td></tr><tr style="height: 28px;"><td style="width: 187.273px; height: 28px;">**Delete agent**

</td><td style="width: 620.909px; height: 28px;">Allows you to remove one or more agents by selecting one or more records and next clicking this button.

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

</td></tr><tr style="height: 30px;"><td style="width: 187.273px; height: 30px;">**Download CSV file**

</td><td style="width: 620.909px; height: 30px;">Allows you to download a CSV file with the basic information of all agents.

</td></tr></tbody></table>

#### Agent detail actions

<table border="1" id="bkmrk-apply-changes-allows" style="width: 98.1818%; height: 644.703px;"><tbody><tr style="height: 46.5938px;"><td style="width: 23.115%; height: 46.5938px;">**Apply changes (disk button)**

</td><td style="width: 76.885%; height: 46.5938px;">Allows you to create a new agent or update an existing agent. To save the data it will be mandatory to fill in the required fields

</td></tr><tr style="height: 63.3906px;"><td style="width: 23.115%; height: 63.3906px;">**Delete agent**

</td><td style="width: 76.885%; height: 63.3906px;">Allows you to delete the agent.

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

</td></tr><tr style="height: 46.5938px;"><td style="width: 23.115%; height: 46.5938px;">**Import**

</td><td style="width: 76.885%; height: 46.5938px;">Allows you to upload an XML file with the attribute mapping data. This option deletes previous attribute mappings and creates new attribute mapping.

</td></tr><tr style="height: 29.7969px;"><td style="width: 23.115%; height: 29.7969px;">**Export**

</td><td style="width: 76.885%; height: 29.7969px;">Allows you to export an XML file with attribute mappings.

</td></tr><tr style="height: 29.7969px;"><td style="width: 23.115%; height: 29.7969px;">**Create default mapping**

</td><td style="width: 76.885%; height: 29.7969px;">Allows you to create automatically default mappings for the specific Type selected.

</td></tr><tr style="height: 29.7969px;"><td style="width: 23.115%; height: 29.7969px;">**Test**

</td><td style="width: 76.885%; height: 29.7969px;">Check if there is a connection to the target system.

</td></tr><tr style="height: 29.7969px;"><td style="width: 23.115%; height: 63.3906px;">**Preview changes**

</td><td style="width: 76.885%; height: 63.3906px;">When there are some changes to be applied (when the configuration agent is updated), you can check them with this option. If you click this button, Soffid will display a new window with the list of users to be updated.

</td></tr><tr style="height: 29.7969px;"><td style="width: 23.115%; height: 80.1875px;">**Apply now**

</td><td style="width: 76.885%; height: 80.1875px;">When the configuration agent is updated, this button will be displayed. If you click this option the update action will be performed. The progress bar will be displayed during the execution of the process.

This action is performed asynchronously.

</td></tr><tr style="height: 29.7969px;"><td style="width: 23.115%; height: 29.7969px;">**Expand all**</td><td style="width: 76.885%; height: 29.7969px;">Displays all the attributes of the different blocks.</td></tr><tr style="height: 29.7969px;"><td style="width: 23.115%; height: 29.7969px;">**Collapse all**</td><td style="width: 76.885%; height: 29.7969px;">Hide all attributes of the different blocks.</td></tr><tr style="height: 29.7969px;"><td style="width: 23.115%; height: 29.7969px;">**"Types of views"**</td><td style="width: 76.885%; height: 29.7969px;">Change the view type: Classic view, Modern view, Compact design.</td></tr><tr style="height: 29.7969px;"><td style="width: 23.115%; height: 29.7969px;">**Undo**

</td><td style="width: 76.885%; height: 29.7969px;">Allows you to quit without applying any changes made.

</td></tr><tr style="height: 46.5938px;"><td style="width: 23.115%; height: 46.5938px;">**Apply changes**

</td><td style="width: 76.885%; height: 46.5938px;">Allows you to create a new agent or update an existing agent. To save the data it will be mandatory to fill in the required fields. After that the screen will display the agents list.

</td></tr></tbody></table>

##### Integration flows

<table border="1" id="bkmrk-open-flow-opens-a-wi" style="width: 98.1818%; height: 59.5938px;"><tbody><tr style="height: 29.7969px;"><td style="width: 23.0864%; height: 29.7969px;">**Open flow**

</td><td style="width: 76.7901%; height: 29.7969px;">Opens a window with the workflow.

</td></tr><tr style="height: 29.7969px;"><td style="width: 23.0864%; height: 29.7969px;">**Test**

</td><td style="width: 76.7901%; height: 29.7969px;">Allows you to test the workflow.

</td></tr></tbody></table>

##### Attribute mapping

<table border="1" id="bkmrk-apply-changes%2Fsave-a" style="height: 761.282px; width: 98.1818%;"><tbody><tr style="height: 46.5938px;"><td style="width: 22.0025%; height: 46.5938px;">**Apply changes (disk button)**

</td><td style="width: 77.9975%; height: 46.5938px;">Allows you to update the agent with the changes made on Attribute mappings.

</td></tr><tr style="height: 80.1875px;"><td style="width: 22.0025%; height: 80.1875px;">**Add new (object)**

</td><td style="width: 77.9975%; height: 80.1875px;">Allows you to add a new system object based on a Soffid object. Once you click the button, Soffid adds new fields to the form to add new attributes, methods, properties, and/or triggers depending on the agent type.

It is mandatory to apply changes by clicking the diskette button to update the agent.

</td></tr><tr style="height: 46.5938px;"><td style="width: 22.0025%; height: 46.5938px;">**Test**

</td><td style="width: 77.9975%; height: 46.5938px;">Allows the test options buttons: text expression, synchronize now, fetch system raw data, fetch Soffid object

</td></tr><tr style="height: 29.7969px;"><td style="width: 22.0025%; height: 29.7969px;">**Expand all**</td><td style="width: 77.9975%; height: 29.7969px;">Displays all the attributes of the different blocks.</td></tr><tr style="height: 29.7969px;"><td style="width: 22.0025%; height: 29.7969px;">**Collapse all**</td><td style="width: 77.9975%; height: 29.7969px;">Hide all attributes of the different blocks.</td></tr><tr style="height: 47.375px;"><td style="width: 22.0025%; height: 47.375px;">**Delete (object)**

</td><td style="width: 77.9975%; height: 47.375px;">Allows you to delete a system object.

It is mandatory to apply changes by clicking the diskette button to update the agent.

</td></tr><tr style="height: 46.5938px;"><td style="width: 22.0025%; height: 46.5938px;">**Test expression**

</td><td style="width: 77.9975%; height: 46.5938px;">Allows you to test a system object. When you click that option, Soffid will show you new fields and operations to test the system attribute config.

</td></tr><tr style="height: 29.7969px;"><td style="width: 22.0025%; height: 29.7969px;">**Synchronize now**

</td><td style="width: 77.9975%; height: 29.7969px;">Allows you to synchronize a specific system object to the target system.

</td></tr><tr style="height: 31px;"><td style="width: 22.0025%; height: 31px;">**Fetch system raw data**

</td><td style="width: 77.9975%; height: 31px;">Brings the data of a specific system object from a target system.

</td></tr><tr style="height: 29.7969px;"><td style="width: 22.0025%; height: 29.7969px;">**Fetch Soffid object**

</td><td style="width: 77.9975%; height: 29.7969px;">Brings the data of a specific system object with processed data to update into Soffid

</td></tr><tr style="height: 63.3906px;"><td style="width: 22.0025%; height: 63.3906px;">**Add new (property)**

</td><td style="width: 77.9975%; height: 63.3906px;">Allows you to add properties to a specific system object. Once you click the button, Soffid adds new fields to the form to add the property.

It is mandatory to apply changes by clicking the diskette button to update the agent.

</td></tr><tr style="height: 46.5938px;"><td style="width: 22.0025%; height: 46.5938px;">**Delete icon (property)**

</td><td style="width: 77.9975%; height: 46.5938px;">Allows you to delete properties from a specific system object.

It is mandatory to apply changes by clicking the diskette button to update the agent.

</td></tr><tr style="height: 63.3906px;"><td style="width: 22.0025%; height: 63.3906px;">**Add new (system attribute)**

</td><td style="width: 77.9975%; height: 63.3906px;">Allows you to add attribute mappings to a specific system object. Once you click the button, Soffid adds new fields to the form to add the attribute.

It is mandatory to apply changes by clicking the diskette button to update the agent.

</td></tr><tr style="height: 10px;"><td style="width: 22.0025%; height: 10px;">**Delete icon (system attribute)**

</td><td style="width: 77.9975%; height: 10px;">Allows you to delete attribute mappings of a specific system object.

It is mandatory to apply changes by clicking the diskette button to update the agent.

</td></tr><tr style="height: 96.9844px;"><td style="width: 22.0025%; height: 96.9844px;">**Add new (trigger)**

</td><td style="width: 77.9975%; height: 96.9844px;">Allows you to add a trigger to a specific system object that will be executed when data is loaded into a target system. You need to click the button with the add symbol (+) located at the end of the row of Trigger. Once you click the button, Soffid adds new fields to the form to add the trigger.

It is mandatory to apply changes by clicking the diskette button to update the agent.

</td></tr><tr style="height: 63.3906px;"><td style="width: 22.0025%; height: 63.3906px;">**Delete icon (trigger)**

</td><td style="width: 77.9975%; height: 63.3906px;">Allows you to delete a trigger of a specific system object. You need to click the button with the subtraction symbol (-) located at the end of the row Trigger which you want to delete.

It is mandatory to apply changes by clicking the diskette button to update the agent.

</td></tr></tbody></table>

##### Incoming data

<table border="1" id="bkmrk-apply-changes-allows-0" style="width: 98.1818%; height: 165.156px;"><tbody><tr style="height: 46.5938px;"><td style="width: 23.0864%; height: 46.5938px;">**Apply changes (disk button)**

</td><td style="width: 76.7901%; height: 46.5938px;">Allows you to update the Load trigger data with the changes made on the Load Trigger

</td></tr><tr style="height: 80.1875px;"><td style="width: 23.0864%; height: 80.1875px;">**Add new (trigger)**

</td><td style="width: 76.7901%; height: 80.1875px;">Allows you to add a trigger that will be executed when data is loaded into Soffid. Once you click the button, Soffid adds new fields to the form to add the trigger. Then you need to select the Object and the type of trigger and write the customized script.

Finally, you need to apply changes to update the agent.

</td></tr><tr style="height: 38.375px;"><td style="width: 23.0864%; height: 38.375px;">**Delete icon (trigger)**

</td><td style="width: 76.7901%; height: 38.375px;">Allows you to delete a trigger.

It is mandatory to apply changes by clicking the diskette button to update the agent.

</td></tr></tbody></table>

##### Massive actions

<table border="1" id="bkmrk-provisioning-all-use-0" style="width: 98.1818%; height: 216.172px;"><tbody><tr style="height: 29.7969px;"><td style="width: 24.8148%; height: 29.7969px;">**Configuration icon**

</td><td style="width: 75.0617%; height: 29.7969px;">Open the task into the Scheduled tasks page

</td></tr><tr style="height: 46.5938px;"><td style="width: 24.8148%; height: 46.5938px;">**Start**

</td><td style="width: 75.0617%; height: 46.5938px;">To start the task manually from this page, you can query the result here or in the Scheduled tasks page

</td></tr></tbody></table>

##### Account metadata

<table border="1" id="bkmrk-add-account-metadata"><tbody><tr style="height: 29px;"><td style="width: 203px; height: 29px;">**Apply changes (disk button)**

</td><td style="width: 606px; height: 29px;">Allows you to update the agent with the changes made on metadata.

</td></tr><tr style="height: 30px;"><td style="width: 203px; height: 30px;">**Add new**

</td><td style="width: 606px; height: 29px;">Allows you to add account metadata. Once you click the button, Soffid shows you an empty form to fill in with the new account metadata.

Finally, you need to apply changes.

</td></tr><tr style="height: 29px;"><td style="width: 203px; height: 29px;">**Delete**

</td><td style="width: 606px; height: 29px;">Allows you to delete one account metadata. First, you need to click on the account metadata which you want to delete. Then Soffid shows a form with the detailed account metadata. On the hamburger icon of that form, you can find the delete action.

In this case, Soffid will not ask you for confirmation to delete.

</td></tr></tbody></table>

## More information

### Scripting

In the agent's configuration, it may be possible to use scripting to include logic in the attribute mappings and in the trigger scripts.  
  
In the attribute mapping, if you use a script on one side, it will be mandatory to a single direction to the other side:

- System attribute &lt;= script
- script =&gt; Soffid attribute

Below, an easy script to send a full name to the system:

```shell
system attribute <= return firstName + lastName;
```

Below, a more complex script to create the main domain if it doesn't exist in Soffid:

```shell
String mailDomain = null;
if (email != void && email != null && email.contains("@")) {
    String[] mailTokens = email.split("@");
    mailDomain = mailTokens[1];
}
com.soffid.iam.service.MailListsService service = com.soffid.iam.ServiceLocator.instance().getMailListsService();
com.soffid.iam.api.MailDomain domain = service.findMailDomainByName(mailDomain);
if (domain==null) {
    domain = new com.soffid.iam.api.MailDomain();
    domain.setCode(mailDomain);
    domain.setDescription(mailDomain);
    domain.setObsolete(new Boolean(false));
    domain = service.create(domain);
}
return mailDomain;
 
=> mailDomain
```

<p class="callout info">You could find a set of sample scripts: [Sample scripts](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/sample-scripts "Sample scripts")</p>

<p class="callout info">You could find a link with the SCIM Query Language used in some methods as findUserByJsonQuery("query"). You can visit the [SCIM chapter](https://bookstack.soffid.com/books/scim "SCIM").</p>

<p class="callout info">Below you could find a set of custom utility classes: [Utility classes](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/utility-classes "Utility classes")</p>

### Password synchronization

The passwords a user has on an agent will be synchronized with any other "single user" account the user has on this agent. Shared accounts will never get their password synchronized.

Password in an agent will be also synchronized with any other account the user has on other agents that are sharing the same password domain.

The password change can be produced by an operator using the Soffid console, the user itself using the Soffid Self Service portal, or a timed automatic task. Furthermore, some managed systems can forward their password to Soffid in order to get them synchronized. In order to accept these password changes coming from managed systems, the trusted passwords box must be checked for the source agent.

Mind that this is the flow for normal user passwords. Temporary passwords generated by the Soffid console will only be sent to agents marked as trusted. Agents not checked as trusted will have a random new password instead. Later, when the user changes the password on Soffid or any trusted system, the new password will be notified to Soffid by the managed system, and every agent on the same password domain will actually get the new password.

### Agents account management

The agent configuration sets the way accounts are created and disabled.

Whenever a user is modified, the following rules will be applied to check if the user should have or not an account on this agent:

1. The user type is checked against valid user types.
2. If there is a business unit or group bound to the agent, the user membership will be assessed.
3. If the role based box is checked, the system will verify if the user has any role or entitlement assigned to this agent.

If the user does not apply for any of the conditions, every account the user has at this agent will be changed to Disabled status.

If the user verifies every one of the conditions, the user can have an account on this agent. Every account the user has at this agent will be changed to Enabled status.

Unless the "Manual account creation" is checked, if the user can have an account on this agent, but it has no one, the account creation method will be invoked. To create it, Soffid will search for the user domain bound to this agent and will follow its configuration. If the user domain is configured with a script, this script will be executed and the result value will be accepted as the new account name. Mind that if the script returns a null value, no account can be created.

If the returning value from the script clashes with an existing account, the existing account will remain unchanged, unless the existing account is marked as an unmanaged account. In such a case, the account will be changed from an unmanaged state to a single user.

### Monitoring

After the agent configuration you could check on the [Sync server monitoring](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/sync-server-monitoring "Sync server monitoring") page if the service is running in the Synchronization Server.

On the same screen you could check is the agent has pending tasks.

### Authoritative task

If you are checked "Authorized identity source", an automatic task to load identities from the managed system to Soffid is available.

And you will something like "&lt;AGENT\_NAME&gt;: Load authoritative data for identities and groups".

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

You can also run the Authoritative load from the Massive actions tab in the Agent

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

### Reconcile task

If you are configured the "Attribute Mapping" tab with some of our objects: "user, account, role, group or grant", an automatic task to synchronize these objects from the managed system to Soffid is available.

And you will do something like "&lt;AGENT\_NAME&gt;: Reconcile (load target system objects)".

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

You can also run the Reconcile from the Massive actions tab in the Agent

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

### Synchronization

Regarding the synchronization of the objects, there are two possible options:

- If the "Read Only" attribute is checked in the "Basics" tab (select Yes option), only the changes in the managed systems will be updated in Soffid. We recommend these options until the global configuration of Soffid will be tested.
- If the "Read Only" attribute is not checked in the "Basics" tab (select No option), all the changes in Soffid or the managed system will be updated in the other. Note that this synchronization must be configured in the "Basic" tab correctly.

# Synchronization servers

## Description

<p class="callout success">Sync server is the engine responsible for connecting Soffid with data sources or managed systems.</p>

Soffid allows you to configure different synchronization servers. These synchronization servers are **installed and configurated using command line tool.**

<p class="callout info">More information about how to install sync server on [the Installation chapter](https://bookstack.soffid.com/books/installation). Here you can find information on how to install a sync server in different environments.</p>

There are several types of synchronisation servers, each with its own specific function within the Soffid architecture. You can see them in the [Standard attributes](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/synchronization-servers#bkmrk-standard-attributes "Standard attributes") section.

### About tasks and systems

Whenever an action is performed on any Soffid object, a synchronization task is created in Soffid database.

Initially, most of the tasks should be forwarded to every managed system connector. The specific system connector will be responsible for applying (or ignoring) the task to the managed system.

The normal synchronization server flow for a task is as follows:

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">1. </span>Engine timely reads pending tasks table (SC\_TASQUE). To avoid two sync servers to process the same task, the column TAS\_SERVER is updated to reflect the actual server that is processing it.

**<span style="color: #a6d100; font-weight: bold; font-size: 18px;">2. </span>**Engine manage tasks priorities and updates the task queue. Engine keeps track of one task queue for each managed system connector.

Soffid allows you to configure the parameter **soffid.sync.engine.threads** with the number of threads available to run the tasks.

<p class="callout info">For more information about this parameter you can visit the [Soffid Parameters](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/soffid-parameters "Soffid parameters") page.</p>

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">3. </span>Engine has created some execution threads to forward each task to the specific connector class. During this process, dispatcher can decide to reject (mark as done) the task without forwarding it.

**<span style="color: #a6d100; font-weight: bold; font-size: 18px;">4. </span>**The specific connector class gets additional information about the task from core services.

<span style="color: #a6d100; font-weight: bold; font-size: 18px;">5. </span>Task is removed from database when every dispatcher has done it.

This architecture and its optimized engine allow Soffid to achieve great performance.

## Screen overview

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

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

## Related objects

- [Agents](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/agents "Agents") : all agentes are executed on one or more synchronisation servers
- [Tenants](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/tenants): the plugins are managed in the master tenant.
- [Sync server monitoring](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/sync-server-monitoring "Sync server monitoring") : where the synchronisation servers are monitored

## Standard attributes

- **Name**: name of the synchronization server (It is the name specified in the configuration; it cannot be changed by the user interface).
- **URL**: URL of the synchronization server (https://{name}:{port}/).
- **Type**: there are different kinds of synchronization servers: 
    - **Synchronization server**: or also known as the principal sync server. That server connects to the main database and allocates the task to the different agents. If more than one is configured, they balance the workload and assign synchronisation tasks themselves.
    - **Synchronization agent proxy**: uses a push mechanism. The main Synchronization server will send the tasks to the synchronization agent proxy when it detects tasks for the proxy. That server does not connect to the main database.
    - **Remote synchronization server**: uses a pull mechanism. That server is asking for its tasks, when it asks and the Synchronization server has a task for the remote, the Synchronization server will send that tasks. That server does not connect to the main database.
    - **Synchronization agent gateway**: this server is the broker between the main synchronization server and the remote servers.
- **Java options**: additional parameters to pass to JVM (Java Virtual Machine). Some useful parameters: 
    - For a high capacity server are: `<span style="color: #236fa1;">-Xmx1024M</span>`
    - For debugging communication: -Djavax.net.debug=ssl
    - To enable sync server to use old TLS version in client connections (from sync server to a managed system) add `<span style="color: #236fa1;">-Djdk.tls.client.protocols=TLSv1,TLSv1.1</span>` (Be in mind TLSv1.2 will be the default version, but some old applications can use TLSv1)
    - To enable sync server to use old TLS version for incoming connections (from a server or desktop to the sync server) add `<span style="color: #236fa1;">-Dsoffid.tls.protocols=TLSv1.1,TLSv1,TLSv1.2,TLSv1.3  -Dsoffid.tls.excludedCiphers="^.*_(MD5)$"</span> `Mind that the system security can be compromised by using deprecated TLS protocols
    - To define how long Java keeps the DNS (domain name resolution) responses in cache you can add the paramameters <span style="background-color: rgb(255, 255, 255); color: rgb(35, 111, 161);">`-Dsun.net.inetaddr.ttl=1`</span> or the newest `<span style="color: rgb(35, 111, 161);">-Dsun.net.inetaddr.ttl=1</span> ` "time-to-live" (TTL).

<p class="callout warning">If you change the Java Options of an existing Syncserver, you will need to restart the Syncserver. You can visit the [Sync server monitoring](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/sync-server-monitoring "Sync server monitoring") page for more information about how to restat the Syncserver.</p>

## Actions

#### Table actions

<table border="1" id="bkmrk-add-or-remove-column"><tbody><tr><td style="width: 152px;">**Download CSV file**

</td><td style="width: 626px;">Allows you to download a CSV file with the information of all synchronization servers.

</td></tr></tbody></table>

#### Synchronization server detail

<table border="1" id="bkmrk-apply-changes-allows" style="width: 93.0952%; height: 356.125px;"><tbody><tr style="height: 46.5938px;"><td style="width: 18.0538%; height: 46.5938px;">**Apply changes (disk button)**

</td><td style="width: 81.9462%; height: 46.5938px;">Allows you to save the synchronization server data.

</td></tr><tr style="height: 63.3906px;"><td style="width: 18.0538%; height: 63.3906px;">**Delete synchronization server**</td><td style="width: 81.9462%; height: 63.3906px;">To delete a sync server you can click on the "three points" icon and then click the delete synchronization server button. Soffid will ask you for confirmation to perform that action, you could confirm or cancel the operation.

</td></tr><tr style="height: 29.7969px;"><td style="width: 18.0538%; height: 29.7969px;">**Undo**

</td><td style="width: 81.9462%; height: 29.7969px;">Allows you to undo any changes made.

</td></tr><tr style="height: 24.375px;"><td style="width: 18.0538%; height: 24.375px;">**Apply changes**

</td><td style="width: 81.9462%; height: 24.375px;">Allows you to save the synchronization server data. Once you apply changes, the details page will be closed.

</td></tr></tbody></table>

# Account naming rules

## Definition

<p class="callout success">Account naming rules define how to generate account names for target systems. The normal case is the account name will be the same as the user name, in other cases, here you could define the customized account name rules.</p>

When you are configuring an agent, you have to indicate the user domain which will be used to create new accounts, that user domain refers to the Account naming rules defined on the Soffid console.

## Screen overview

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

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

## Related objects

- [Agents](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/agents): the account naming rule is selected for each of the agents.
- [Accounts](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/accounts): when creating an account, if no account name is specified, the system uses the naming rule to generate an account name.
- [Users](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/users "Users"): when we add an account, the naming rules indicate the generated name (which can be modified during the process).

## Standard attributes

- **Code**: code used to identify the account naming rule.
- **Description**: a brief description of the rule. That value will be displayed to select the user domain on the agent's setup.
- **User domain type**: use to define the kind of 
    - <span style="text-decoration: underline;">Same as user name</span>: use the main user name.
    - <span style="text-decoration: underline;">Assigned manually</span>: the user will assign the account name.
    - <span style="text-decoration: underline;">Generated by script</span>: allows you to configure the script condition and script creation of account naming.
- **Create account condition**: defines the conditions to enable or prevent the creation of the account. It is only available when the "Generated by script" option is selected in the "User domain type".
- **Script**: computes the name to assign to the user account. If the script returns null, the account is not going to be created. It is only available when the "Generated by script" option is selected in the "User domain type".

## Actions

#### Table actions

<table id="bkmrk-add-or-remove-column" style="width: 96.4286%; height: 116.188px;"><tbody><tr style="height: 46.5938px;"><td style="width: 20.2719%; height: 46.5938px;">**Add new**

</td><td style="width: 79.7281%; height: 46.5938px;">Allows you to add a new account naming rule in the system. To add a new account naming rule it is necessary to fill in the required fields.

</td></tr><tr style="height: 29.7969px;"><td style="width: 20.2719%; height: 29.7969px;">**Delete user domain**

</td><td style="width: 79.7281%; height: 29.7969px;">Allows you to remove one or more account naming rules by selecting one or more records on the list.

</td></tr><tr><td style="width: 20.2719%;">**Download CSV file**

</td><td style="width: 79.7281%;">Allows you to download a CSV file with all the information about account naming rules.

</td></tr><tr style="height: 10px;"><td style="width: 20.2719%; height: 10px;">**Import**

</td><td style="width: 79.7281%; height: 10px;">Allows you to upload a CSV file with the account naming rules configuration to add new rules to the system.

First, you need to pick up a CSV file, that CSV has to contain a specific configuration. Then you need to check the contents. And finally, you need to select the mappings for each column of the CSV file to import the data correctly and click the Import button.

</td></tr></tbody></table>

#### Account naming rules detail

<table id="bkmrk-apply-changes-allows" style="width: 96.4286%; height: 335.36px;"><tbody><tr style="height: 46.5938px;"><td style="width: 18.1726%; height: 46.5938px;">**Apply changes (disk button)**

</td><td style="width: 81.8274%; height: 46.5938px;">Allows you to save the account naming rule data.

</td></tr><tr style="height: 63.3906px;"><td style="width: 18.1726%; height: 63.3906px;">**Delete synchronization server**</td><td style="width: 81.8274%; height: 63.3906px;">To delete a account naming rule you can click on the "three points" icon and then click the delete user domain button. Soffid will ask you for confirmation to perform that action, you could confirm or cancel the operation.

</td></tr><tr style="height: 29.7969px;"><td style="width: 18.1726%; height: 29.7969px;">**Undo**

</td><td style="width: 81.8274%; height: 29.7969px;">Allows you to undo any changes made.

</td></tr><tr style="height: 46.5938px;"><td style="width: 18.1726%; height: 46.5938px;">**Apply changes**

</td><td style="width: 81.8274%; height: 46.5938px;">Allows you to save the account naming rule data. Once you apply changes, the details page will be closed.

</td></tr></tbody></table>

## Others

### Addins a new account

Create a new account naming rule.

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

Configure it in an agent.

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

In a user, add a new account for that agent.

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

### Script examples

#### Condition

Only users with mail address in soffid.com can have an account:

```JavaScript
"soffid.com".equals(user.mailDomain)
```

When the account name depends on other attribute

```JavaScript
attributes.get("userCode")!=null && !attributes.get("userCode").isEmpty()
```

#### Script

Uses the email address as the account name

```JavaScript
user.shortName+"@"+user.mailDomain
```

Username in uppercase

```JavaScript
user.userName.toUpperCase()
```

When the account name depends on other attribute (check that it has a value in the condition)

```JavaScript
attributes.get("userCode")
```

# Attribute translation tables

## Definition

<p class="callout success">Soffid provides an easy to use mechanism to translate references or external codes into internal codes. For example, the HHRR application could be using a diferent coding scheme for business units.</p>

To deal with this data mismatch, users can extend the data model, or can either use translation tables. This screen allows the user to create and maintain such tables. This tables can also be downloaded or uploaded as CSV files, enable the import of data contained into spreadsheets.

Usage of translation table is bound, but not restricted to, attribute translation expressions, by using trigger scripts, through the use of serverService interface.

<p class="callout warning">Before using the **attribute translation tables**, bear in mind that Soffid offers **attribute expansion** for some objects, or directly allows the creation of new **custom objects** with their own attribute definitions. Analyse which solution best suits your needs. Consult the [metadata](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/metadata "Metadata") screen.</p>

## Screen overview

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

## Related objects

- [Metadata](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/metadata "Metadata") : custom objects are an alternative for storing and updating data
- [Custom scripts](https://bookstack.soffid.com/books/soffid-4-reference-guide/page/custom-scripts-addon-admin "Custom scripts (addon admin)") : page to test or use the attribute translation tables

## Standard attributes

- **Domain**: the domain column represents the translation table name.
- **Column 1**: value
- **Column 2**: value
- **Column 3**: value
- **Column 4**: value
- **Column 5**: value

Column 1 to 5 meaning is user defined. Usage of translation table is bound, but not restricted to, attribute translation expressions, through the use of serverService interface.

## Actions

<table id="bkmrk-query-allows-to-sear-0"><tbody><tr><td style="width: 170.5px;">**"Query search"**

</td><td style="width: 651.5px;">Allows to query groups through different search systems, [Quick, Basic and Advanced](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/search-types "Search Types").

</td></tr><tr><td style="width: 170.5px;">**Add new**

</td><td style="width: 651.5px;">Allows you to add a new attribute translation table. That option adds a new row on the table to fill in the data. It will be mandatory to apply changes to save the data.

</td></tr><tr><td style="width: 170.5px;">**Delete translation**

</td><td style="width: 651.5px;">Allows you to remove one or more translations by selecting one or more records and next clicking this button. To perform that action, Soffid will ask you for confirmation, you could confirm or cancel the operation.

</td></tr><tr><td style="width: 170.5px;">**Download CSV file**

</td><td style="width: 651.5px;">Allows you to download a CSV file with the information of all attribute translation tables.

</td></tr><tr><td style="width: 170.5px;">**Import**

</td><td style="width: 651.5px;">Allows you to upload a CSV file with the attribute translation table data to add to the system.

First, you need to pick up a CSV file, that CSV has to contain a specific configuration. Then you need to check the contents. And finally, you need to select the mappings for each column of the CSV file to import the data correctly and to click the Import button.

</td></tr><tr><td style="width: 170.5px;">**Undo**

</td><td style="width: 651.5px;">Allows you to undo any changes made.

</td></tr><tr><td style="width: 170.5px;">**Apply changes**

</td><td style="width: 651.5px;">Allows you to save new attribute translation tables or to save updated attribute translation tables.

</td></tr></tbody></table>

## Examples

##### Example 1

```javascript
lCentros = serviceLocator.getAttributeTranslationService().findByColumn1("CENTROS", "Madrid");
if (lCentros != null) {
    for (var i = 0; i < lCentros.length; i++) {
      if (lCentros[i] != null) {
      	out.println("** Centro - " + lCentros[i].column1 + " - "  + lCentros[i].column2 + " - " 
                    + lCentros[i].column3 + " - "  + lCentros[i].column4);
      }
    }
}
```

##### Example 2

```javascript
lServer = serviceLocator.getAttributeTranslationService().findByExample("SERVER_COPIAS", null, null);
if (lServer != null) {
	out.println("** SERVER_COPIAS - " + lServer);
}
```

##### Example 3

```javascript
// Rename translation tables

void rename(String currentDomain, String newDomain) {
  lat = serviceLocator.getAttributeTranslationService().findByExample(currentDomain, null, null);
  for (at : lat) {
    at.domain = newDomain;
    serviceLocator.getAttributeTranslationService().update(at);
    out.println("Renamed: "+at.domain+", "+at.column1+", "+at.column2+", "+at.column3);
  }
}

rename("COUNTRY", "COUNTRY_COMPANY");
rename("TEST", "TEST_COMMAND");
```

##### Example 4

```javascript
lt = serviceLocator.getAttributeTranslationService().findByExample("COUNTRY", null, null);
for (var i=0; i<lt.length; i++) {
  var t = lt.get(i);
  out.println(t.column1+" is "+t.column2+" or "+t.column3);
}
```

# Network discovery

## Description

The Network discovery tool will be in charge to scan the networks to find the hosts and retrieve information about user accounts. Network discovery can detect system accounts as well.

First of all, you need to create the networks that you want to scan. Visit the [Networks page](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/networks "Networks") for more information. Then, on the Network discovery page, you need to configure for each network, the accounts and passwords of potential administrators to connect to the host and retrieve the information. And finally, you need to start the process execution or you can schedule the execution of the network discovery task.

The operating system of machines can be Windows or Linux and it is not necessary to install any additional software on those machines.

<p class="callout warning">When the Network discovery process is finished, it is **recommended to launch the Reconciliation process of the agents** created by the process to detect the **Account protected services.** To know how to run the Renconciliation process you can visit [the Agents page](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/agents).</p>

<p class="callout info">Once the machines and accounts, both user and system, have been discovered, the critical accounts must be located in the password vault. You can visit the [Password vault page](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/password-vault "Password vault") for more information.</p>

### How Network discovery works?

The **Network Discovery** is the tool in charge to scan the network to discover the hosts of the network. For each host discovered, the **Nmap** utility gets the info about the ports and the protocols used. Also, that process gets the IP Address and the operating system. All the recover information will be saved on Soffid database. The discovery proxy server works as a proxy to connect to the target systems.

When the discovery manager discovers a host, it gets the host information and then, through discovery proxy server, it attempts to connect to the host using the accounts defined on the accounts to probe list.

- If it can not connect to the host, it will attempt with the next host discovered.
- If it gets to connect to the host, then it will create automatically a Soffid agent with the proper attributes and connector parameters, also with the necessary account metadata.

Then, the reconciliation process of the created agent, will be launched and it will try to recover the information about the accounts defined on the host. Also, it will try to recover the information about the account protected services. The recover information will be saved on Soffid database.

## Screen overview

<iframe allowfullscreen="allowfullscreen" height="314" src="https://www.youtube.com/embed/pXtYazC80Vs?rel=0" width="560"></iframe>

## Standard attributes

### Network attributes

#### Basic 

Those attributes are readOnly, you can update them on the [Networks page](https://bookstack.soffid.com/books/soffid-3-reference-guide/page/networks "Networks").

- **Name**: network name.
- **Description**: a brief description.
- **IP Address**: IP range of this network.
- **IP address mask**: IP mask of this network.
- **IP ranges to analyze**: allows you to set the range of IPs to scan

<details id="bkmrk-%F0%9F%92%BB-image"><summary>💻 Image</summary>

[![image-1705573373643.png](https://bookstack.soffid.com/uploads/images/gallery/2024-01/scaled-1680-/image-1705573373643.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-01/image-1705573373643.png)

</details>#### Server

- **Server**: list of available sync servers.

#### Accounts to probe

- **Accounts to probe:** list of potential administrators accounts to connect to the hosts. You can register a new account or use an existing account. 
    - **Register new account**: you need to define the login name and the password of the new account. 
        - Login name
        - Password
        - SSH key

<details id="bkmrk-%F0%9F%92%BB-image-0"><summary>💻 Image</summary>

[![image-1717596387528.png](https://bookstack.soffid.com/uploads/images/gallery/2024-06/scaled-1680-/image-1717596387528.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-06/image-1717596387528.png)

</details>- **Use an existing account**: you need to select an existing account on the system.

<details id="bkmrk-%F0%9F%92%BB-image-1"><summary>💻 Image</summary>

[![image-1717596556925.png](https://bookstack.soffid.com/uploads/images/gallery/2024-06/scaled-1680-/image-1717596556925.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-06/image-1717596556925.png)

</details>When you register a new account, that will be created as an unmanaged account.

#### Schedule

- **Enabled**: if it is selected (value is Yes), a task will be created and performed on schedule defined.
- **Task description**: a brief description of the task
- **Month**: number of the month (1-12) when the task will be performed.
- **Day**: number of the day (1-31) when the task will be performed.
- **Hour**: hour (0-23) when the task will be performed.
- **Minute**: minute (0-59) when the task will be performed.
- **Day of week**: number of the day (0-7 where 0 means Sunday) of the week when the task will be performed.
- **Server**: you must select the sync server where the agent will be run.

For each value of month, day, hour, minute, or day of the week:

- \* means any month, day, hour, minute, or day of the week. e.g. \*/5 to schedule every five minutes.
- A single number specifies that unit value: 3
- Some comma separated numbers: 1,3,5,7
- A range of values: 1-5

#### Current execution

- **Start now**: this allows you to launch the task execution.

#### Last execution

- **Status**: The available status for a task is: 
    - Done (green light): task finished.
    - Pending (yellow light): the task has been started but it has not finished yet.
    - Error (red light): task could not be executed.
- **Start date**: start date and time of the last execution.
- **End date**: end date and time of the last execution.
- **Execution log**: log trace. Allows you to download the log file.

#### Previous executions

List the information about the previous executions:

- **Start date**: start date and time of the execution.
- **Status**: status of the execution.
- **Execution**: log of the execution. Allows you to download the log file.

### Machine attributes

By clicking the machine record, you can check the following information:

- **Name**
- **IP Address**
- **Description**
- **Operating system**
- **Port /Protocol List**: 
    - Port
    - Description

<details id="bkmrk-%F0%9F%92%BB-image-2"><summary>💻 Image</summary>

[![image-1705661256378.png](https://bookstack.soffid.com/uploads/images/gallery/2024-01/scaled-1680-/image-1705661256378.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-01/image-1705661256378.png)

</details>#### Machine details

If you display the contents of a machine from which the information has been obtained, you could check and manage information about:

- Protected services per account
- Account repositories
- Entry points

<p class="callout warning">It may be necessary to perform the **Reconciliation process of the proper agent** in order to obtain the information from the Account protected services</p>

<details id="bkmrk-%F0%9F%92%BB-image-3"><summary>💻 Image</summary>

[![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-11/scaled-1680-/8Av8doZFXuSr6a3W-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-11/8Av8doZFXuSr6a3W-image.png)

</details>## Actions

#### Network discovery query

<table border="1" id="bkmrk-apply-changes-allows"><tbody><tr><td style="width: 138px;">**Add new account repository**</td><td style="width: 670px;">Allows you to create a new agent.

You must select the System type and the login name and password. When the agent is created, if the connection is successful, the reconciliation process will be executed.

<details><summary>💻 Image</summary>

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

</details></td></tr><tr><td style="width: 138px;">**Agent definition**

</td><td style="width: 670px;">Allows you to browse to the agent definition.

</td></tr><tr><td style="width: 138px;">**Accounts**

</td><td style="width: 670px;">Allows you to browse the accounts page and the accounts, which belong to this system, will be displayed

</td></tr><tr><td style="width: 138px;">**Add new entry point**

</td><td style="width: 670px;">Allows you to create a new entry point.

You must select the Entry point type and the pale to locate it. Once the entry point is created, you can connect to the target system. Bear in mind, that if you need to create an account to connect, when you set the password to this account, the system (agent) must be in No ReadOnly mode.

<details><summary>💻 Image</summary>

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

</details></td></tr><tr><td style="width: 138px;">**Entry point definition**

</td><td style="width: 670px;">Allows you to browse to the entry point definition.

</td></tr></tbody></table>

#### Network discovery detail

<table id="bkmrk-apply-changes-allows-0"><tbody><tr><td style="width: 142px;">**Apply changes**

</td><td style="width: 667px;">Allows you to save the data of network detail. To save the data it will be mandatory to fill in the required fields.

</td></tr><tr><td style="width: 142px;">**Undo**

</td><td style="width: 667px;">Allows you to undo any changes made.

</td></tr></tbody></table>

##### Accounts to probe

<table border="1" id="bkmrk-add-allows-you-to-ad"><tbody><tr><td style="width: 131.984px;">**Add**</td><td style="width: 677.016px;">Allows you to add a new administrator potential account to connect to the machines of the network. To add a new account, first of all, you need to click the add button (+) and close the accounts to probe list. Then you will need to choose if you want to add an existing account or register a new account.

save the data of a new network or update the data of a specific network. To save the data it will be mandatory to fill in the required fields

</td></tr><tr><td style="width: 131.984px;">**Delete**

</td><td style="width: 677.016px;">Allows you to delete one or more accounts of the accounts to probe. You need to select one or more records and next click the button with the subtraction symbol (-).

</td></tr></tbody></table>

#### Schedule 

<table id="bkmrk-start-now-allows-you" style="width: 813px;"><tbody><tr><td style="width: 133px;">**Start now**

</td><td style="width: 680px;">Allows you to launch the task execution.

</td></tr></tbody></table>

#### Previous execution

<table border="1" id="bkmrk-%C2%A0-%C2%A0-%C2%A0-%C2%A0-apply-change"><tbody><tr><td style="width: 126.984px;"> **Logs**

</td><td style="width: 681.016px;">Allows you to download the log files of previous executions.

</td></tr></tbody></table>

#### Machine

<table border="1" id="bkmrk-%C2%A0delete-allows-you-t"><tbody><tr><td style="width: 126.984px;"> **Delete**

</td><td style="width: 681.016px;">Allows you to delete the machine and the PAM connectors for the device. Soffid will display a message to confirm the deletion process.

</td></tr></tbody></table>