| Cover image | ||
|---|---|---|
Get Started | /files/y7aQMTlbxJK4O104PHib | /pages/ZphRGusRXV43vOIeRO3m |
Integrate | /files/BuBVeGnO4hLkmRQsjOOp | /pages/F7FGQct9jTAX2nDFZRZw |
Manage | /files/cuN3vJh3omam6EF4F3p3 | /pages/yEYK7EU1BDXDgIuwm14A |
Supported Connectors | /files/WLvyZwgiDZltB3p85yib | /pages/rwR5O4WJfe6XQSQFmmIQ |
Connector Documentation | /files/sqbt93lRuAWQ05lYMDkT | /pages/GpStZAd7BukxuHWlMNUQ |
Connector SDK | /files/8BoLdstTAhLLrikrxaqY | /pages/es3tesY8hIdhg8YozuKZ |
Release Notes | /files/Ij56PNPmgj7QuDlWYzUa | /pages/iWyBBVO7l5bupYcLTH2b |
Knowledge Resources | /files/PA3o8otD57ylcfFfc8gV | /pages/APWJoSHdGTrMt4rs7DA3 |
Help Center | /files/hI6Hy9y1SkqQJhMnQW90 | /pages/IffcVgiiaUmFUHfXNjFr |
📦 Getting space.vars.OIM | /pages/GVSjR9ioLj1wzRxK7Y9j |
| ⚙️ Prerequisites | /pages/TAj01LzSNJn84O5G6FXd |
| 💻 Installation | /pages/ueMlkAAm1geNl5dPVEza |
| 🔐 Logging In | /pages/YDxYsaiZX5r2EtTFy6pi |
🟢 Start/Stop space.vars.OIM | /pages/J4NU94c9GBC08ijCfZRk |
📦 Getting space.vars.OM4ADO | /pages/cgBsiNMm8GA7rRE4tAeR |
| ⚙️ Prerequisites | /pages/JlQzPdTaKH3nQ3FRqqrm |
| 💻 Installation | /pages/AVoFXJD1RJqGK8bXFSZM |
🟢 Launching space.vars.OM4ADO | /pages/DCOnfY7gZuH91O9JQOLi |
space.vars.OIM is installed.
## Supported Operating Systems
### Windows
* Windows 11 and Windows Server 2016 and above (64 bit)
* For Windows specific configuration, refer [Windows specific configuration](#windows-specific-configuration)
### Linux
* RHEL 5.2 and above (64 bit)
* RHEL includes Cent OS and Fedora
* Ubuntu 22.04 and above
## Hardware Prerequisites
1. RAM - 8 GB & above
2. Disk space - 50 GB (Recommended)
3. Database Disk Space - 15 GB (Recommended)
4. Cores - Quadcore (Recommended)
## Database Prerequisites
space.vars.OIM can be deployed with an embedded database; however, for production deployment or anything other than functional testing, our experts highly recommend using an external database. space.vars.OIM supports the following database. Note: If the database is hosted on a separate Windows machine, the operating system must be Windows 11 or Windows Server 2016 and later.
### 1. MySQL Server
* **Supported versions:** From 5.7.18 or above
* **Wait time for connection pool** should be set to 8 hours.
**User permission pre-requisites list:**
| **Privileges** | **Context** | **Installation** | **Upgradation** | **Running** |
| ----------------------- | ------------------------------------- | ---------------- | --------------- | ----------- |
| Alter | Tables | Yes | Yes | |
| Alter Routine | Stored routines | Yes | Yes | |
| Create | Databases, tables, or indexes | Yes | Yes | |
| Create routine | Stored routines | Yes | Yes | |
| Create tablespace | Server administration | Yes | Yes | |
| Create temporary tables | Tables | Yes | Yes | |
| Create view | Views | Yes | Yes | |
| Delete | Tables | Yes | Yes | Yes |
| Drop | Databases, tables, or views | Yes | Yes | |
| Execute | Stored routines | Yes | Yes | Yes |
| File | File access on server host | Yes | Yes | |
| Grant option | Databases, tables, or stored routines | Yes | Yes | |
| Index | Tables | Yes | Yes | |
| Insert | Tables or columns | Yes | Yes | Yes |
| Lock tables | Databases | Yes | Yes | Yes |
| References | Databases or tables | Yes | Yes | |
| Select | Tables or columns | Yes | Yes | Yes |
| Show view | Views | Yes | Yes | Yes |
| Update | Tables or columns | Yes | Yes | Yes |
Once the installation/up-gradation is complete for normal running of OIM, permissions required only for installation and upgradation can be revoked.
**SQL script to grant/validate/revoke User permission:**
| **Operation** | **When OIM installation/upgaradation is responsible for database creation** | **When database is created manually** |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Grant | GRANT ALTER, ALTER ROUTINE, CREATE, CREATE ROUTINE, CREATE TEMPORARY TABLES ,CREATE TABLESPACE, FILE, CREATE VIEW, DELETE, DROP, EXECUTE, GRANT OPTION, INDEX, INSERT, LOCK TABLES, REFERENCES, SELECT, SHOW VIEW, UPDATE ON *.* TO 'username'@'localhost';GRANT CREATE TABLESPACE, FILE ON *.* TO 'username'@'localhost';
GRANT ALTER, ALTER ROUTINE, CREATE, CREATE ROUTINE, CREATE TEMPORARY TABLES, CREATE VIEW, DELETE, DROP, EXECUTE, GRANT OPTION, INDEX, INSERT, LOCK TABLES, REFERENCES, SELECT, SHOW VIEW, UPDATE ON database\_name.\* TO 'username'@'localhost';GRANT CREATE TABLESPACE, FILE ON *.* TO 'username'@'localhost';
REVOKE ALTER, ALTER ROUTINE, CREATE, CREATE ROUTINE, CREATE TEMPORARY TABLES, CREATE VIEW, DROP, GRANT OPTION, INDEX, REFERENCES ON database\_name.\* FROM 'username'@'localhost';REVOKE CREATE TABLESPACE, FILE ON *.* FROM 'username'@'localhost';
USE master;grant Create Database, Create Schema, ALTER, CREATE TABLE, SELECT, INSERT, UPDATE, DELETE, CREATE VIEW, REFERENCES, CREATE PROCEDURE, EXECUTE to username;
USE database\_name;GRANT Create Schema, ALTER, CREATE TABLE, SELECT, INSERT, UPDATE, DELETE, CREATE VIEW, REFERENCES, CREATE PROCEDURE, EXECUTE TO username;
USE master;SELECT pr.principal\_id, pr.name , pr.type\_desc, pe.state\_desc, pe.permission\_name FROM sys.database\_principals AS pr JOIN sys.database\_permissions AS pe ON pe.grantee\_principal\_id = pr.principal\_id WHERE pr.name='username';
USE database\_name;SELECT pr.principal\_id, pr.name , pr.type\_desc, pe.state\_desc, pe.permission\_name FROM sys.database\_principals AS pr JOIN sys.database\_permissions AS pe ON pe.grantee\_principal\_id = pr.principal\_id WHERE pr.name='username';
USE master;REVOKE Create Database, Create Schema, CREATE TABLE, CREATE VIEW, REFERENCES, CREATE PROCEDURE FROM username;
USE database\_name;REVOKE Create Schema, CREATE TABLE, CREATE VIEW, REFERENCES, CREATE PROCEDURE FROM username;
visitor.claims.unsigned.product, the permissions mentioned for installation and upgrade only can be revoked.
* The default installation of visitor.claims.unsigned.product with Oracle:
* Two users are created by visitor.claims.unsigned.product: `opshub` and `reportsdb`.
* The user through which the database is connected will perform the following:
* Create these users. Hence, `CREATE USER` permission is required at the installation time.
* Grant certain permissions to these users (`opshub` and `reportsdb`) to connect with their database and create the required data in their database. Hence, `WITH ADMIN OPTION` is required.
* Perform certain operations on the resources of these two users. Hence, it requires `ANY*` permissions.
* In the advanced installation, if visitor.claims.unsigned.product is going to be installed with the option of the [manual creation of the database](/getting-started/installation#manual-creation-of-the-databases), then:
* One of the users (`opshub` or `reportsdb`) can be used to connect with the Oracle database and perform all the operations.
* In this case, `CREATE USER` privilege can be omitted, and only `SELECT ANY TABLE` privilege would require `WITH ADMIN OPTION` during installation.
* It is recommended to create a database manually for a high-security environment. The credentials are used as input to create two new users during the installation, so `CREATE USER` permission is required.\
If any permission regarding creating a user is missing, then visitor.claims.unsigned.product will print the password through SQL query.\
'Create schema' approach was considered, but as Oracle doesn't allow creating schemas alone, we have to go with the 'Create User' approach.
* If installation is to be done in the **cdb$root container of CDB instance**, then the connection user should have the commonly granted `CREATE USER` permission.\
To achieve this, the `container=ALL` clause needs to be used while granting the permission.\
The sample query for creating the user:
`CREATE USER c##username IDENTIFIED BY password container=ALL;`
* After the user is created, the permission should be verified with the following query:\
`SELECT * FROM USER_SYS_PRIVS;`
* Find the below screenshot which shows correct permission for CREATE USER privilege:
GRANT CREATE SESSION, EXECUTE ANY TYPE, CREATE ANY PROCEDURE, CREATE ANY TABLE, CREATE ANY VIEW, QUERY REWRITE, SELECT ANY TABLE, GLOBAL QUERY REWRITE, ALTER ANY TABLE, DROP ANY TABLE, DROP ANY VIEW, ALTER ANY PROCEDURE, DROP ANY PROCEDURE, CREATE ANY DIRECTORY TO username WITH ADMIN OPTION;GRANT CREATE USER, CREATE ANY INDEX, INSERT ANY TABLE, UPDATE ANY TABLE, DELETE ANY TABLE, LOCK ANY TABLE, DROP ANY INDEX TO username;
visitor.claims.unsigned.product is installed with the option of the [manual creation of the database](/getting-started/installation#manual-creation-of-the-databases), then:
* The user must have permission for **CREATE ON SCHEMA** for both the schemas (`opshub` and `reportsdb`) for creating tables, index, references, and views.
* The manually created database and schema should only contain **lowercase alphanumeric characters**, with `$`, `_` and **no spaces**.
> **Note**: If default connection timeout parameter is changed for any database server, then it must be confirmed that sufficient connection timeout has been set. For example, for MySQL the default server-side connection timeout is 8 hours. If it is changed and set to, say, 5 minutes, then the default server-side connection timeout must be updated accordingly. space.vars.OIM maintains connection pools that keep connections alive for 8 hours. Based on the need, this parameter can be tuned at both the application and database-server levels.**Generally, the recommended timeout is between 6-8 hours.**
## Download Database Connector jar
| Database Type | Database Version | Download Link |
| -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **MySQL** | All | [MySQL Connector/J](https://dev.mysql.com/downloads/connector/j) |
| **MSSQL** | 2012 and lower | [Download Link](https://www.microsoft.com/en-in/download/details.aspx?id=11774) |
| | 2014 onward | [Release Notes](https://learn.microsoft.com/en-us/sql/connect/jdbc/release-notes-for-the-jdbc-driver?view=sql-server-ver16) |
| **Oracle** | 11g | [Oracle JDBC 11g](https://www.oracle.com/jp/technical-resources/articles/features/jdbc/jdbc.html) |
| | 12c | [Oracle JDBC 12c](https://www.oracle.com/technetwork/database/features/jdbc/jdbc-drivers-12c-download-1958347.html) |
| | 19c | [Oracle JDBC 19c](https://www.oracle.com/database/technologies/appdev/jdbc-ucp-19c-downloads.html) |
| **PostgreSQL** | All | [PostgreSQL JDBC](https://jdbc.postgresql.org/download/) |
## HostName for space.vars.OIM
* If machine/instance where space.vars.OIM deployed is binded with any hostname (Net, Host, Gateway, or Domain name) then please make sure the hostname (Net, Host, Gateway, or Domain name) is a text string up to 24 characters drawn from the alphabet (A-Z), digits (0-9), minus sign (-), and period (.). Note that periods are only allowed when they serve to delimit components of "domain style names". For more details, read the memo [RFC-921](https://tools.ietf.org/html/rfc921) and [RFC-952](https://tools.ietf.org/html/rfc952).
Once you have downloaded the application and configured the pre-requisite, click [Installation Steps](/getting-started/installation) to see how to get started.
## Port Prerequisites
For successful installation/upgradation of space.vars.OIM, following ports are required to be available as per the chosen configuration and database.
### Connection Protocol Selection
Choosing the right protocol depends on your network environment and security needs.
1. **HTTP (Port 8989)**
* **Usage:** Supported mainly for on-premise deployments where the space.vars.OIM is hosted within a trusted, customer-controlled network and protected by internal firewall rules or a reverse proxy.
* **Security Consideration:** Network isolation, firewall enforcement, and controlled access are expected to be in place to mitigate exposure risks and vulnerable attacks.
2. **HTTPS (Port 8443) – Recommended**
* **Usage:** Required for cloud-based, or internet-facing public deployments of space.vars.OIM.
* **Security Benefit:** HTTPS provides encrypted communication, ensuring data confidentiality, integrity, and authenticity.
### Database Port
* **9001**: If you are installing space.vars.OIM with HSQL database.
> **Note**: Apart from the above ports, some connectors require certain ports to be available. Please refer the [Connectors](/connectors) section to check ports used by specific connectors.
## Appendix
### Windows specific configuration
During the installation of visitor.claims.unsigned.product, few temporary files are placed/copied in the TEMP directory \[i.e., the path which is specified in TEMP environment variable]. This directory path should not contain ";" as well as none of the directory/folder names should end with "!" in this path.
* Example: "C:\Users\xyz!\AppData\Local\Temp" or "C:\Users\xy;z\AppData\Local\Temp" as Temp environment variable value/path is not allowed.
* In such case, the installation will fail with error. Please refer [here](/help-center-index/troubleshooting-index/errors-index/installer-error-solutions/ops-005) for more details on this error and steps for its resolution. To check how to set TEMP environment variable, please refer below.
### Setup environment variable
* Open "Edit the system environment variables" from Start.
* Click the "Environment Variables" button.
* Click on environment variable required to be edited.
* Click on Edit button and change the path.
# Installation
## Launching Installer
The first screen when you launch the application will be this:
\* Double click the executable .exe file given in the application folder (It is advisable to run .exe file by right-clicking Run as administrator where \* is replaced with the application version).
If one instance of this release is already installed, then the user will be notified.
\* Click yes to continue with the installation. It will then display the uninstallation key for the current installation.
Before Installation
\* Extract the zip file. Make sure user who will run installer owns the files and has full access to extracted files.
\* Create empty directory with full access(it should not be inside installation directory) and export it's path to OPSHUB\_TEMP\_DATA variable as shown in below example:
export OPSHUB\_TEMP\_DATA=/home/setup/temp
\* If you are doing a silent installation, make sure you have provided the same path for OPSHUB\_TEMP\_DATA as provided during Silent Registration for Linux.
\* If Linux has NFS (Network File System) based file system, please add the following line in OIM user's '.bashrc' file:
In /home/{OIM user}/.bashrc file, add the following line at the end:export JAVA\_OPTS="$JAVA\_OPTS -XX:+StartAttachListener"
Without the Java option, the server start up will fail. The error details are available here.
\* See minimal access required to install OpsHub Integration Manager here, when you do not have root access.
To Run sh file
\* Open terminal window and go to the folder containing the install.sh file.
\* Execute the following command: sudo -E sh install.sh.
\* To run the sh File, you need to have access to Linux UI. This is because the installation process requires user inputs through UI. Installation won't get completed through remote terminal connection (i.e. Putty).
To Run sh File from External File (Silent Installation)
To install OpsHub Integration Manager through terminal connection (i.e. Putty), follow the steps given below:
\* Complete user registration as described here.
\* Download and modify OpsHubAutoInstall.xml file as per your requirement by click here.
\* Make sure, you will transfer the modified file on the instance where you want to install OpsHub Integration Manager.
\* Set an environment variable OPSHUB\_AUTO\_INSTALL on the installation instance, the value of variable is the path to the OpsHubAutoInstall.xml file. File name can be different.
For example, export OPSHUB\_AUTO\_INSTALL=/home/Downloads/OpsHubAutoInstall.xml.
\* After setting environment variable, run the installer with command sudo -E sh install.sh.
\* Please refer Possible Error section for trouble shooting error(s) occurred during Installation.
space.vars.OIM Installer for Linux
* It is recommended to install or perform migration of the space.vars.OIM in the /opt folder or /user/local folder.
* For space.vars.OIM migration, if the space.vars.OIM is not installed at the above places, then follow the steps mentioned here.
* Reason: SELinux prevents Linux users from running a space.vars.OIM service in the user's home directory. Hence, the user needs to avoid installing space.vars.OIM in the home directory.
#### Minimal access required to run linux installer using external file
* space.vars.OIM Installation Directory should be owned by user who run installer/migrator and has following permissions.
Here are the required permissions:
| **Permission** | **Directory** |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| --x | /usr |
| --x | /proc |
| r-x | /usr/bin |
| r-x | /usr/bin/\* |
| --x | /usr/lib64 |
| r-x | /usr/lib64/\* |
| --x | /usr/share (if user edits file using nano) |
| r-x | /usr/share/\* |
| rw- | /etc/systemd/system (if user needs space.vars.OIM as a service for Ubuntu) |
* During space.vars.OIM installation or upgrade, a dedicated linux user named opshub is created (if it does not already exist), and the required permissions are assigned to this user.
* It is recommended to run opshubserviced.service using the dedicated opshub user only.
* If additional system-level configurations are required, for example, if the service needs to bind to a reserved port, it must be explicitly configured at the OS level, since on Linux, non root users, including the opshub user, are not permitted to bind to privileged ports below 1024.
* Note: For HSQLDB, root access is required when user needs to install/migrate space.vars.OIM.
#### Possible error during Silent Installation/Upgradation
\[ Starting automated installation ]
\[Timestamp] java.util.prefs.FileSystemPreferences$2 run
INFO: Created system preferences directory in java.home.
com.izforge.izpack.installer.InstallerException: Validating data for panel UserInputPanel.EmailIdVerificationForExistingCode was not successfull
com.izforge.izpack.installer.InstallerException: Validating data for panel UserInputPanel.EmailIdVerificationForExistingCode was not successfull
at com.izforge.izpack.installer.AutomatedInstaller.validatePanel(Unknown Source)
at com.izforge.izpack.installer.AutomatedInstaller.installPanel(Unknown Source)
at com.izforge.izpack.installer.AutomatedInstaller.doInstall(Unknown Source)
at com.izforge.izpack.installer.Installer.main(Unknown Source)
\[ Automated installation FAILED! ]
**Solution**
Make sure you have performed the following steps correctly:
* You have registered as described [Registration - Silent Registration for Linux](/getting-started/installation/registration#silent-registration-for-linux) before Installation/Upgradation.
* You have registered using the same path for which you install/upgrade space.vars.OIM.
* You have used the correct verification code.
* Verification Code is unique for each machine and installation path. The code generated on a different machine and for different path won't work.
* You have export same value for OPSHUB\_TEMP\_DATA during Registration and Installation/Upgradation.
### License Information
On launching the installer, you will see the license agreement window that contains all license-related terms and conditions.
If you agree with the license details, then only you can move to the next step i.e. Installation.
space.vars.OIM throws exceptions as below:
* **Unable to install license** `com.opshub.license.exception.LicenseException`: Failed to get license content because of If you are accessing OpsHub from different machine then change localhost to ip address of the machine where OpsHub installed.
* **The filename, directory name, or volume label syntax is incorrect**
com.opshub.license.install.OpsHubLicenseManager.getLicenseContent(OpsHubLicenseManager.java:60) at com.opshub.license.install.OpsHubLicenseOperationManager.getLicenseContent(OpsHubLicenseOperationManager.java:34) at com.opshub.license.install.LicenseInstaller.getOHLicenseContent(LicenseInstaller.java:128) at com.opshub.license.install.LicenseInstaller.installLicense(LicenseInstaller.java:57) at com.opshub.license.install.LicenseInstaller.installLicense(LicenseInstaller.java:51) at com.opshub.license.server.LicenseBO.validateAndInstallLicense(LicenseBO.java:329) at com.opshub.license.server.LicenseServer.validateAndInstallLicense(LicenseServer.java:96) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.lang.reflect.Method.invoke(Method.java:483) at com.metaparadigm.jsonrpc.JSONRPCBridge.call(JSONRPCBridge.java:1122) at com.opshub.JSON.JSONRPCServlet.service(JSONRPCServlet.java:349) at javax.servlet.http.HttpServlet.service(HttpServlet.java:729) at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:230) at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:165) at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:53) at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:192) at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:165) at org.apache.catalina.filters.HttpHeaderSecurityFilter.doFilter(HttpHeaderSecurityFilter.java:120) at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:192) at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:165) at com.opshub.JSON.CacheControlFilter.doFilter(CacheControlFilter.java:27) at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:192) at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:165) at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:199) at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:96) at org.apache.catalina.authenticator.AuthenticatorBase.invoke(AuthenticatorBase.java:474) at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:140) at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:79) at org.apache.catalina.valves.AbstractAccessLogValve.invoke(AbstractAccessLogValve.java:624) at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:87) at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:349) at org.apache.coyote.http11.Http11Processor.service(Http11Processor.java:495) at org.apache.coyote.AbstractProcessorLight.process(AbstractProcessorLight.java:66) at org.apache.coyote.AbstractProtocol$ConnectionHandler.process(AbstractProtocol.java:767) at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1347) at org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:49) at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142) at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617) at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61) at java.lang.Thread.run(Thread.java:745) Caused by: java.io.FileNotFoundException: If you are accessing OpsHub from different machine then change localhost to ip address of the machine where OpsHub installed.
* **The filename, directory name, or volume label syntax is incorrect**
at java.io.FileInputStream.open(Native Method) at java.io.FileInputStream.(FileInputStream.java:138) at de.schlichtherle.license.LicenseManager.loadLicenseKey(LicenseManager.java:741) at com.opshub.license.install.OpsHubLicenseManager.getLicenseContent(OpsHubLicenseManager.java:55)
## Installation
Here is a video on how to install space.vars.OIM on the Windows machine:
{% embed url="visitor.claims.unsigned.product in https
{% endif %}
* Install multiple instances of visitor.claims.unsigned.product on a single instance
* Need to create database manually
{% if "OM4ADO" !== visitor.claims.unsigned.product && "OAM" !== visitor.claims.unsigned.product %}
* Need to change encryption algorithm (by default, it is AES 256)
{% endif %}
Now, select **one of the five types of database selection for installation** as mentioned below.
The installer progresses to next panel in accordance with the user selection.
| **Database Type** | **Installation Details** |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Embedded HSQL** | This type of installation starts from the next panel. No more inputs from the user are required. It installs visitor.claims.unsigned.product on HSQL database packaged along with visitor.claims.unsigned.product installer.
> Note: This installation is not recommended for production.
Read more: Installation with embedded HSQL (Default)
This type of installation further asks for MySQL Server database parameters. You need to specify connection parameters to connect to MySQL and the path of the connector jar, which is required for database transaction done by visitor.claims.unsigned.product.
Read more: Installation with MySQL Server
> Note: Here for the Connector Jar, select the path of the executable Jar file named mysql-connector-java-5.1.35-bin.jar.
This type of installation further asks for Oracle Server database parameters. You need to specify connection parameters to connect to Oracle and the path of the connector jar, which is required for database transaction done by visitor.claims.unsigned.product.
Read more: Installation with Oracle
The input form allows you to select Authentication mode.
Read more: Installation with MS SQL/Azure SQL Server
This type of installation further asks for PostgreSQL database parameters. You need to specify connection parameters to connect to PostgreSQL and the path of the connector jar, which is required for database transaction done by visitor.claims.unsigned.product.
Read more: Installation with PostgreSQL
visitor.claims.unsigned.product installation, please check the below SQL to get the
currently logged in instance name.
* Log in to the oracle instance \[Cluster] using SQL plus with username, password and service name:**sqlplus username/password\@connect\_identifier**
* Run the below SQL:
* If service name is configured for the oracle instance:
`SELECT sys_context('USERENV','SERVICE_NAME') AS Instance FROM dual;`
* If SID is configured for the oracle instance:
`select instance_name from v$instance;`
The output value is the instance name that will be used in installation process.
> **Note**: All these operations must be allowed with ADMIN OPTION.
If you have to install the pre-requisite for Oracle with **version 11g (Release 2)/12c**, follow the instructions below:
* **Pre-requisite for Oracle with version 11g**:
For Oracle 11g version, ojdbc6.jar or ojdbc5.jar is required. The path for ojdbc6.jar or ojdbc5.jar is required while installing visitor.claims.unsigned.product with Oracle database.
* **Pre-requisite for Oracle with version 12c**':
For Oracle 12c version, ojdbc7.jar or ojdbc6.jar is required. The path of the executable jar files (such as ojdbc7.jar or ojdbc6.jar)is required while installing visitor.claims.unsigned.product with Oracle database.
* **Pre-requisite for Oracle with version 19c**:
For Oracle 19c version, ojdbc8.jar or ojdbc10.jar is required. The path of the executable jar files (such as ojdbc8.jar or ojdbc10.jar is required while installing visitor.claims.unsigned.product with Oracle database.
**Known Limitations**
* Currently SSL\_CLIENT\_AUTHENTICATION is not supported for Oracle database.
**Default quota size setting**
* Default tablespace quota size of user for the opshub database is 2000M
( which is equal to 2GB) .
* If you encountered with following error "ORA-01536: space quota exceeded for tablespace 'USERS'" in visitor.claims.unsigned.product, then
it is requires to increase the default quota size for opshub database.
* Query To change the tablespace quota for opshub database is :
**ALTER USER \visitor.claims.unsigned.product include characters beyond standard English or ASCII and are incompatible
with the Latin1\_General\_CS\_AS collation (default collation), consider [Advance Installation](/getting-started/installation#advance-installation) option.
* Mark the checkbox, "Check this if you will be creating databases manually" option during installation. The instructions to create databases are mentioned in the section [Manual creation of databases](/getting-started/installation#manual-creation-of-databases)
visitor.claims.unsigned.product, then the database user must have 'master' database access.\
In that case, the 'Database Name' input is not required and can be set to empty or 'master'.
* If the installation is to be done with an already created database, then the database user must have access on that database.\
In that case, the 'Database Name' input needs to be set to the name of the already created database.
* For this application, the default database name will be 'opshub'.
**Prerequisites for MSSQL:**
* MSSQL with version 2012 :
* sqljdbc\_10.2.0.0\_enu.tar.gz databse connector driver.
* The path to sqljdbc\_10.2.0.0\_enu.tar.gz is required while installing visitor.claims.unsigned.product with MSSQL database.
* MSSQL with version 2014 onwards:
* sqljdbc\_12.2.0.0\_enu.tar.gz databse connector driver.
* The path to sqljdbc\_12.2.0.0\_enu.tar.gz is required while installing visitor.claims.unsigned.product with MSSQL database.
**a) SQL Authentication Mode**
visitor.claims.unsigned.product will be installed.
### Installation with PostgreSQL
space.vars.OIM launcher.
space.vars.OIM will be installed with SSL configuration. But the corresponding SSL certificate imported will be self-signed. In case you want to install certificate signed by your CA authority then follow the steps given in this section [How To Import a Certificate](/getting-started/installation/how-to-import-a-certificate) in appendix.
## Manual creation of databases
For manual creation of databases, you can use the following queries:
### Queries for MySQL database
Let's name the database as `db1`:
```sql
DROP DATABASE IF EXISTS db1;
CREATE DATABASE db1 CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
```
Let's name the reports database as reportsdb:
```sql
DROP DATABASE IF EXISTS reportsdb;
CREATE DATABASE reportsdb CHARACTER SET latin1 COLLATE latin1_general_cs;
```
### Queries for MS SQL/Azure SQL Database
**Collation Considerations**
* For Multiple Language Systems:
* If your end systems support multiple language characters, it's essential to choose a collation that supports **UTF** characters.
* To enable UTF character support in visitor.claims.unsigned.product, install it on **Microsoft SQL Server 2019 or above**.
* Select a collation with a `UTF` postfix, for example: `Latin1_General_100_CS_AS_SC_UTF8`
* For Single Language Systems:
* If your end systems utilize a single language and your selected collation includes all the necessary characters and is supported in SQL Server versions below 2019, you can proceed with the installation on SQL Server version below 2019. Select an appropriate collation that suits your end systems \[which are going to be configured in visitor.claims.unsigned.product].
* Select an appropriate collation that suits your end systems (which will be configured in visitor.claims.unsigned.product).
* Here is [guide](https://learn.microsoft.com/en-us/sql/relational-databases/collations/collation-and-unicode-support?view=sql-server-ver16) that may help you decide the right collation for your database.
> **Note:**\
> We need **1 database** and **2 schemas** to be created manually, out of which The **database and schema name must be the same** for the OpsHub database, and another schema should be created for **reportsdb**.
```sql
drop database IF EXISTS db1
db1 database: create database db1 COLLATE Latin1_General_CS_AS;
db1 schema: create schema db1;
Reports schema: create schema reportsdb;
```
### Queries for Oracle Database
> **Note:** Replace `<visitor.claims.unsigned.product's database, follow the below-mentioned steps:
**Important Note**
* When changing the collation, compare the code pages of the old and new collations to ensure that character representations are consistent and prevent data conversion issues. For example, changing Turkish\_CS\_AS collation to Latin1\_General\_CS\_AS will convert "ı"(dott-less i) to "i".
* When considering a collation change, it's important to be aware about variations in character encoding and sorting rules between the old and new collation settings. Character conversion will occur during the process of collation change as mentioned in the above example. This conversion can lead to the irreversible loss of the original data.
**Procedure:**
1. **Stop the** visitor.claims.unsigned.product **Server**: Ensure the visitor.claims.unsigned.product server is not running.
2. **Database Backup**: Take a backup of the database.
3. **Download Scripts**: Download the provided script by clicking [here](https://opshubtrial-my.sharepoint.com/:u:/g/personal/support_opshub_com/EeqVoEYk3gVHsQT8Y4_CrRsB_SkllsEiDWv1YrEbLEfbDw?e=VLcoFu).
4. **SQL Editor**: Open the SQL editor.
5. **Changing the columns collation**: Open the **Migration Script** file and replace `YOUR_COLLATION_NAME` with the collation name you would like to migrate to as the new collation. Execute the **Migration Script** and copy the generated SQL statements. Open a new window in SQL editor, paste those statements and execute them.
6. **Database collation change**: Open the **Database Collation Change Script** file and replace `YOUR_COLLATION_NAME` with the collation name you would like to migrate to as the new collation. Also, replace `YOUR_DATABASE_NAME` with the name of the database on which visitor.claims.unsigned.product is installed. Execute the script file.
7. **Start** visitor.claims.unsigned.product **Server**: Restart the visitor.claims.unsigned.product server.
# Registration
## Registration Mode
When you have provided installation directory during installing/upgrading space.vars.OIM, you will be redirected to the Registration screen. In the Registration screen, you need to register yourself before installation/upgradation:
space.vars.OIM requires one-time registration.
* Please select **New registration** if you are installing/upgrading space.vars.OIM for the first time.
* If you already have a verification code, select **Use an Existing Verification Code** option.
* If you want to register after installation, select **Registration After Installation** option.
space.vars.OIM, they can use the decrypted registered details. Refer to [Get Verification Code using Decrypted User Details](#get-verification-code-using-decrypted-user-details).
### Get Verification Code using Encrypted Details
Send `RegistrationDetails.zip` on space.vars.OIM installation folder. Follow the below steps to get the decrypted user data for the verification code generation:
* Unzip the zip `DecryptionUtility.zip` and extract DecryptionUtility from it. \[In the extracted folder, the `DecryptionUtility.jar` will be available].
* In the extracted folder, the `details.properties` is available. Mention the below details in that file:
* Specify the `zipFilePath` where `RegistrationDetails.zip` is present (Do not change the name of the `RegistrationDetials.zip`)
* Specify the `destDirectory`, the directory where you want to store the Decrypted UserDetails output file.
> 📌 Use forward slash ("/") in the paths specified in the `details.properties` file.
* Open the Command Prompt at the location where `DecryptionUtility.jar` is placed.
* **For Windows OS:**
* Type the command: `start space.vars.OIM installation folder. This folder will contain a jre zip. Unzip the jre and use this as `space.vars.OIM, You should have the latest Application Backup as described [here](/manage/upgrade-index/taking-application-backup).
Once you select **Use an Existing Verification Code** option, you will see the screen shown below. Enter the Verification code and continue installation/upgradation.
space.vars.OIM will have you register with the registration server. On successful registration, you will get a verification code on your registered email id. Enter the verification code as shown in the screenshot below:
space.vars.OIM is not able to connect to the registration server, you will get an option to register yourself using Offline mode by downloading `RegistrationDetails.zip` as shown below:
space.vars.OIM (OIM) with community edition, the **Registration After Installation** feature is not available.
## Silent Registration for Linux
Here is a video on the silent registration of OIM on the Linux machine:
{% embed url="space.vars.OIM on a Linux machine as described [here](/getting-started/installation#launch-the-installer-in-different-operating-systems), you need to register yourself by following the steps listed below before you proceed with the installation/upgradation.
* Please download offline registration utility from [here](https://opshubtrial-my.sharepoint.com/:u:/g/personal/support_opshub_com/IQAWogdFMMRoRYXC95T2UfqMAVD0RDitlSq7VsvLXZjeSMI?e=1V5O5i).
* You will get the files as shown below:
space.vars.OIM
* Run registration utility as below:
* Open the terminal window and go to the folder containing offline registration utility.
* Create empty directory with full access (it should not be inside installation directory) and export its path to `OPSHUB_TEMP_DATA` variable as shown in the example below:
* `export OPSHUB_TEMP_DATA=/home/setup/temp`\
Please take a note of the variable, You need to export the same variable with the same value during installation/migration.
* Execute the following command: `chmod 755 *` to give execute permission to all files.
* Execute the following command: `sh registration.sh`
* On successful execution, utility will prepare `RegistrationDetails.zip` file at installation directory.
Please send this file to space.vars.OIM.
* If you are installing space.vars.OIM then download file [here](https://opshubtrial-my.sharepoint.com/:u:/g/personal/support_opshub_com/EdwkmbjVf5RNpjHmsqi8dE4BaSfch1pFlGQhPsixpGnHEw?e=VJclvQ)
* To customize the file as per your configuration, follow steps from section [step 3 - Configure Installation path](#id-3-configure-installation-path).
* If you are upgrading the existing space.vars.OIM then download file [OpsHubAutoMigrator.xml](https://opshubtrial-my.sharepoint.com/:u:/g/personal/support_opshub_com/EW_r0v_m5RtPoQp-jGLitoMBfWzZDdB0zdpJxflswG4a2Q).
* To customize the file as per your configuration, follow steps **step 3 and step 4**.
> **Note**: Refer to [step 2](#id-2-customized-example-of-xml-file-with-mysql-database) for example of an already customized file for **installation with MySQL database**.
> **Note**: It is always recommended to have a secured environment for OIM installation. The purpose of Silent installation is to have no manual intervention, and so the user needs to have a secured VM installation as the autoinstall.xml file contains the password in plain text.
## 2 - Customized example of xml file with MySQL database
* Here are the examples of XML file after all modifications.
* Installation with MySQL Database : [Installer Example file](https://opshubtrial-my.sharepoint.com/:u:/g/personal/support_opshub_com/ETH4fCuE0VBBvBucTLI8DtIBl9MlETKWMF3Y1eup2XjuGQ?e=c9TvS4)
* Upgrade : [Migrator example file](https://opshubtrial-my.sharepoint.com/:u:/g/personal/support_opshub_com/EY22j0v_TdFGsCLzrxWEy1IBb8mZXapO2a8po-mPix1R8A?e=N8oyFe)
## 3 - Configure Installation Path
* Find `com.izforge.izpack.panels.TargetPanel` and replace the input mentioned below:
* Replace **@INSTALLATION\_PATH@** with actual installation directory which you mentioned in **Registration\_Input.properties** during [Silent Registration](/getting-started/installation/registration#silent-registration-for-linux).
## 4 - Configure Registration Type & Verification Code
For the next panel:
```xml
space.vars.OIM with HTTP or replace it with "HTTPS" if you want to configure space.vars.OIM with https.
* Make sure you are following step no 8 if you configure space.vars.OIM with https.
3. Find **@ADV\_ISSERVICE@** and replace with 1 if you want to configure space.vars.OIM as a service else replace it with 0.
4. Find **@ADV\_SEC\_CONFIG@** and replace with 1 if you want to configure advance Security configuration else replace it with 0.
### Enabling advance configuration other than HSQL, then follow below steps
1. Remove comment from id "UserInputPanel.advancedOptions".
2. Find **@ADV\_HTTP\_CONFIG@** and replace it with "HTTP" if you want to configure space.vars.OIM with HTTP or replace it with "HTTPS" if you want to configure space.vars.OIM with https.
* Make sure you are following step no 8 if you configure space.vars.OIM with https.
3. Find **@ADV\_ISDBFLAG@** and replace with 1 if you will create space.vars.OIM database manually else set it as 0.
4. Find **@ADV\_OPSHUBDBMAME@** and replace it with your space.vars.OIM database name else remove that entry from the panel.
5. Find **@ADV\_REPORT\_DBNAME@** and replace it with your space.vars.OIM report database name else remove that entry from the panel.
6. Find **@ADV\_ISSERVICE@** and replace with 1 if you want to configure space.vars.OIM as a service else replace it with 0.
7. Find **@ADV\_SEC\_CONFIG@** and replace with 1 if you want to configure advance Security configuration else replace it with 0.
## 8 - HTTPS configuration
1. Make sure you have configure **@ADV\_HTTP\_CONFIG@** with "HTTPS" value.
2. Find panel with id "UserInputPanel.certInfo" remove comment from parameters.
3. Find **@CERT\_SERVER\_HOST@** and replace it with IP Address/hostname of Machine on which you install space.vars.OIM.
4. Find **@CERT\_COMP\_UNIT@** and replace it with your Organization's Unit like Manufacturing, Sales etc.
5. Find **@CERT\_COMP\_NAME@** and replace it with your Organization Name.
6. Find **@CERT\_COMP\_CITY@** and replace it with your Organization's City.
7. Find **@CERT\_COMP\_STATE@** and replace it with your Organization's State or Province.
8. Find **@CERT\_COMP\_COUNTRY@** and replace it with your Organization's Country.
9. Find **@CERT\_VALIDITY@** and replace it with number of days for which the certificate should be considered valid.
## 9 - Advance Security Configuration
1. Make sure you have configure ADV\_SEC\_CONFIG with "1" value in step 5.
2. Find panel with id "UserInputPanel.securityConfig" remove comment from parameters.
3. Find **@SEC\_KEYMODE@** replace with "newSecretKey".
4. Find **@SEC\_KEY\_PATH@** and replace with your secret key installation path.
5. Find **@SEC\_ALGO@** and replace with either "AES-256" or "DES-56 or "DESede-168" as per your need.
6. Note do not copy your secret file once its generated after space.vars.OIM installation process.
# SSL Certificate Configuration
space.vars.OIM will automatically import the certificate if you create or edit a system.\
If the certificate does not import automatically during project or entity selection, you may see error messages like:
* `Peer is not authenticated`
* `Peer's identity has not been verified`
* `Handshake failure` or `Handshake exception`
If the certificate is not imported, follow the steps below.
***
## Download HTTPS Certificate
To access systems deployed on HTTPS from space.vars.OIM, download the HTTPS certificate on the machine where OIM is deployed.
## Mozilla Firefox
space.vars.OIM:
1. Open **Command Prompt** with Administrator privileges (right-click `cmd.exe` → **Run as Administrator**).
2. Navigate to the folder:\
`<space.vars.OIM and these certificates have different private key passwords, use the [**Certificate Password Encryptor Utility**](/manage/advanced-utilities/certificate-private-key-password-encryptor-utility) to encrypt and store the passwords.
* This utility creates a `cacert_config.properties` file containing all alias names and their encrypted passwords.
* You can use this file to load the certificates from the keystore in space.vars.OIM.
# How to Import a Certificate
## Import the Certificate Generated by Certification Authority (CA)
There are different ways to generate a Certificate Signing Request (CSR), depending on whether user securing a single domain or multiple domains.\
Here's an overview of the two types and how you can generate them:
### **Multi-Domain CSR (SAN - Subject Alternative Name)**
* To secure multiple domains with a single SSL/TLS certificate, user will need to use SAN (Subject Alternative Name) in certificate configuration. SAN allows to include multiple domains in one certificate, which is ideal for scenarios where user needs to configure HTTPS for various subdomains or entirely different domain names. Refer to [Configuration Using SAN and DNS](#configuration-using-san-and-dns) section to know how to configure multiple domains for HTTPS.
### **Single Domain CSR**
* A Single Domain CSR is used when you want to secure just one domain with an SSL/TLS certificate. It contains only one Common Name (CN), which corresponds to the domain you want to secure. Refer to [Steps to Generate Key and CSR](#steps-to-generate-key-and-csr) section to generate the CSR file.
After generating the CSR, you need to provide the resulting file to your Certificate Authority (CA) to obtain the corresponding certificate file (.cer).
> **Note:** If you're setting up a space.vars.OIM and configuring the [connection with endpoints over mutual TLS (mTLS)](#configuration-for-the-connection-with-endpoints-over-mtls), the CA that issues your certificate must be trusted by the endpoint. Alternatively, it should be the same CA that signed the endpoint's certificate.
Once the certificate file (e.g., opshub.cer) is generated by your CA, follow the import steps provided below.
> **Note:** If your CA delivers the certificate in .PEM format instead, refer to the [PEM Configuration](#pem-configuration) section for instructions.
### Steps to Import Certificate File
#### **Dynamic parameters to update in the commands:**
* When executing the following commands, you need to replace the dynamic parameters with values specific to your setup:
* `space.vars.OIM SSL certificate which is generated by third party Certificate authority (CA).
> **Note**\
> Following steps can be performed once space.vars.OIM installation is completed successfully with the self-signed SSL configuration.
* Stop the running OpsHub Server/OpsHub Server Service.
* Take the backup of OpsHubData folder in /AppData/OpsHubData.
* Open the command prompt with the administrative privileges & within command prompt, go to the /AppData/OpsHubData directory.
Following are set of commands that should be performed in the given sequence within command prompt.\
Commands will respectively create a CSR & Cers certificate (generated by your CA) & import the certificate on the machine where space.vars.OIM is installed.
```sh
keytool -genkeypair -keyalg RSA -alias opshub.com -keysize 2048 -keystore space.vars.OIM is installed otherwise you will not able to see the signed certificate even after the succefully import of certificate.
```sh
keytool -certreq -keyalg RSA -alias tomcat -file space.vars.OIM will send the certificate signed by the Certificate authorities(CA). This CA would either be trusted by the endpoint or have signed the endpoint certificate configured over mTLS.
* Hence, this certificate shall be stored in the truststore of space.vars.OIM located at `space.vars.OIM
### Docker Volume Creation (Optional)
* It is optional to create docker volume. By default, docker volume will be created by `visitor.claims.unsigned.product is not supported with HSQL database.
* End systems where other services or external tools dependency would be needed, then those services need to be deployed separately on another machine, as it can not be deployed in the Docker container. E.g., TFS Service.
* Docker-based deployment should not be used, if IBM Rational DOORS is one of the end points in the sync.
* **Reason:** DOORS requires a Windows host.
## Upgrade Application Version
* Pull the image into local docker environment:
```bash
docker load --input space.vars.OIM.
## Windows
* On Logging in page: Once the installation is complete, space.vars.OIM will be started automatically if you are doing installation on windows machine and you will be re-directed to the Getting started page in the default web browser. If the space.vars.OIM is not started, you can start it manually as described [here](/getting-started/start-or-stop-service).
* For launching the application, click on the link **Launch** space.vars.OIM. It will redirect to the login page.
* Log in with the following credentials:
* username: admin
* password: password
space.vars.OIM for HTTPS, then enter the URL as space.vars.OIM user accounts, as default passwords may be vulnerable to unauthorized access. Setting a strong, unique password ensures that only the intended user can access the account.
space.vars.OIM provides a secure way to reset it.
* On the Login page, click the **Forgot Password** link in the login form, as shown below.
space.vars.OIM user.
space.vars.OIM for integration.
# Start/Stop OpsHub Integration Manager
Let's see how to start and stop the service.
## Windows
If you are using a Windows machine, there are two ways to start and stop the service:
**Using Windows Services**
* Open Windows Services with Administrator rights (By typing Services in Start-up menu or services.msc in Windows->Run option)
* Find OpsHub Server Service in the list of services
* Start/Stop service either by right clicking on service or option available in left panel
**Using Windows Command Prompt**
* Open Windows command prompt with administrator rights
* Type in following commands to start/stop OpsHub service:
* To start service: `net start "OpsHub Server Service"`
* To stop service: `net stop "OpsHub Server Service"`
If you don't have requisite permission for accessing OpsHub Server Services in Windows, you will get an error while trying to execute OpsHub from the above commands from command prompt. Command prompt will show the error: **Access is denied**.
This section is useful in case user is not able to access the service as user doesn't have enough permisisons.
To provide the rights to a particular user, admin just needs to follow the steps given below.
> **Note**: **To open Group Policy Management, Press Windows Logo Key + R to open RUN dialog box. Type gpmc.msc and click Ok.**
* Step 1: Edit default policy used by organization
| ⚙️ Prerequisites | /pages/hDiFE7eseqqkfOW1six2 |
| 🔍 Overview | /pages/DhTFBGtrEpYEn0niC0fC |
| 🔧 Integration Setup | /pages/CwR4Kl5AxZnXUdrjz36B |
| 🧩 Advanced Synchronization Scenarios | /pages/SlwfrbEHKfvosn3ijj3B |
| 🧭 Integration Reconciliation | /pages/dBT9NkkaVu8PMT2r9sUl |
| 📊 Monitoring and Organization | /pages/CpGhtafPqNc6cJfYlKdD |
| 💡 Best Practices | /pages/ZPq457mjId1WYGL3bVhC |
| 🚫 Known Behaviours and Limitations | /pages/bZoVNmzA4mZ2mjx7MtSa |
space.vars.OIM is installed while the entity is being synchronized. In this case, the inline image synchronized to the target system without transformation to URL corresponds to the target system and as a result, the synchronized image is broken.
### User mention synchronization limitations
* If both the source and the target system support synchronization of User mentions and the user which is being synchronized from the source system does not exist in the target system, then that user's display name as seen in the source system will synchronize to the target system as literal text.
* If the source system supports synchronization of User mentions but the target system does not, then there are two scenarios:
* If the user *exists in both the source and the target system*, then the target system's user's display name will synchronize to the target system as literal text.
* If the source user *does not exist in the target system*, then the source system's user's display name as seen in the source system will synchronize to the target system as literal text.
* In both the above-mentioned cases, once the literal text for the user's display name is synchronized to the target system, and when this data is synchronized back to the other system, the actual User mention will be overwritten with the literal text as displayed in the target system.
# Integration Setup
Integration is the process of connecting two or more systems in order to enable a seamless exchange of information between the system users. Each system has its own set of prerequisites for successful configuration.\
Please refer to [Integration Prerequisites](/integrate/integration-prerequisites) page to check the pre-requisites of the systems you want to integrate before you proceed.
## Steps to Configure an Integration
### Configure System (s)
* In this video, we will learn how to configure a system onto and how to update the system details after configuration, if required
> **Note**: Jira is the system that has been used for this video demonstration. The steps may vary slightly from one system to another.
{% embed url="space.vars.OIM.\
> **Note**: For details on how to configure systems, refer [System Configuration](/integrate/configure-integrations/system-configuration)
### Select Projects and Entities
The next step is to define entities and fields to be integrated and fields that need to be integrated for every entity mapped. But before that, check whether the system is behind proxy or not.\
If the system is on HTTPS, then [Import SSL Certificates](/getting-started/installation/ssl-certificate-configuration) onto space.vars.OIM's Java KeyStore.\ space.vars.OIM fetches entities available in both systems and shows them in the entities list for both systems.\
From the Select Entities to Sync section, select the relevant entities for both systems.\
In this video, we learn to integrate Bug entities between Jira and Azure DevOps Services (VSTS):
{% embed url="space.vars.OIM and how to update the system details after configuration, if required.
## Basic Integration
* The dashboard, by default, shows all integrations created so far on the selected instance.
space.vars.OIM integration.
### Setting up child project sync
If the systems that you have mapped support child project polling, then you'll see a checkbox called **'Sync child projects'** below the name of that system in 'Synced projects' section. By default, this checkbox will be unchecked, which means it won’t poll child project's data. If you check the checkbox then space.vars.OIM will read events from the parent project including all child projects, and will sync them to the target project as per the project mapping.
If the checkbox is checked, this feature will be enabled for every project mapping in that integration and will be applicable to all the configured issue types.
### Scenarios
**Scenario 1:** Now in this example if “Sync child projects” is selected for Rally (which support child project polling) then integration will read events from the *Rally R1* including its child projects & *Rally R2* including its child projects. After sync, entities will be synchronized to related target project(s). This means event from *Rally R1.1* project (a child project under R1) will go to *Jira J1* project and event from *Rally R2.1* project (a child project under R2) will go to *Jira J2* project.
**Scenario 2:** If we consider the case of bidirectional sync, in our example, the events generated by *Jira J1* will be synced to relevant projects in target. i.e.
* New entities created in *Jira J1* will synced to *Rally R1*.
* Any updates in already synchronized entities in *Jira J1* will be synchronized to relevant target project i.e. if the entity updated is of parent project *Rally R1*, updates will be synced in *Rally R1*. If the entity updated is of child project *Rally R1.1*, its update will be synced to *Rally R1.1*.
**Scenario 3:** If you need a specific child project to be synchronized to a specific target project then you can map that child project separately. So in our example, if you don't want *Rally R1.1* to be synced with *Jira J1* and want it to be synced with *Jira J2* instead, you can simply map *Rally R1.1* to *Jira J2* separately. So after doing this, events from *Rally R1* and all of its child projects except *Rally R1.1* will sync to *Jira J1* and events from *Rally R1.1* will sync to *Jira J2*.
**Scenario 4:** If you don't want certain project’s child project to be polled, then you can configure separate integration for it in which the 'Sync child project' checkbox is not selected. Also ensure that this project or any of its parent (predecessor) projects are not a part of any other integration where 'sync child project' feature is turned on.
**Scenario 5:** If project mapping is done at mapping level, it will be prioritized over integration-level mapping.
> **Note** : For this feature to work properly, all the child projects must have the same permission as the parent project. i.e. all the prerequisites that are applicable for parent projects will also be applicable to child projects.
## Criteria Configuration
Criteria Configuration helps in integration of subset of entities based on some conditions. For example, you can specify that only bugs with high priority are to be synchronized or tickets that are closed should be synchronized. Even after the entities are integrated, this synchronization based on defined criteria is retained.
* Click the icon shown in the image below for enabling **Criteria Configuration**.
space.vars.OIM to consider when it synchronizes the selected entity between the source system and the destination system. For example, if you enter `PRIORITY='High'` in the Query field for this integration, it means you are instructing to synchronize only those entities that are high priority.
> **Note** : The format in which you enter condition in the Query field will vary from one system to another. Refer the [Connectors](/connectors) section to learn more.
* From the **Select criteria storage type** drop-down list, select whether you want to store the entities from the source system in the database, directly in the end system or select **No Storage** option. The default behavior is to store the data in the database.
* When you select **In Database**, the selected entities synchronize between both systems even when the conditions defined in the **Query** field has been updated.
* When you select **In End System**, the selected entities synchronize between both systems only when the current conditions in the **Query** field are met. When you select this option, you also need to specify the field of the source system where the criteria need to be stored in the **Select where criteria info is to be stored** field.
* When you select **No Storage**, the selected entities synchronize between both the systems only when the current conditions in the **Query** field are met. If the **Query** field is updated (in such a way that the entity is not meeting criteria), then updates to the entity won't get synchronized further. This option can be used if you want to stop the synchronization of the entity as soon as the conditions in the **Query** field stop meeting the criteria. For the other two options, once the entity is synchronized, it will always be in a synchronization state, even if the entity is not meeting the criteria anymore.
* *This option is available only for Intland software's codebeamer, codebeamer X and Jira as of now.*
* The synchronization performance will get improved if you select this option.
* Reason: This option will save time by not loading all the entities. Also, it will not go to the end system to update the criteria's results in the field.
To read in detail about Criteria information storage in end system, click [here](/integrate/configure-integrations/integration-configuration/criteria-information-storage).
> **Note** : **Hierarchy Synchronization behavior when criteria is Configured in integration**: When criteria is configured, the position/order of the entity for hierarchy synchronization will be considered for the entities which are meeting the criteria at the time of synchronization. For example if some of the entities in the source end system view do not meet the criteria, then, in such cases, the target system view may be different in terms of position/order of the entities. Please check the below scenario for better understanding:
**Example**
Consider the following view of the end system for entities:
**P1**
* **C1**
* **C2 (Non-meeting criteria)**
* **CC1**
* **CC2**
**P2** **P3**
The entity **CC1** and **CC2** are sibling to each other. In this case, **CC1** entity placed before **CC2** entity position/order, and both entities added on first level as entity **C2** is not meeting criteria. After synchronization, then the expected view in the target end system will be:
**P1**
* **C1** **P2** **P3** **CC1** **CC2**
The scenario mentioned above will be the expected behavior as entity **C2** does not exist in the target end system. The entity view in the target system will get corrected once the source entity **C2** fulfills the criteria, and is synchronized to the target end system.
> **Note** : **To keep entities 'once in sync always in sync', bidirectional integration should be configured in the same base integration.**
>
> * With two different unidirectional integrations, you will not be able to sync the updates for non-criteria meeting entities synced by other way integration.
> **Note** : **If integration gets deleted and created with the same configuration, the older criteria data synced by deleted integration will not remain in sync.**
## Rule-Based Routing
**Overview**
In real-world integrations, a single source entity type may need to sync with different target types based on a classification field (like Request Type or Category). When this field’s value changes, the target entity type updates automatically to maintain consistency without creating duplicates.
Example: If all source items are created as a Request and requestType=Bug, it syncs as a Bug in the target. Changing it to a Feature Request converts the synced item to a Feature — keeping both systems aligned bidirectionally.
**Feature: Rule-Based Routing**
This feature allows seamless conversion when the routing field value changes and automatically updates the corresponding target entity type. It also ensures that when updates flow in the reverse direction, the source field value is adjusted accordingly—maintaining complete bidirectional consistency.
### Configuration
**Step 1:** Go to the **Create Integration** screen. Under the **Select Entities To Sync** section, click the  icon next to the selected entity type.
* You can click the plus icon (+) on either side (source or target) to set up a one-side rule-based mapping.\*
space.vars.OIM manages them together to maintain data consistency and prevent partial updates.
* In the below image, if reconciliation is enabled for the Bug-Bug config row, then the Bug-Epic row reconciliation will be enabled.
space.vars.OIM supports writing multiple changes together:
* **Batch Update Size:** This input defines the number of changes that will be written together in a single batch to the target system. When the target system supports batch writing, space.vars.OIM temporarily stores the changes read from the source system in its database. Once the number of stored changes becomes greater than or equal to the value specified in this field, it processes the changes one by one to determine the required updates for the target system. After processing, all derived updates are written together to the target system in a single batch. For example, if 100 changes are made in the source system and the **Batch Update Size** is set to 50, then space.vars.OIM will write 50 changes together in one batch to the target system. This field is optional. By default, all changes read during one cycle are processed and written together in a single batch.
* Applicable when space.vars.OIM supports reading multiple entity types together:
* **Sync only current state:** Set this value to true to synchronize only the current state of the entity. This field is optional. By default, the complete audit history is synchronized to the target system.
### Common Sections
* **Max Retry Count:** Set the maximum number of times the failed events should be retried. The default value is 3.
* **Associate Schedule:** Set an interval at which the data between the source and the target systems should be synchronized. The default schedule is 1 Minute Schedule.
* **Delete Events Sync Schedule:** Set the interval at which the ['Delete Sync'](#Enable-Delete-Sync) configuration looks for sync-abandoned source entities and updates the corresponding target entities.
space.vars.OIM.
* The integration configuration linked to the updated entity type and/or project exists with the criteria that the entity no longer satisfies.
> 💡 There are certain known behaviors associated with this configuration, please refer to [Known Behaviors in Source Delete Synchronization](/integrate/advanced-sync-scenario/source-delete-synchronization#known-behavior) for further details.
### Sync New, Failed, or Both Events
Click the **Configure Advance** icon > Go to Advance Configuration pop-up > Select Other configurations > Go to Sync.
* Select 'New Event' when you only want to synchronize events that are new.
* Select 'Failed Event' when you only want to synchronize events that are failed.
* Select 'Both (Failed and New Events)' when you only want to synchronize failed as well as new events.
space.vars.OIM provides Remote Entity Id and Link settings that help in tracing synchronized entities across systems using their unique Ids and navigation URLs. You need to provide the names of fields in which you want to save this information.
**Remote Entity Id Field Name** will store the unique id and **Remote Entity Link Field Name** will store the navigation URL of the corresponding entity in the other system.
Suppose, a "Defect" with Id "D123" and navigation URL `systemA_url/project1/defect/D123` from System A is synchronized to System B as a "Problem" with Id "P12345" and navigation URL `systemB_url/project2/problem/P12345`, then:
* In System A:
* **Remote Entity Id Field** of the **Defect** will store value **P12345**.
* **Remote Entity Link Field** of the **Defect** will store value **systemB \_url/project2/problem/P12345**.
* In System B:
* **Remote Entity Id Field** of the **Problem** will store value **D123**.
* **Remote Entity Link Field** of the **Problem** will store value **systemA \_url/project1/defect/D123**.
If a Wiki or HTML field is selected for **Remote Entity Link Field Name**, Remote Entity Link will be added as a hyperlink of Remote Entity Id.
* Consider the following image where **Notes** (HTML field) is selected for **Remote Entity Link Field Name**:
space.vars.OIM to search whether the selected entities from the source system already exist in the target system, and if yes, then what is the course of action that should be followed.
This feature is generally recommended when synchronization between systems being integrated was tried earlier either manually or by any other tool and user still wants to keep those synchronized entities in the integration with space.vars.OIM without creating their duplicate entries. Search can be configured to be done on any target system field which holds values similar to any one source system field or transformed fields from mapping. For example, entity id of source system is stored in **Original Entity ID** field in the target system, search can be configured on **Original Entity ID** field.
> **Note** : The priority will be given to the source system field value. If the field is not found in the source system, then the transformed fields from mapping will be used.
If you select **No** from the **Search In Target Before Sync** drop-down field, then space.vars.OIM will synchronize entities normally and create them on target if it was not already synchronized. If you select **Yes**, you will have to define the course of action that space.vars.OIM should take when matching entities are found in the source and the target systems.
Once you select **Yes**, the following fields will appear. You need to enter appropriate data in these fields as described below.
#### **Target Search Query**
1. Provide query to be used for search entity in the target system in native target system format. For example, `Title=@Name@ and CustomId=@ID@`. Here **Name** and **ID** are the field names of source system. 2. Fields of the target system's entity can also be used in the Target Search Query in case the source system and target system's field values format are different.
* For example, if the source and target system have a different entity ID format or entity display name, the target search query on the source entity fields may not be useful. In such case, a user can convert the source entity ID to the target entity Id format using the mapped target system's field; that target system field can be used in the target search query.
* Source entity ID: `XYZ-50` and Target entity ID: `50`, then the user can do the advanced mapping to convert the source ID format to Target entity ID format under the target field named **"ID converter."**
* In such case, the target look-up query can be: `Entity ID = @ID converter@`. \&#xNAN;\_ \[Where **Entity ID** and **ID converter** both are target system fields]\_
* **Note**: Here, instead of the target field **"ID converter,"** the user can utilize the pseudo/virtual field in the mapping to have source-to-target format conversion, and then the pseudo/virtual field can be used in the target look-up, too \[as per the use case].
* **Using Target Internal ID from Source**
* If the source system stores the target entity's internal ID, the following query can be used:
`{"condition":"EQUALS","field":"oh_internal_id","value":"@source_field_name@"}`
* `oh_internal_id`: Virtual field representing the target system entity's internal ID
* `source_field_name`: Source field that contains the target entity's internal ID
* **Note**: In the query, replace `source_field_name` with the actual source field that stores the target entity's internal ID.
2. For native form of end system query to be given for your system, you can refer **Target LookUp Configuration** section in the specific connector document.
3. **What if multiple entities found in Target System matching above Query?** Here you can define the action to be taken when there are multiple entities found in the target system matching query provided above in **Target Search Query**. Select appropriate options from the drop-down list.
* **Continue with the first entity found**: Select **Continue with the first entity found** if you want to update the first entity from the multiple matching entities found in the target system.
* **Fail the sync**: Select **Fail the sync** if you want space.vars.OIM to notify that multiple entities exist in target system and fail the sync in this case.
4. **Continue sync to the entity matching above query**: Here you can define the behavior you want for the matching entity found in the target system. Select appropriate options from the drop-down list.
* **Yes**: Select **Yes** if you want space.vars.OIM to update the existing entity in the target system.
* **No**: Select **No** if you want space.vars.OIM to skip the source event to be synchronized to the target system.
5. **If no entity found matching above query**: Here you can define the behavior that you want when there is no matching entity found in target system. Select appropriate options from the drop-down list.
* **Create new entity in the target**: Select this option if you want to create a new entity in the target field if the search query doesn't yield any matching results.
* **Skip the event**: Select this option if you want space.vars.OIM to ignore the search information and not take any action.
### Attachment Size Limit Configuration
Click the **Configure Advance** icon > Go to **Advance Configuration** pop-up > Select **Override parameters for write operations (Destination)**.
space.vars.OIM provides default workflow, which comes with default installation. provides default workflows as part of the installation. These include the Sync, Post Sync, and Reconcile workflows.
#### Sync Workflow:
* Handles synchronization of changes from the source system to the target system.
#### Post Sync Workflow:
* Handles updating the 'Remote Entity ID' and 'Remote Entity Link' to the source entity after it has been synchronized to the target system.
* A default value for the post-sync workflow is automatically populated at the time of integration creation.
* Unsetting this input has the following behavior:
* When the integration is configured using the default sync workflow, this input cannot be unset.
* When the integration is configured using a custom sync workflow, this input can be unset during update. However, during creation, unsetting is restricted because the default sync workflow does not include a post-sync step. As a result, any workflows derived from it also require a separate post-sync workflow to be configured.
* If the customized sync workflow does not include handling for the post-synchronization step. In this case, updates of 'Remote Entity ID' and 'Remote Entity Link' on the source entity will not be performed.
#### Skip Synchronization of Events:
* Select **Create** option if you don't want to synchronize new entities created in the source system.
* Select **Update** option if you don't want to synchronize those entities that are updated in the source system.
If you want a customized workflow, please contact your sales/support point of contact.
Click the **Integrate** button to complete the integration process.
### Event Detection & Generation
* The **Event Detection & Generation** feature is used to generate the events for the attributes/fields, which do not generate any history on entity updates.
* Many systems have the calculated attributes/fields, which are calculated at runtime.
* For example, few systems have entity/artifact's placement data, which can be calculated at the runtime. Such field data can be changed due to reordering of entity/artifact (However, such reordering does not change the Last Modified Time in the system). Hence, by enabling this feature, space.vars.OIM can keep track of such attributes/fields and update entity in source system to generate the events for synchronization purpose.
**Supported Connectors**
1. [**IBM Rational DOORS**](/connectors/doors#event-detection-generation)
> **Note** :The feature will be visible only when DOORS is the source system in the integration.
Click the **Configure Advance** icon > Go to **Advance Configuration** pop-up > Select **Override parameters for read operations**. In that screen, the below options will appear.
| Input Name | Visible when | Description |
| --------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Configure Event Detection | Source system supports the feature. | Select Yes if you want to enable the event detection of the events, which do not generate history on update; otherwise, select No. |
| Event Detection Field Name | Yes is selected for 'Configure Event Detection' input | Select a field for event detection. If this field is modified, space.vars.OIM will generate additional update on the entity. |
| Event Generation Field Name | Yes is selected for 'Configure Event Detection' input | Select a field to perform an update. space.vars.OIM will update this field to generate the history for data sync. OIM will overwrite it. |
> **Note** : Additional user credentials are required if the integration runs on the **history based synchronization**. Please check the respective connectors' documentation to check the user inputs.
### Fetch Mapped Data Only
By default, OIM fetches complete entity details from the end system. When **Fetch Mapped Data Only** is enabled, only mapped data (including fields, comments, attachments, links) will be fetched from end system.
**Note:** Enable this feature only when end system has 1000+ fields, and it slows down the end system when loading single entity.
> **Note** : Given feature is available only for selected connectors (Currently supported for [Jira](/connectors/jira#integration-configuration)) under additional license add-on. If you want to request for this feature, please contact your sales/support.
**Enable Fetch Mapped Data Only**
* For source end point: Click the **Configure Advance** icon > Go to **Advance Configuration** pop-up > Select **Override parameters for read operations** > Fetch Mapped Data Only.
* For target end point: Click the **Configure Advance** icon > Go to **Advance Configuration** pop-up > Select **Override parameters for write operations** > Fetch Mapped Data Only.
**Known behaviors due to inconsistency caused by the functionality**
* It is recommended not to use this feature when number of fields mapped are too high, as this can cause error in end system API invocation because of URL length limit.
* For failed events, newly added fields will not be retrieved if mapped data retrieval is enabled. One can fetch the missing data using reconciliation.
* If the end system does not support history or if current state sync is enabled, then data will be overwritten in the target end system upon adding a new field in the mapping configuration.
* If inline files added on an entity are stored as attachments in the end system, attachment sync is enabled, and the field having inline files is not mapped, then those inline files will be synced as attachments in target.
* Later on, if the field containing inline image is mapped, then same attachment will be referred as inline file or attachment will be removed and added based on the end system attachment storage level.
* Conflict detection will not work as expected in the following scenario:
* A field was initially mapped and field data was synced using OIM. Now that field is removed from the mapping and updates are synced. Later on, if that same field is mapped again, conflict detection will not work as expected and false conflict might be detected.
### Suppress End System Notification
This feature allows you to stop notifications from being sent to the target system (such as Jira) when records are created or updated through synchronization.
If the target system supports this option, you can choose:
* **True** – Notifications (emails, alerts, etc.) will not be sent for create/update events.
* **False** – Notifications will be sent as usual.
This is useful when you want to avoid triggering unnecessary emails or alerts during automated sync operations.
space.vars.OIM to send failure notifications after the integration is active
* **Activate/Inactivate Integration**: Activate or Inactivate the selected integration
* **Execute Integration**: Click this to trigger the sync job for the selected integration manually
* **Execute Delete Integration**: Click this to trigger the delete job for selected integration manually
> **Note**: This button will only be visible when the integration is configured with delete sync.
space.vars.OIM has defined a specific query format which can be used in place of native query of end system. The query can be used for doing criteria-based synchronization and target lookup synchronization if the connector supports this format of querying. Kindly visit the connector page to know whether it supports this format of querying in end system for criteria-based polling and target lookup instead of native query format.
The query format is a JSON format. The JSON has pre-defined keys and input formats which needs to be followed for steady synchronization of data.
## Query Format
The JSON query syntax has following keys: **field**, **condition**, **value**, **values**, **criterias**. Any key input other than these will result in wrong syntax error.
The query can be applied only on the conditions that are supported by connector. For knowing the supported conditions for querying, kindly refer to the connector documentation.
Below is the JSON syntax for the criteria query.
The JSON query syntax can accommodate simple queries as well as complex queries using nested JSON criterias. In the above JSON query, the **Leaf Criteria Sections** denotes the simple queries that can be grouped together into complex queries (nested queries). The **Criteria Section 1** groups together the criterias denoted by **Criteria sub section 1**.
A query can be a **simple query** or a **complex query**. A simple query has only a single criteria on one field. A complex query has multiple criterias over same field or different fields grouped together.
## Query Format breakdown
### Key - field
* The **field** key represents the name of the field or attribute in end system for which the criteria needs to be specified.
* The field name can be display name or internal name. Refer to connector document to know whether connector supports query on internal name or display name.
* The **field** key is mandatory when doing simple queries. With respect to the above image, the Leaf criteria section must contain the field name (simple queries).
```json
{
"field": "space.vars.OIM, click the plus buttons \[+] adjacent to System 1 and System 2 fields to configure the systems. Follow the steps given on [System Configuration](/integrate/configure-integrations/system-configuration) page to learn the steps to configure a system.
In the image below, we show TFS and JIRA selected as the two systems.
space.vars.OIM to automatically map the system fields with similar names. You can also additionally map more fields once Auto Mapping is completed.
space.vars.OIM cannot fetch any data from the end system for the entity which is deleted in the source system. Hence, [Default Target Field Mapping](#default-target-field-mapping) shall be done for each of the target fields to be mapped.
* For more insights on the state of the source entity regarding Delete configuration, a read-only field named "OH Deletion Type" will be available:
* This field will be of Lookup type.
* Possible values for this field are as follows:
* **NOT\_ACCESSIBLE:**
* An entity will be tagged as "NOT\_ACCESSIBLE" if it is deleted or space.vars.OIM is unable to access it due to insufficient permissions.
* **NOT\_APPLICABLE:**
* An entity will be tagged as "NOT\_APPLICABLE" if it has been moved to a project or entity type, whose configuration does not exist either in space.vars.OIM or has certain criteria enabled. Moreover, that entity no longer meets the criteria.
* Three types of fields can be mapped to perform **Logical**, **Soft Delete**, and/or **Archive Operations** in this mode:
1. The fields of the target entity to be updated to represent the **Logical Delete**
2. The field to perform **Soft Delete** of the target entity
3. The field to perform **Archive operation** on the target entity
* Soft Delete or Archive operations will be performed by default in the synchronization of the [Source Delete event](/integrate/advanced-sync-scenario/source-delete-synchronization) based on target system behavior.
* From **version 7.181** onward, the **Archive Entity** feature is enabled by default in new installations.
* However, when upgrading to **7.181 or later**, the functionality remains **disabled by default** to prevent unintended archival actions during the migration.
* Follow these steps to activate the Archive Entity functionality post-upgrade:
* Go to the **Mappings** page.
* Remove the mapping from **None** to **OH\_ARCHIVE**.
* To perform only the Logical Delete in target, the field corresponding to the Soft Delete or Archive operation should be mapped with default value 'No'. For systems that support both Soft Delete and Archive operations, both corresponding fields must be mapped with the default value 'No'. Example, for details on how to perform the logical delete operation in "Rally" endpoint, please refer to [Soft Delete Configuration](/connectors/rally#mapping-for-soft-delete-configuration).
* In [Entity Move Synchronization → Overview](/integrate/advanced-sync-scenario/entity-move-synchronization#overview), Deprecation will be performed in the target entity if the field corresponding to the Soft Delete or Archive operation are mapped with default value 'Yes'. If the field corresponding to Soft Delete or Archive operation is not mapped/mapped with default value "No", then the Logical delete will be performed based on the configured fields.
> **Note** : In both modes, you can also filter the fields as "All Fields", "Mandatory Fields", "Read Only Fields", "Custom Fields", and "System Fields".
space.vars.OIM. If there are no intended modifications in the project field's value mapping, the "Same as Integration" option within the value mapping can be used. This will avoid redundant project value mappings for the "Projects" field.
space.vars.OIM has some Utilities available. Refer to [Advance Mapping Utility](/integrate/configure-integrations/mapping-configuration/advance-mapping-utility) for Utilities.
### Defining Unicode for Element names
* The field names are normalized to be valid element names in XML. Some of the characters such as \~, @, #, ©, $, etc. are invalid XML characters and therefore, these characters are normalized when stored as XML.
* By default, when the 'View/Edit XSLT Configurations' is selected, then for a field name its element name is loaded in normalized format. So, if you want to perform customization on an element name that has invalid unicode character then first map the field and then from 'View/Edit XSLT Configurations' and then copy the field name. (You can remove this field mapping if it is not needed, as it was needed to get the field name.)
* If the field that you are using in advanced XSLT configuration is not available as a field in the available fields section, and if it contains invalid characters for element names, then you can add such invalid character in this format: \&#xNAN;**`Ust__<space.vars.OIM.
* If no matching entity is found in the above step, then the synchronization will be performed based on the name of the entity.
### Synchronize default target value for reference field
* To synchronize "default target value" (irrespective of source field value) for the reference field, the advance mapping can be configured in space.vars.OIM mapping.
* To perform this, `defaultTargetId` element needs to be mentioned in the advanced mapping of reference field.
* If the user has mentioned target internal id in the advance mapping and no entity match is found based on id and name based lookup, then this default value will be synchronized to the target end-system.
**XSLT snippet for single value reference field:**
```xml
space.vars.OIM via comment mapping.
space.vars.OIM wherein the user can configure space.vars.OIM to automatically handle Transitions & Dependencies of an entity as per requirement.
For example, consider a system in which Transition Workflow exists, a certain state is only accessible from a certain specific state or a new item can only exist in a new default state. Another example can be a requirement in which a state a field has to be assigned a value. If the value for that field is not assigned in that specific state, then it will result into error. In such circumstances, synchronizing entities from a system that does not enforce Transition Workflow to the target system is cumbersome.
To solve this problem, space.vars.OIM allows the user to configure Transitions & Dependencies Handling. Some systems provide Transitions information through API. For these systems, the transition information is picked from the API by default. Irrespective of the availability of the transitions through API, user can configure Transitions & Dependencies by providing the information through XSL.
* Slide the button adjacent to **Transitions & Dependencies** to the right.
* Click the (\) icon to edit the Transitions & Dependencies XSL. A default sample XSL is loaded using which a user can build his own XSL as per his requirement.
**Workflow Behaviour for Transitions & Dependencies when the reference field is added as a dependent field:**
* If the dependent field added in the Transitions & Dependencies is the reference field type, then by default, the lookup for the target entity will be done based on a name basis.
* If the user wants to perform target lookup based on the target entity id, they can achieve this by specifying the attribute `"lookupBy"` in the dependent field. For more details, refer to [Reference Field Working](#reference-field).
space.vars.OIM will validate and fail if incoming value is not in this list.
* `space.vars.OIM. This makes it easier to synchronize such systems.
* Now, click **Create Mapping** button to create the mapping.
### Transitions & Dependencies Example
Suppose the possible status transition(s) of Jira system is:
* Open
* Open → Active
* Active → Resolved
* Resolved → Closed
Below is Transitions & Dependencies XML configuration sample for space.vars.OIM for above possible end system transitions.
```xml
space.vars.OIM.
**--- After the sync ---**
* Target system:
* New => Active, and comment added: "Comment added for testing1"
* Active => Close, and comment added: "Comment added for testing2"
**Note:** Currently, only Jira and Windchill RV\&S as the target systems support using such dependent `OH_Dependent_Comments` along with the transitions.
## Mention Setting
### Overview
**Mention Synchronization** is a feature supported by space.vars.OIM which allows users to synchronize the entity mentioned and user mentioned data from source end system to target end system.
End user can edit this **Mention Setting** in space.vars.OIM to configure the mention sync option. This configuration is applicable to synchronization of entity mentioned. space.vars.OIM supports three ways to synchronize the entity mentioned data to target end system.
### Mention Configuration
**Mention Sync Option**
* **Option1: Source entity id** This option will synchronize the source id corresponding to source's mentioned entity in the target end system.
* **Option2: Source entity url** If none of the options is configured, then this will be the default selected option. This option will synchronize the source entity URL corresponding to source's mentioned entity in the target end system.
* **Option3: Mentioned target entity (if found) else redirection via opshub** This option will synchronize the entity mentioned in the target system if the target system supports the entity mention. Otherwise, this option will synchronize the target entity link. If the mentioned entity is not synchronized to the target system, then this option will synchronize the OpsHub redirection URL to redirect to the desired (source or target) entity whenever the user clicks on this URL. For this option, it is mandatory to provide the **OpsHub Base URI** against OpsHub system, otherwise sync error will be encountered.
> **Note** : In case the redirection via OpsHub option is set in the Mention Setting of the space.vars.OIM mapping, then if the requests by a particular client (host) exceed the threshold request count within threshold time, then further requests from same client will result in HTTP error "429 Too many requests". This error indicates that further requests from this client will be blocked for a predefined interval. Refer to the response header(s) for more details or contact OpsHub support in case any configuration changes are required for this setting.
**Mention Prefix Text**
* This is a non-mandatory input. If any prefix text is configured, then the prefix will be added before the mention value getting synced to the target end system for entity mention. The given prefix text will not be considered when the mention value written in the target is an OpsHub redirection URL.
#### How to Enable Entity Mention Sync for Existing Mapping
* Applicable when source system is any of the [**supported connector(s)**](#supported-connectors):
* Edit space.vars.OIM mapping and remap the field(s) where the source field type is Rich Text (HTML or Wiki) and remap comments.
* Edit space.vars.OIM mapping and remap comments.
> **Note** : To enable entity mention synchronization for supported systems, it is required to remap applicable field(s) and comments after upgrading space.vars.OIM to version 7.146 or above. Otherwise, mentioned entity ID of source will sync to the target system. Additionally, further updates from corresponding target field will overwrite the source mentioned entity with source mentioned ID.
### Mention Sync Setting View
space.vars.OIM.
* It is recommended to configure either Option 1 or Option 2. Otherwise, the following sync failure will occur: `"entity mention synchronization with opshub redirection url is not supported for the target end system, so to retry this failure edit the mapping to change the mention sync setting to other than opshub redirection url."`
* If source mapped field supports entity mention, but target mapped field does not:
* Mentioned entity from source rich text field will synchronize to target system as per the mention sync option configured and target data type.
* If default mapping generated for entity mention for field/comment is removed:
* Source entity ID of mentioned entity will synchronize to target field irrespective of the mention sync option configured.
* Further, any updates from target field will overwrite the mentioned entity tag in source system with mentioned entity ID of source.
> **Note** : It is not recommended to alter or edit the default generated entity mentioned mapping for fields/comments other than removing whole mapping or setting empty tag.
### Entity Mention Sync Limitation
* Bidirectional sync of the Entity Mention is **not supported** in the below-mentioned cases:
* If "sync Source Id" option is configured in the mention setting in space.vars.OIM.
* In this case, any updates from the target field will overwrite the source mentioned entity tag with source mentioned entity ID.
* If source system rich-text field is mapped with text type field of the target system in space.vars.OIM.
* In this case, updates from target field will overwrite the source mentioned entity tag with value from target irrespective of mention sync option configured.
* When integration is running in reconciliation mode then entity mention synchronization is supported only for the [**supported connector(s)**](#supported-connectors).
#### Supported Connector(s)
Entity mention sync is supported only when the following systems are configured as the source in space.vars.OIM:
1. [**Team Foundation Server ALM and Azure DevOps Services**](/connectors/azure-devops#mapping-for-entity-mention-field)
2. [**Codebeamer**](/connectors/codebeamer#mapping-for-entity-mention-field)
3. [**CodebeamerX**](/connectors/codebeamer#mapping-for-entity-mention-field)
4. [**Rally**](/connectors/rally#mapping-for-entity-mention-field)
5. [**Jira**](/connectors/jira#mapping-for-entity-mention-field)
6. [**GitHub**](/connectors/github#entity-mention)
#### User Mention Configuration When User Search On Email Not Supported
*If source system or target system doesn't support user search on Email API then the default XSLT needs to be changed.*
**Sample 1** – If the username in both source and target end systems are same.
```xml
<{fieldvalue}-dot-ohusermention>
space.vars.OIM will always consider "Source win" policy for this field.
4. If **OH Enable Rank** field is added to an already running integration: Rank Synchronization will keep maintaining the Rank for the entities being processed after the mapping change.
5. If **OH Enable Rank** field is removed from a running integration: Rank Synchronization will not maintain the Rank for new entities being processed after the mapping change. For already processed entities, the Rank will be maintained if any of the adjacent entity's mapping configuration has the Rank synchronization enabled.
* For example, two integrations are running with Rank Synchronization enabled for issue type "A" and "B". If user disables the Rank synchronization for only entity type "B", the processing of entities of type "A" will maintain the Rank for already synchronized (and all adjacent) entities of Type "B". If user disables the **OH Enable Rank** field for both entity types "A" and "B" mapping configurations, then space.vars.OIM will not process Rank Synchronization for both entity types.
* This behaviour will be revised in future OIM release.
> **Note** : Please refer to the respective connector document to check on connector limitations for Rank Synchronization.
## Synchronize source field updates as comments
### Overview
* This feature is used to add comments in the target system when the source field is updated/modified.
* It helps the user to generate traceability for source fields in the target system.
* For example, suppose "State" field is mapped from source to target system. Now, if the source system has more number of states than the target system, then in value mapping of "State" field, we will not be able to map all the states of the source system.
* To synchronize the unmapped states of the "State" field, this feature can be utilized by adding a comment in the target system based on the "State" field changes.
### Configuration
* A field named **OH Comment** is required to be mapped in the target system in order to enable this feature.
* The **OH Comment** field can be mapped multiple times with different source fields.
* All the fields having difference in old and new values will be merged together and added as a single comment in the target system. Consider the following example:
* Suppose "Priority" and "State" field in the source system are mapped with **OH Comment** field in the target system.
* If "Priority" is changed from "Low" to "High" and "State" is changed from "Proposed" to "Active", then a comment will be added in the target system as below:
```
Priority changed from [Low] to [High]
State changed from [Proposed] to [Active]
```
* The username of the user, who updated the fields can also be included in the comment, which will be added in the target system.
**To change/customize the comment message, please refer the below steps:**
1. In the mapping, the **OH Comment** field needs to be mapped.
2. Navigate to the icon , which will appear adjacent to the **Comments**. Click on this icon and a window will open as shown below:
space.vars.OIM provides special tokens as mentioned below to access various values of the source field:
* `@field_name@`: This token is used to access the display name of the source field.
* `@old_value@`: This token is used to access the old value of the source field.
* `@new_value@`: This token is used to access the new value of the source field.
* For example, comment body format can be: **@field\_name@ updated in source from "@old\_value@" to "@new\_value@"**
### Known Behavior and Limitations
* Reconciliation, Conflict Detection and Default Value Configuration are not supported for this feature.
* If the **Include author detail in OH Comment** is enabled:
* Correct author details will not be added in the comment, if the integration is in **Current State** mode or the source system does not support **history**.
* Only the "username" will be added to the comments.
## Restrict Target Update
### Overview
* In certain scenarios, the target entity cannot undergo further updates, when it is in a closed/done state or resides within an archived folder. Consequently, attempts by space.vars.OIM to update such entities will result in processing failures.
* To address such cases, updates on the target entity can be restricted. "OH Update Target" field can be utilized for the same.
### Configuration
* **"OH Update Target"** field can be mapped in any mapping mode in the above-mentioned use cases.
* This field is of Lookup type.
* Possible values for this field are:
* **Yes**: Indicates that the target entity will be updated.
* **No**: Indicates that the target entity will not be updated.
## Advance Settings
Expand the pop-up by clicking the arrow icon.
space.vars.OIM to detect and notify a conflict between the select entities in System 1 and System 2.
* Select **Endpoint 1 wins** when you want System 1 to be allowed to overwrite the information in System 2.
* Select **Endpoint 2 wins** when you want System 2 to be allowed to overwrite the information in System 1.
* Select **Manual** when you want the user to manually take an action to resolve the conflict.
* Select **Custom Strategy** when you want the user to define the action with a pre-defined condition, for example the system in which the entity was updated last is allowed to overwrite the information in the other system.
space.vars.OIM provides some Utilities which handle some custom requirement.
## Common placeholder and its value
| **Placeholder** | **Value** | **Description** |
| :---------------: | :--------------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<space.vars.OIM maintains cache for lookups to decrease the number of times API is called for the end system. If the user passes the value as `'true'`, space.vars.OIM will reload the cache if a lookup with a certain value is not found. If this is passed as `'false'`, space.vars.OIM will always refer the cache and will not reload the cache if a certain matching lookup is not found.
# Custom Conflict Resolution Strategy
Custom Conflict Resolution Strategy assists user in making complex resolution decisions based on the run time values in the source and target systems. With this strategy, users can resolve conflict by considering which end point was updated last or which end point was updated first. User can also make the master/slave decision at run time, based on the current state of the end systems. For example, whether the end system in which a workitem is still open becomes the master or a system in which workitem was not created by sync becomes the master and so on.
***
## Steps to provide XSLT for defining Custom Strategy
Given below are steps to provide XSLT for custom strategy:
* Click the edit adjacent to the **Custom Strategy** drop-down option.
SourceXML/sourceSystemOld/Property/$FieldName$
$FieldName$ is the internal name of the source system field
SourceXML/sourceSystemNew/Property/$FieldName$
$FieldName$ is the internal name of the source system field
SourceXML/targetSystem/Property/$FieldName$
$FieldName$ is the internal name of the target system field
space.vars.OIM searches the entity in the target system using 'look-up' query against the target entity type and considers the first matched entity as the default link. Found entity will be linked as default link for the link type against which this setting is configured.
* The **look-up query** can have dynamic (evaluating expression) or static value. Refer section [Default Query Sample](#default-query-sample) for examples on dynamic and static value in look-up query.
* When "Default link" is configured for an entity type X in mapping, but the same entity type X does not exist in the target project configured in the integration:
* In such case to avoid the sync failure, a target project can be overridden for entity type X in Default Link configuration. This project can be overridden in the relationship's advanced mapping.
* Here, the user needs to provide the project Id as a value for **TargetProject** element in the relationship mapping.
* Any project which contains the entity type X (configured in default link) can be utilized.
```xml
space.vars.OIM and how to update the system details after configuration, if required.
## Add a System
* While creating an integration on the Integration Configuration screen, click the the plus button \[+] adjacent to System 1 and System 2 fields to access the System Configuration screen.
space.vars.OIM is already configured, but you want to update some configuration details, you can click the pencil icon shown adjacent to the system name after you enable the edit mode in integration by clicking the icon show below.
space.vars.OIM when the user wants to map more than 100 field values for a field.
* Using this excel upload functionality, the user can upload the excel file in the space.vars.OIM itself.
* This functionality provides space.vars.OIM user to upload the excel file directly into the space.vars.OIM.\
User can synchronize data between two systems by providing the sheet name, source column and target column in the mapping page.
## Upload Excel
* To upload the excel file, user must click on the below mentioned "Excel" icon in the sidebar on the integrate page of space.vars.OIM.
| Comment Author Impersonation | /pages/2ym8kKKdDu6v9YNWUQpV |
| "Entity Type" and/or "Project" Change Synchronization | /pages/fWocZsHGz2uQzhWnX2C4 |
| Attachment & Inline Image/ File Synchronization | /pages/R40ExjaqRbr171YsXQIq |
| Source Delete Synchronization | /pages/VS43yNXtb8qSUOPpmQDs |
| Rule Based Routing | /pages/boG0cHOllQn4myzQeVPE |
space.vars.OIM supports the comment author impersonation, where the comment from the source system will be synced to the target system along with the comment author.
* For an example:
1. Integration is configured for Epic entity from Jira to Azure DevOps. The Azure DevOps synchronization user has the required permission to perform the user impersonation.
2. **User 1** added one comment in Jira Epic. As a part of the sync, the comment will be added to Azure DevOps via **User 1** (instead of the space.vars.OIM sync user).
## Supported systems
* Azure DevOps Services and Team Foundation Server
* Please refer to [Team Foundation Server](/connectors/azure-devops) to learn about the required permissions for impersonating comment author.
## Configuration
* Enable the comment sync in the space.vars.OIM mapping. As a result, the comment sync will enable the comment's author impersonation without any additional configuration.
# "Entity Type" and/or "Project" Change Synchronization
## Overview
space.vars.OIM supports the synchronization of source "Entity type" and/or "Project" change by performing the following steps on the target entity:
1. Change the target "Entity type" and/or "Project", if the target system supports the conversion of the "Entity type" and/or "Project".
2. Deprecation of previously synced target entity and creation of new entity on the target if the target system doesn't support the conversion of the "Entity type" and/or "Project."
space.vars.OIM) to represent that the corresponding source entity's "Entity type" and/or "Project" is changed.
* In the "Soft Delete", the entity will be deleted in the target, and will move to the recycle bin of the corresponding systems.
* Currently, the "Soft Delete" is supported for Rally, Digital.ai Agility (Formerly known as VersionOne), and Team Foundation Server systems in space.vars.OIM.
* In the "Archive operation", the entity will be archived in the corresponding systems.
* Currently, the "Archive operation" is supported for Jira On Premise system in space.vars.OIM.
Furthermore, space.vars.OIM supports the synchronization of project structures (in which each project from that hierarchy can be synced to target project) via [Child Project Sync](/integrate/configure-integrations/integration-configuration#child-project-synchronization) feature. In such cases, if the project is restructured in the end system, and the entity from the new project structure is transformed to a different target project (other than the previously synchronized one), it will be categorized as project movement synchronization. Refer to [Synchronization with project hierarchy](#synchronization-with-project-hierarchy) for more details.
## Configuration Steps
* In order to perform the Deprecation in the target entity, "Delete Mode" mapping shall be configured in the mapping configuration of the older Entity type and/or Project's integration.
* Refer to '[Delete Mode mapping configuration](/integrate/configure-integrations/mapping-configuration#delete-mode)' section for further details on "Delete Mode" mapping.
* If the "Delete Mode" mapping is not configured, then deprecation will be reflected in the sync report of space.vars.OIM only.
> **Note** : To distinguish between "Logical Delete" performed on target entity due to source delete synchronization or deprecation performed due to source entity's "Entity type" and/or "Project" change, some advanced mapping configurations can be used. Refer to [Differentiating source delete synchronization and deprecation](#differentiating-source-delete-synchronization-and-deprecation) section for further details on the same.
## Known Behaviors
* space.vars.OIM facilitates the synchronization of updates in the "Entity type" and/or "Project" to the target by performing the above pre-defined actions by default.
* However, if the user does not want to change the "Project" once the entity is created in the target system, the "Create" option can be set in "Sync When?" setting of the 'Projects' field mapping. Refer to the [Restrict project update in target](#restrict-project-update-in-target) section for more details.
* If in the source system, the "Entity type" and/or "Project" are changed, and this new "Entity type" and/or "Project" are transformed to the same "Entity type" and/or "Project" of the target system (which is previously synchronized), such scenario would not be considered as entity movement. Refer to [Synchronization with flat project mapping](#synchronization-with-flat-project-mapping) for more details.
* To synchronize the source entity's "Entity type" and/or "Project" changes, the integration user for the target system must have read and write permission on previously synced(having older entity type/project) entities.
### When the target system doesn't support the "Entity type" and/or "Project" change
* space.vars.OIM will perform the following operations:
1. Previously synced entities will be marked deprecated based on the "Delete Mode" mapping configured of older "Entity type" and/or "Project"'s integration.
> **Note**: If the integration associated with the older "Entity type" and/or "Project" is not available, then the delete mode mapping configured in the integration related to new "Entity type" and/or "Project" will be considered.
2. A new entity will be created based on the current data of the source entity.
3. If the comments are mapped in the mapping, ['OpsHub-020404' or 'OH-Connector-06201'](/help-center-index/troubleshooting-index/errors-index/common-error-solutions/opshub-020404) error will be observed temporarily in the sync.
* If the source entity is restored to the older "Entity type" and/or "Project", it will be treated as a new change on that source entity. As a result, deprecation and new creation of the entity will be performed in the target system.
* space.vars.OIM has integration configurations, involving multiple systems:
space.vars.OIM:
* Deprecated entities will not be fetched from any other integration configuration.
* If there is any failure on the target entity, which is going to be deprecated, space.vars.OIM will delete the failures on that entity.
### When the target system supports the "Entity type" and/or "Project" change
* When space.vars.OIM contains a single "Entity type" and/or "Project" to multiple "Entity types" and/or "Projects" integration configurations:
* For the older "Entity type" and/or "Project":
* The last updated entity by space.vars.OIM is applicable for conversion, and the rest entities will be deprecated as shown:
space.vars.OIM will convert "Problem" to "Story" and deprecate "Defect".
```
* For the newer "Entity type" and/or "Project":
* The integration which fetches the updated entity first will perform the type/project change in the target. Others will do normal create/update.
space.vars.OIM, some interim conversions may get skipped if not fully fetched:
space.vars.OIM. If there are no intended modifications in the project field's value mapping, the "Same as Integration" option within the value mapping can be used. This will avoid redundant project value mappings for the "Projects" field.
* By performing the above configurations, space.vars.OIM will synchronize the source updates to the target (on the previously synchronized entity) without altering the project, i.e.,
* Configurations in space.vars.OIM are as follows:
| Integration Configuration | | | | | Mapping Configuration | | | |
| ------------------------- | --------- | ------------- | -------------- | --------- | --------------------- | ------------- | -------------------- | -------------- |
| **Endpoint 1** | | **Direction** | **Endpoint 2** | | **Endpoint 1 field** | **Direction** | **Endpoint 2 field** | **Sync When?** |
| Entity Type | Project | | Entity Type | Project | | | | |
| Defect | Project A | Forward | Bug | Project B | Projects | Forward | Projects | Create |
| Defect | Project C | Forward | Bug | Project D | | | | |
* Here, if the project of the Defect entity SE1 is updated to 'Project C' in Endpoint 1, space.vars.OIM will synchronize this update to the Bug of Project B, i.e., TE1 in Endpoint 2 (instead of updating the project to Project D):
space.vars.OIM are as follows:
| Integration Configuration | | | | | Mapping Configuration | | | |
| ------------------------- | --------- | ------------- | -------------- | --------- | --------------------- | ------------- | -------------------- | -------------- |
| **Endpoint 1** | | **Direction** | **Endpoint 2** | | **Endpoint 1 field** | **Direction** | **Endpoint 2 field** | **Sync When?** |
| Entity Type | Project | | Entity Type | Project | | | | |
| Defect | Project A | Forward | Bug | Project B | Projects | Forward | Projects | Create |
| Defect | Project C | Forward | Story | Project D | | | | |
* Here, if the project of the Defect entity SE1 is updated to 'Project C' in Endpoint 1, space.vars.OIM will synchronize this update to the Bug entity of Project B, i.e. TE1 in Endpoint 2 by modifying the Entity Type to 'Story':
space.vars.OIM are as follows:
| Integration Configuration | | | | | Mapping Configuration | | | |
| ------------------------- | --------- | ------------- | -------------- | --------- | --------------------- | ------------- | -------------------- | -------------- |
| **Endpoint 1** | | **Direction** | **Endpoint 2** | | **Endpoint 1 field** | **Direction** | **Endpoint 2 field** | **Sync When?** |
| Entity Type | Project | | Entity Type | Project | | | | |
| Defect | Project A | Bidirectional | Bug | Project B | Projects | Forward | Projects | Create |
| Defect | Project C | Bidirectional | Bug | Project D | Projects | Backward | Projects | Both |
* Here, if the project of the Defect entity SE1 is updated to 'Project C' in Endpoint 1, space.vars.OIM will synchronize this update to the Bug of Project B, i.e., TE1 in Endpoint 2.
* Afterwards, if the Bug entity TE1 is updated in the Endpoint 2, it will create a new Defect entity in 'Project A' of Endpoint 1, i.e., SE2:
space.vars.OIM.
* Configurations in space.vars.OIM are as follows: **Integration Configuration** (Left) | **Mapping Configuration** (Right)
| Jira Entity Type | Project | Direction | Rally Entity Type | Project | Jira Field | Direction | Rally Field | Sync When? |
| ---------------- | ----------- | ------------- | ----------------- | ----------- | ------------------ | ------------- | -------------- | ---------- |
| Defect | Project A | Bidirectional | Bug | Project B | Rally Project Enum | Bidirectional | Projects | Both |
| Defect | Project A | Bidirectional | Bug | Project C | Projects | Backward | Rally Projects | Create |
| Defect | Project D | Bidirectional | Bug | Project E | Projects | Forward | Rally Projects | Both |
| (continued) | (continued) | (continued) | (continued) | (continued) | Projects | Backward | Rally Projects | Create |
* If the project of the Defect entity SE1 is updated to 'Project D', space.vars.OIM will synchronize this update by updating the project of Rally Bug entity TE1 to 'Project E'.
* If the project of the Bug entity TE2 is updated to 'Project E', space.vars.OIM will synchronize this update to Jira Defect entity SE2 of Project A in Endpoint 1 without modifying its project:
space.vars.OIM are as follows: **Integration Configuration** (Left) | **Mapping Configuration** (Right)
| Endpoint 1 | Project | Direction | Endpoint 2 | Project | Endpoint 1 Field | Direction | Endpoint 2 Field | Sync When? |
| ----------- | --------- | --------- | ----------- | --------- | ---------------- | --------- | ---------------- | ---------- |
| Entity Type | Project | | Entity Type | Project | | | | |
| Defect | Project A | Forward | Bug | Project B | Projects | Forward | Projects | Create |
| Defect | Project A | Forward | Bug | Project C | | | | |
* The Defect entity SE1 of the Project A in Endpoint 1 will be synchronized as a Bug entity TE1 in 'Project B' of Endpoint 2 via Integration 1 and Integration 2. So, there will be no entity corresponding to SE1 in the 'Project C' of the Endpoint 2:
space.vars.OIM are as follows:
| **Configurations** | **Integration Configuration** | | | | | **Mapping Configuration** | | | |
| ------------------ | ----------------------------- | ---------------------- | ------------- | -------------------------- | ---------------------- | ------------------------- | ------------- | -------------------- | -------------- |
| | **Endpoint 1 Entity Type** | **Endpoint 1 Project** | **Direction** | **Endpoint 2 Entity Type** | **Endpoint 2 Project** | **Endpoint 1 Field** | **Direction** | **Endpoint 2 Field** | **Sync When?** |
| **Old** | Defect | Project A | Forward | Bug | Project B | Projects | Forward | Projects | Both |
| **Old** | Defect | Project A | Forward | Problem | Project C | | | | |
| **New** | Defect | Project D | Forward | Bug | Project E | Projects | Forward | Projects | Create |
* Here, the Defect entity SE1 of Endpoint 1 will be synchronized in Endpoint 2 as Bug in Project B (TE1) and as a Problem entity in Project C (TE2).
* If the project of the Defect entity SE1 is updated to 'Project D', space.vars.OIM will synchronize this update to TE2 of Project C (the last updated entity) in Endpoint 2 by modifying the Entity Type from 'Problem' to 'Bug' and deprecate the older entity TE1 (to avoid orphan entities) in Endpoint 2:
space.vars.OIM are as follows:
space.vars.OIM will synchronize the SE1 either by updating the project of TE1 to 'Target Project 2' (if Endpoint 2 supports project update) or create a new entity TE2 in 'Target Project 2' and deprecate TE1 (if Endpoint 2 does not support project update).
#### Synchronization with flat project mapping
* Configurations in space.vars.OIM are as follows:
space.vars.OIM will synchronize the SE1 to TE1 without updating its project (as the new transformed project is same as the previously synchronized project).
# Inline Image or File Synchronization
## Overview
space.vars.OIM supports the synchronization of images and files across end systems in fields, comments, and as attachments on the entity.
* There are certain types of end systems based on how they add images/ files on their entity fields and comments.
1. **Entity Storage:**
* Upon adding an image/ file to rich text fields, the same image/ file is also added as an attachment to the entity.
* Example: If image/ file is added to rich text field in Rally, the same image/ file will be visible in attachment section of the entity.
* Entity Storage Systems: Rally, Jira, OpenText ALM Quality Center (Formerly Micro Focus ALM/QC), qTest, DOORS NG, ServiceNow, Codebeamer, Windchill, TestRail, OpenText ALM Octane, Enterprise Architect, Aha!, Redmine
2. **Server Storage:**
* Upon adding an image/ file to rich text fields, they are uploaded to an end system location itself, but the image/ file will not be added as an attachment to the entity.
* Example: If image/ file is added to rich text field in Azure DevOps, this image/ file will not be visible in attachment section of entity. Instead, it will be uploaded to an end system.
* Server Storage Systems: Version one, Jama, Aras, Readyone, Salesforce, ETM, DOORS, Hubs=Spot, Azure DevOps
3. **Base64 Storage:**
* Upon adding an image/ file to rich text fields, they are not uploaded anywhere. The raw data itself is encoded in Base64 and is set in the rich text field. Image/ file will not be added as an attachment on the entity.
* Example: If image/ file is added to rich text field in Broadcom Clarity, image/ file will not be uploaded anywhere. Also, it will not be added as attachment on the entity.
* Base64 Storage Systems: Broadcom Clarity
4. **Field Storage:**
* Upon adding an image/ file to a rich text field (such as the Test Step field), it is stored only within that specific field. It is not stored at the entity level or server level.
* This means the attachment is linked directly to the field where it is added (field-level storage).
* Example: If an image/ file is added to the Test Step field of a Test entity in Jira Xray (Cloud), it will be visible only in the attachment section of that Test Step field.
* Field Storage System: Jira Xray (Cloud) – Test Step field of Test entity
space.vars.OIM as shown in the above image, it will be similar to the way image/ file is added to the source end system entity, i.e., it will only be added on inline field/ comment.
### Entity Storage System Combinations
space.vars.OIM as shown in the above image, it will be similar to the way image/ file is added to the source end system entity, i.e., it will be added on inline field/ comment and also as an attachment on the entity.
* Due to the entity storage system's behavior of auto-adding the image/ file as an attachment to the entity regardless of whether attachment synchronization is enabled/ disabled in mapping. space.vars.OIM will also add the attachment on the entity to synchronize the image/ file.
### Server/ Base64 Storage and Entity System Combinations
* Between server/ base64 and entity storage combination systems, if an inline image/ file is added to the entity, upon synchronization by space.vars.OIM above shown image will be the way image/ file will be added to the entity.
* When the entity storage system is the target, space.vars.OIM will auto-add the image/ file as an attachment to the entity.
* When server/ base64 storage system is the target, space.vars.OIM will not auto-add the image/ file as an attachment to an entity. It will only be added in the rich text field/ comment.
* View parity between these storage combinations will be due to end-system behavior differences.
## Image/ File Synchronization Behavior with Text Fields/ Comments
* In the case of a Text type field/ comment, we cannot add renderable images/ files.
* Hence, we will add a custom tag with the uploaded image/ file URL and the filename of the uploaded image/ file.
```xml
space.vars.OIM, below mentioned will be the behavior:
* Data synchronized to the target entity will not have any renderable images/ files or opshub custom tags for image/ file when it is not a renderable field/ comment.
* Images/ files will be uploaded to the entity as attachments.
* In backward synchronization, from such end systems, the originally added images/ files will be removed from the fields.
## Image/ File Synchronization Behavior with Comment
* If a comment has been synchronized by space.vars.OIM with an inline image/ file, the target comment will also have the image/ file.
* Now, even if the comment is deleted in the source end system, the image/ file will persist in the target comment and also as an attachment on the entity in case it is an entity storage end system.
## Attachment and Inline Image Synchronization with Field Storage
#### Applicable to following systems:
* Jira Xray cloud, Jama and Codebeamer
Other systems may require additional customization to handle step level attachments and inline images. Please refer to connector documentation for more details.
### Pre-requisite
* Attachment mapping must be enabled in space.vars.OIM to synchronize step level attachments.
* Attachment type will be auto-mapped based on field configuration in mapping to sync step level attachment. For more details, refer [Auto-mapping of Attachment type](#auto-mapping-of-attachment-type).
* No pre-requisite to synchronize step level inline images.
### General Behaviors:
* Format conversion of step-level fields (except additional step-level fields) is automatically managed by the system.
* Only the additional step-level fields (which may vary from system to system) need to be handled explicitly in the mapping XSLT, as done earlier.
* When a test-step type field with attachments is synced from a field storage system (Jira Xray Cloud) to an entity/server storage system (Jama or Codebeamer), the attachment is stored at the entity level in Jama/Codebeamer.
#### Step field data synchronization based on mapping configuration
| Mapping Configuration | Behavior |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 'Step' field is mapped & 'Attachment' mapping is enabled | Steps with attachment and inline images will be synchronized. |
| Only 'Step' field is mapped | Steps with inline images will be synchronized. Attachments will not be synchronized. |
| Only 'Attachment' mapping is enabled | If previously 'Step' field mapping was configured & now removed from mapping, given attachment is enabled now, the attachment types won't be removed from attachmet mapping. However, as Step field is not mapped now, no new attachment will be synced at step level, they will only be synced at entity level. If there is any update on already synced steps attachment, they will be synced and no impact on them.
If Step field is not mapped and only attachment mapping is enabled, then attachment will be synced at entity level and no action will be performed at step level.
Attachment is added to the entity.
For the end systems, where field level attachments are not supported, attachments associated with a particular step are included in the Description sub-field of that step. So user will know that which attachments are a part of step from entity level attachments. However, this is just plain text data for reference point of view, not a link to those attachments.
For example: two attachments are added for step 1 & one attachment is added for step 2 to the entity, step content will be as followed:
Step 1 description: “step 1 text data \
Step 2 description: “step 2 text data \
It is suggested to keep space.vars.OIM added content at the end of original content during modification; however, synchronization will not be impacted regardless of its placement.
- Create entity with no attachment or inline images
- Add inline image to entity & start synchronization
- An image will be uploaded twice, one as attachment & second as inline image
- Due to re-upload of image, one image of source will be in sync with multiple target images
- Create entity with no attachment or inline image
- Add comment with inline image & start synchronization
- First, image will be added as attachment
- When the image is detected as inline image, the same will be removed from the attachment
- A new image will be uploaded as the inline image. It will be referred from rich text field or comment.
- Create entity with one attachment
- Add the same file in rich text field
- If the rich text field was not mapped previously and it had inline images
- After few revisions, rich text field is mapped
- Create entity with multiple same name images referred in single rich text field & synchronize to target
- Update target entity & start other way synchronization
- Create entity with same image referred in two or more rich text fields
- Update the content of image
- In later revision, both rich text field has some text appended
- Inline image will be updated twice
- Due to re-upload, one image of source will be in sync with multiple target images
- HTML type of field is mapped with text field in target
- Source field has an inline image
- Two images will be uploaded, one as external image in target system and other as attachment on entity
- In target text field, it will be shown as \
- One image will be uploaded in the target system and this will not be visible in attachment section of entity
- In target text field, it will be shown as \
- Attachment will be uploaded twice
- In target text field, it will be shown as \
- Attachment will be visible in attachment section of entity.
- In target text field, it will be shown as \
- Target text field will have \
- Image will not be uploaded to attachment or anywhere. Instead, an image tag with filename will be created
- Same source field is mapped to two different fields in target & one of them is a text field and other one is a rich text field
- Source field has inline image
- Image will be synchronized both as inline image for rich text field and as attachment to the target entity
- Rich text field has inline image
- Text field has \
- Entity has attachment
- Rich text field will have inline image
- Text field will have \
- Image will be uploaded to external server and will be referred in these 2 fields
- Rich text field will have inline image
- Text field will have \
- The entity will have only the attachment due to the implicit behaviour of Entity Storage Connector
- Create entity with no attachment or inline image
- Add comment with inline image & start synchronization
- Target end system does not support inline image in comments
- Same image will be uploaded twice to the end system
- Attachment will be added to the entity also
- First, image will be added as attachment
- When the image is detected as inline image, the same will be removed from attachment & image will be uploaded to server again
- The comment will be added with \
- First, image will be added as attachment to entity
- When the image is detected as inline image, a comment will be added with \
- Comment synchronization is enabled
- Rich text field is mapped to text field in target
- Both have same inline image
- Image will be uploaded to server system & text field data added with \
- Comment will be added with referred inline image
- Source HTML field is mapped to target text field
- Create entity with inline image & synchronize
- Update target text field & start reverse synchronization (from target to source)
- If same name image is found in source entity, it will be replaced with source URI
- In case, image with same name is not found, the image will be removed from the source entity
- Create entity with rich text field having image 1
- In next revision, image 2 is uploaded on the same field
- If the events fail and are in retry but image 1’s base64 data is missing from the write-side cache
- Base64 content for image 1's hashcode will be queried in source entity
- Since, it is no longer present on entity now, image 1 will not be synchronized
- In the next revision, image 2 will be synchronized
space.vars.OIM supports the synchronization of sync-abandoned source entities by performing Logical delete, Soft delete, or Archive operation on the target entity.
* An entity will be treated as sync-abandoned in the following cases:
1. space.vars.OIM is unable to access that entity due to insufficient permission or its deletion.
* Such entities are categorized as "Not Accessible" in the integration sync report.
2. Sometimes, the entity is no longer a part of synchronization in space.vars.OIM, then also it will be treated as sync-abandoned entity, i.e.,
* Modification of project and/or entity type of an entity in the end system leads to its exclusion from the synchronization, when the configuration related to updated entity type and/or project:
1. Does not exist in space.vars.OIM.
2. Exists with specified criteria but the entity no longer meets the criteria.
* Such entities are categorized as "Not Applicable" in the integration sync report.
* In the "Logical Delete", some of the fields of the target entity is updated with some fixed values to represent that the corresponding source entity is deleted.
* In the "Soft Delete", the target entity will be deleted in the target, which can go to the recycle bin of the corresponding systems.
* Currently, the "Soft Delete" is supported for the Aha, Rally, Team Foundation Server, VersionOne, Doors, Salesforce, Codebeamer and Monday.com systems in space.vars.OIM. For further details on the same, please refer to connector documentation of systems.
* In the "Archive operation", target entity will be archived in the corresponding systems.
* Currently, "Archive" is supported in **Jira data center** and Monday.com systems.
## Configuration Steps
1. Configure '[Enable Delete Sync](/integrate/configure-integrations/integration-configuration#enable-delete-sync)' in the advance configuration panel of the integration.
2. Upon '[Enable Delete Sync](/integrate/configure-integrations/integration-configuration#enable-delete-sync)' configuration, Soft Delete or Archive operation will be performed by default based on target system behavior.
* To perform only logical delete, configure the '[Delete Mode](/integrate/configure-integrations/mapping-configuration#delete-mode)' mapping for the corresponding fields, setting the default value to 'No' in the '[Delete Mode](/integrate/configure-integrations/mapping-configuration#delete-mode)' mapping.
* If the target end system supports both Soft Delete and Archive operations, Soft Delete will be performed by default. Otherwise, deletion will be performed as per the '[Delete Mode](/integrate/configure-integrations/mapping-configuration#delete-mode)' mapping.
## Known Behaviors
* This configuration needs to be performed for each entity pair configured in the integration group.
* If the source entity is restored somehow in the end system, in that case, the further updates on that entity will be synchronized under the configuration done for the regular synchronization of the "Create"/"Update" events.
* If the access of the integration user is revoked from some set of entities, then those entities will be considered as deleted for that integration user. Therefore, they will be considered for the Source Delete synchronization. Once access is being given to those entities, they would remain in sync and the behavior of the synchronization would be similar to the restoration of the entity in the source.
* If the '[Delete Mode](/integrate/configure-integrations/mapping-configuration#delete-mode)' mapping gets updated, then the earlier synchronized data cannot be reconciled as per the new "Delete Mode" configuration.
* If the Delete event is synchronized for the source entity, for which space.vars.OIM has recreated the entity in the target as per 'Recreate' configuration of '[Action on Entity Deleted in Target](/integrate/configure-integrations/integration-configuration#action-on-entity-deleted-in-target)' advanced setting, then in the '[Integration Sync Report](/help-center-index/troubleshooting-index/integration-sync-report)', the already deleted entity will be in the 'Active' state.
* If **Synchronize Not Applicable Entities** is configured with **Yes** input:
* space.vars.OIM will meticulously scan all the configurations between relevant source and target systems. Consequently, there's a risk of erroneously identifying entities as not applicable under certain circumstances:
* Criteria configuration will be updated in any dormant integration configuration related to the updated entity type or project.
* In this case, space.vars.OIM will consider the criteria set during the delete synchronization, which can lead to misidentification in the following cases:
* Even if an entity meets the criteria (to be updated in the dormant configuration), it will still be flagged as "Not Applicable" because it didn't meet the criteria at the time of delete synchronization.
* If the entity meets the criteria defined in the dormant configuration during the delete synchronization, it will be included in the synchronization process of dormant configuration, when reactivated, even if it no longer meets the updated criteria.
* Hence, it is recommended to enable this setting only when all the configurations within space.vars.OIM are strictly configured with the intended criteria, and there are no dormant or obsolete configurations (to be deleted in future).
## Use Case
* Suppose, the configuration between System 1 and System 2 is as follows:
* The Delete configuration of Bug integration includes soft deletion or archive operation on the target entity in System 2.
* space.vars.OIM has synchronized 6 entities from System 1 to System 2, i.e., source entities SE1, SE2,...,SE6 to target entities TE1, TE2,...,TE6, respectively.
space.vars.OIM will perform these actions:
* TE1 and TE2 will be deleted in the target, and the sync report will be updated with the "Not Accessible" state for these entities.
* Updates on the SE3 and SE4 will be synchronized to the target entities TE3 and TE4 respectively via Task and Story integration.
* TE5 (as SE5 fails to meet the criteria of Story integration) and TE6 (as the configuration related to Feature is missing in space.vars.OIM) will be soft deleted or archived in the target as per the configuration, and the sync report will be updated with the "Not Applicable" state for this entity.
space.vars.OIM automatically manages the field's value based on the defaults defined in the Routing Criteria Field Values table.
* Use the **same field set** across all rows in a rule-based configuration.
* Example: If one row in a rule-based configuration uses the `priority` field in its routing query, then all other rows in that configuration must also use only the `priority` field in their routing queries.
* Keep all **routing rules independent** across rows.
* Example: If one row in a rule-based configuration uses the routing criteria `{"condition": "IN", "field": "priority", "values": ["High", "Medium"]`}, then another row in the same configuration **cannot** use`{"condition": "IN", "field": "priority", "values": ["High", "Low"]}`. Each row must define a distinct and non-overlapping routing rule.
* Do **not** use routing-based configuration if duplication is expected in the target.
* If one source entity needs to stay in sync with multiple target entity types at the same time, avoid rule-based routing.\
Under rule-based routing, a source entity can sync with only one target entity type at a time — based on the rule it matches.
## Default Route Configuration Guidelines
Follow these guidelines when configuring the **default route**:
* Only one default route can be configured, within a given rule-based configuration.
* The default route is applied only when no routing criteria match for an incoming entity.
* Changes to the default route can impact previously synchronized entities.
* When modified, entities that were synchronized due to default route may undergo entity type conversion during subsequent synchronization.
* Disabling the default route will result in synchronization failures for incoming entities where no routing criteria match.
## Example Use Case
Consider a source system where all items are created as a Request, and the field **requestType** determines the entity type to be created in the target.
| **requestType Value** | **Target Entity Type** |
| --------------------- | ---------------------- |
| Bug | Bug |
| Feature Request | Feature |
| Change Request | Change Request |
**Typical Behavior:**
* When the source Request has requestType = Bug, it is synchronized as a Bug in the target system.
* If the requestType changes to Feature Request, the previously synced Bug is automatically converted to a Feature Request — without creating duplicates.
* If the entity type changes on the target side, the requestType field in the source system updates automatically to stay aligned.
## Configure default route
In integrations where routing criteria determine the target entity type, there may be scenarios where incoming entities do not match any configured conditions. The default route ensures such entities are still processed by assigning a fallback target entity type.
Consider a source system where all items are created as a Request, and the field **requestType** determines the entity type to be created in the target (as per the above example use-case)
Integration Configuration with default route
| **Source Entity Type** | **Target Entity Type** | **Routing Criteria** | **default route** |
| ---------------------- | ---------------------- | ----------------------------- | ----------------- |
| Request | Bug | requestType = Bug | false |
| Request | Feature | requestType = Feature Request | true |
| Request | Change Request | requestType = Change Request | false |
**Behavior with default route Configured**
* When a source Request has requestType = Story (or any value not matching configured criteria), no explicit routing criteria is satisfied.
* In such cases, the *default route* is applied for the synchronization, For example, for requestType = Story, the target entity type will be Feature (as per the above configuration).
**Behavior When default route is Changed**
* Continuing the above scenario, a Request with requestType = Story is initially synchronized as a Feature.
* If the default route is changed to requestType = Bug route.
* On the next synchronization, the existing target entity will be converted from Feature to Bug.
* **Warning** : Changing default route will change the entity type of all records synchronized via the default route in the next sync cycle.
**Behavior When default route is Disabled**
* If the default route is disabled and an entity does not match any routing criteria:
* The synchronization will fail with the error message: "OpsHub-020604: No routing criteria matched the provided entity values. Review the currently configured routing criteria: {currently configured criteria}"
space.vars.OIM allows seamless conversion when the routing field value changes and automatically updates the corresponding target entity type. It also ensures that when updates flow in the reverse direction, the source field value is adjusted accordingly, maintaining complete bidirectional consistency. For more details about configuration, refer to this section: [Routing Rules Configuration](/integrate/configure-integrations/integration-configuration#rule-based-routing).
# Integration Reconciliation
## Overview
Reconciliation feature helps reconcile data for fields added in integration. Primary use of this feature is to reconcile existing data in the end system after changing mapping, for example after adding new field, link type, enabling attachment, etc.\
Some of the use cases where this feature can be used are:
1. The user wants to add field(s) that was previously not integrated, but now the user would like it to be integrated. But the user also does not want to perform any mass update on all other entities existing in the source system so that the value of only the newly added field is integrated.
2. The user may already be using space.vars.OIM for sync and the data got into an inconsistent state, either due to bad failure management or inappropriate conflict resolution. And now, the user wants to reconcile both the systems to achieve a consistent state.
An important point to remember is that Reconciliation is not Integration or Migration, and hence should not be confused with them.
## Steps to Configure Reconciliation
> **Note**: Few things to know before reconciling data:
>
> * Inactive the integration to be reconciled. If the integration is not inactivated, then it will be automatically inactivated once data reconciling starts.
> * When Reconciliation is configured on integration, all Failed Events currently associated with the integrations would be **deleted**.
> * **Remote Entity Id** and **Remote Entity Link** fields are not supported.
> * Workspace / Project / Entity type name with Unicode character is not supported.
* To configure Reconciliation, navigate to the integration to be reconciled. Click on reconcile icon as shown below:
| Merge Integrations | /pages/YiiNct3masc523IhskmA |
| Organize Integrations | /pages/S6Oi5ChHLTSJB43Hm8DF |
| Search and Navigation | /pages/IxSUxb8DylTNLCUfF3Jm |
| Using the Dashboard | /pages/mTtapehuwzd07MvMwclJ |
| Using Trends & Metrics | /pages/NNPKjLKhF4huaba2A7sd |
space.vars.OIM Version 7.0, it was not possible to create bidirectional mapping and integrations in one go. If a user wanted to create a bidirectional integration between TFS and JIRA, the required configurations were as follows:
* **Configuration 1**
* Mapping 1 \[TFS User Story to JIRA Requirement]
* Mapping 2 \[JIRA Requirement to TFS User Story]
* Integration 1 \[TFS User Story to JIRA Requirement] with Mapping 1 associated with the integration
* Integration 2 \[JIRA Requirement to TFS User Story] with Mapping 2 associated with the integration
But from version 7.0 onwards, it's possible to have 1 mapping and 1 Integration for such cases. If a user wanted to create a bidirectional integration between TFS and JIRA, the required configurations now are as follows:
* **Configuration 2**
* Mapping 1 \[TFS Story to and from JIRA Requirement]
* Integration 1 \[TFS User Story to and from JIRA Requirement] with Mapping 1 associated with the integration
So, if a user migrates space.vars.OIM instance to 7.0 version or onwards, the user can merge Mapping 1 and Mapping 2 into Mapping 1 as well as Integration 1 and Integration 2 into Integration 1. So, the user doesn't have to manage multiple integrations. Users can simply delete Mapping 2 and Integration 2 after they are successfully merged to another configuration and if they are not being used in any other integration.
The above case is also applicable when Configuration 1 is created in the new UI and user wants to have configuration like Configuration 2. If the user has created different integrations created for different projects:
User had defined configurations as given below. It is because of project templates mismatch, user was required to create different mappings and different integrations.
* Mapping 1 \[TFS User Story to JIRA Requirement for Project 1]
* Mapping 2 \[TFS User Story to JIRA Requirement for Project 2]
* Integration 1 \[TFS User Story to JIRA Requirement for Project 1] with Mapping 1 associated with the integration
* Integration 2 \[TFS User Story to JIRA Requirement for Project 2] with Mapping 2 associated with the integration
But now both projects fall under similar templates and same mapping can be used in them. So, user can merge Integration 1 and Integration 2 and delete the other integration and mapping if they are not being used anywhere else.
## Merging Mappings or Integrations
The process for merging two mappings or integrations with sample example is given below.
### Merge Mappings
Here for example let us assume there are 2 different mappings \[TFS User Story to JIRA Requirement and JIRA Requirement to TFS User Story as below]
* TFS User Story to JIRA Requirement
* JIRA Requirement to TFS User Story
space.vars.OIM based on use case. Given below are some example of use case and using folders to manage integrations:
**1. Divide based on system combination**
* User wants integration between VersionOne, TFS and HP ALM.
* Integration can be divided into two sets:
* VersionOne and TFS integrations
* TFS and HP ALM integration
> **Note**: It can be a bi-directional integration with multiple entities involved for each set of integration.
* Create systems at default level so that it can be accessed in child folders.
* Create mappings and integration in folders as shown below.
space.vars.OIM.
You can search within two scopes — depending on whether you want a focused or global search: **Current Folder** and **All Folders**.
space.vars.OIM. Users can check overall health of integrations and know if integrations are working fine or have any failures. Users can navigate directly to integrations, systems, and failures from the dashboard.
Here is a video on how to use the dashboard in OIM:
{% embed url="space.vars.OIM.
* Dashboard will appear on home page under Integration Landscape tab.
space.vars.OIM.
* **Branch:** Represents that two nodes are connected through integration. Click on branch to view integration in read-only mode. Color of branch depicts status of integration.
* **Green:** Integration is active.
* **Gray:** Integration is inactive.
* **Red:** Job failure in integration.
* **Orange:** Processing failures in integration.
* Click on  to view integration details from dashboard.
space.vars.OIM. Users can monitor sync volume, identify high- or low-activity areas, track project growth across systems, and drill down into specific systems, integrations, projects, and entity types for deeper analysis.
## Trends & Metrics View
* Login into space.vars.OIM.
* Navigate to Metrics and Trends Dashboard on the home page
space.vars.OIM across all integrated systems.
space.vars.OIM across all integrated systems.
space.vars.OIM across all systems, including both in-sync and deleted entities.
* In sync entities include all active entities that are currently part of the synchronization.
* Deleted entities include all entities that have been deleted, archived, or deprecated - including entities deprecated due to project conversion, entity conversion, or both.
space.vars.OIM.
## Infrastructure
### Database
* Use any database from the supported 4 databases \[Oracle, MSSQL Server, MySQL, PostgreSQL] for production deployment. HSQL shouldn't be used for production deployments.
### Database Disk Space
| WorkItem | Sync State | Estimated DB Size |
| ----------------- | --------------- | ----------------- |
| <100K | Current/History | 50GB |
| 100K to 500K | Current/History | 100GB |
| 500K to 1 million | History State | 150GB |
| 500K to 1 million | Current State | 150GB to 250GB |
> **Note**: Actual size depends on various factors, including the total count of work items, sync state, sync failures, number of attachments, links, and overall usage patterns. For small-scale implementations, starting with a minimum database size of 15GB is recommended to accommodate initial needs effectively.
### RAM and Threads
| Integration | RAM allocated to OIM | Threads in OIM | Machine Core | Heap Space | Machine Disk Space | Environment Type |
| ----------- | -------------------- | -------------- | ------------ | ---------- | ------------------ | ---------------- |
| Up to 50 | 8GB | 27 | 4 | 4GB | 50GB-100GB | Small |
| 50-150 | 16GB | 50 | 6 | 12GB | 150GB-200GB | Medium |
| 150-900 | 32GB | 100-150 | 8 | 28GB | 300GB-350GB | Large/Enterprise |
> **Note**: The RAM data is estimated, as RAM requirements depend on several factors, including the number of integrations, thread count, and scheduling cycle settings.
### Enable Monitoring for OpsHub Service, Database, and VM for Health Check
* In a production environment, it's important to have monitoring in place for the OpsHub service, database, and the virtual machine (VM) where OpsHub is installed.
* **Set up alert**: OpsHub service, database, or VM goes down.
* **Monitor OpsHub's database access** (if possible): if the database becomes unavailable or there are access issues, alerts are triggered.
* When OpsHub is down: It will not generate its usual failure alerts. Therefore, external monitoring is necessary to ensure you receive alerts if the system, database, or VM becomes unresponsive.
### Enable Database and VM backups
* **Database backup**: Once a day or less (point in time).
* Frequent backups ensure you can quickly recover the most recent configuration, mappings, and sync histories in case of data loss or corruption.
* **VM \[OIM installed] backup**: Once a month or quarterly.
* A monthly or quarterly backup allows you to capture the state of the VM, including OS-level changes and configurations, while not overwhelming storage with frequent snapshots.
## Integration
### Integrate multiple projects through a single integration
* Group integrations for management efficiency when:
* Multiple projects share similar templates or artifact structures.
* Managing individual integrations becomes cumbersome.\
Example: Managing user stories, tasks, and bugs across multiple Jira and Rally projects.
* **Grouping Benefits:**
* Reduced API Calls
* Simplified Maintenance
* Unified Control
* Easier Error Handling
### Managing Project Count in Integrations
* **Limit Projects per Integration**: 25 or fewer for optimal performance.
* **Balance Large and Small Projects**: Combine large projects (100,000+ entities) with smaller ones to avoid overloading the integration.
### Enable Remote ID and Remote Link
* **Remote ID**: Easily find and track items across systems.
* **Remote Link**: Relationships between items and understanding their connections.
### Polling Frequency/Scheduling
Setting the appropriate polling frequency is crucial for effective integration management.
| Criteria | Recommended Polling Frequency | Use case |
| --------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------- |
| Target: Reporting and compliance (Once a week) | Every 12 hours
High volume: every 1 to 6 hours
Production: Use WARN
Temporary Debugging: Use DEBUG/TRACE, then revert to WARN
Testing: DEBUG
space.vars.OIM. While some exceptional cases may require specific operations, admins must not perform any of the following actions with the space.vars.OIM system without proper guidance.
* Do not rename entity types or projects into end systems. Please consult the system expert or space.vars.OIM support before implementing any such change in the end system.
* Do not upgrade space.vars.OIM without going through pre and post migration checklist document.
* Do not back date 'Start polling time' once integration has started synchronizing.
* Do not delete any failures from the integration failure queue.
* Verify target search queries when you configure integration or reconciliation with this input to consider manually created entities are matched before integration transacts. Admin should manually verify that the search query is correct and producing the expected results. If this query is wrongly configured, then there are chances of entity duplication. For more information on what target search query is, refer to [Search in Target Before Sync](/integrate/configure-integrations/integration-configuration#search-in-target-before-sync) section.
# Known Behaviours And Limitations
## Common
There are a few limitations that are common across all connectors. The limitations are listed below:
* **User Mention Synchronization Limitations**
* If both the source and the target system support synchronization of User mentions and the user which is being synchronized from the source system does not exist in the target system, then that user's display name as seen in the source system will synchronize to the target system as literal text.
* If the source system supports synchronization of User mentions but the target system does not, then there are two scenarios:
* If the user *exists in both the source and the target system*, then the target system's user's display name will synchronize to the target system as literal text.
* If the source user *does not exist in the target system*, then the source system's user's display name as seen in the source system will synchronize to the target system as literal text.
* In both the above-mentioned cases, once the literal text for the user's display name is synchronized to the target system, and when this data is synchronized back to the other system, the actual User mention will be overwritten with the literal text as displayed in the target system.
* **Inline Image Synchronization Limitations**
* The inline image from an entity of the source system synchronizes as a broken image to the target system, given that the embedded inline image URL in the source system is not accessible/reachable from the machine on which space.vars.OIM is installed while the entity is getting synchronized. In that case, the inline image synchronizes to the target system without transformation in the URL corresponding to the target system. As a result, the synchronized image is broken.
* Synchronization of the height and width of the inline image is performed only for HTML-supported systems.
* If the same image is referred to more than once with a different height and width, then only the size of the last image is synchronized with all the images on the target side.
* **Comment Synchronization Behaviour (Edited Comments)**
* Consider the following scenario:
* Initial sync of an entity:
* Comments **C1** and **C2** are added and synchronized to the target system.
* Later:
* Comment **C1** is edited in the source system.
* When the edited comment is synchronized:
* space.vars.OIM detects the updated **C1** based on its modified timestamp.
* As **editing existing comments is not supported**, the space.vars.OIM does not update the previously synced comment (C1).
* Instead, a **new comment is created** with the updated content.
* This may result in **duplicate-looking comments** in the target system (original C1 + updated C1).
## End System Limitations
In addition to the common limitations, each system has its own set of synchronization limitations.\
Such limitations are available in the limitations section on each connector's page under [Connectors](/connectors).
# Manage
{% if "OM4ADO" !== visitor.claims.unsigned.product && "OAM" !== visitor.claims.unsigned.product %}
| ⚙️ Administration | /pages/st8wIQ3AMFJJeD4Zft9D |
| 🧰 Advanced Utilities | /pages/3HiSkPFDdHN9Dp4FsUjq |
| 🧩 APIs | /pages/ed6jdR8ednZuwCNkeFHe |
| 🤖 MCP Server | /pages/MRv3AdqM1yo7VKMnoNk6 |
| ⬆️ Upgrade | /pages/TV3dyAicgH7G3sO3CTtt |
| ⚙️ License Installation | /pages/dTHtq57PauMdrbfXofLF |
| 🧰 Advanced Utilities | /pages/3HiSkPFDdHN9Dp4FsUjq |
| ⬆️ Upgrade | /pages/TV3dyAicgH7G3sO3CTtt |
| User Management | /pages/ir33CHeBLDvHbyXubcVk |
| API Key Management | /pages/mG0fkBlJHgmLNzSpBC3k |
| Login Server Management | /pages/viPf2UANjxXEuFumodCx |
| Managing Licenses | /pages/bhnvVRbnzx7hL4wQkPUr |
| Proxy Settings | /pages/BzU5dUw0yOHiptO8g6d3 |
| Register Connectors | /pages/2gElsdzm9tDoed9tPc1a |
| Purge Change Logs | /pages/tZkaoBGRMNMBSf8EyGFS |
| Rules Management | /pages/ph4BCZ5DiAKrLqzbeGjN |
| Reset Default Password | /pages/7DT94km0nATi9yojImHp |
| Increase Server Memory | /pages/cH5Bv5dVgYb9lV9Wd2DO |
| Configure Socket Timeout | /pages/MN7de0h3Hz9jQgEn4Seo |
| Scheduler | /pages/S04wbuV9IpGj8njhiziu |
| Log Viewer | /pages/9uMzU8wHAloMzrjC9rmJ |
| User Access Control | /pages/GmPHO5Lq6vTUqduKv8PL |
space.vars.OIM:
> **Note** : All the new users in space.vars.OIM have administrator-level permissions. With the administrator-level permissions, the users will have access to all features.
{% embed url="space.vars.OIM. For example, here 'user.mail' is the selected attribute and so this property of the user from Azure Active Directory is to be used while defining 'User name' in space.vars.OIM.
# API Key Management
### Overview
API Keys provide a secure, dedicated credential for programmatic access to the [Admin APIs](/manage/api/getting-started-with-api) and [MCP integrations](/manage/mcp/getting-started-with-mcp) — without sharing a user's username and password.
> **Note:** API Key authentication is an additional mechanism and does not replace existing Basic Authentication.
* **License**
* API Keys are available on the **Professional** and **Ultimate** editions only. To verify your edition, refer to the value shown in the footer of space.vars.OIM.
* **API Key Permissions**
* An API Key inherits the permissions of the user who created it — it cannot be used to perform any action beyond what that user is authorized to do.
* **Where to Create**
* API Keys are created and managed from the space.vars.OIM UI under **Administration → API key**, and can be revoked at any time. Refer to [Create an API Key](#create-an-api-key) for the steps.
***
### Access API Key Management
1. Click **Administration**.
2. Select **API key** from the options in the left pane. The **API key** list view opens, showing all keys you have created.
> **Note:** The toggle for **My API keys / All API keys** is visible only to administrators (Super Admin or users with **User Management – Write** permission). For more details, refer to [User Access Control](#user-access-control) on this page.
• Must be a future date and time.
• Cannot be more than 1 year from the current date.
• Expiry date must be a future datetime.
• Expiration date cannot exceed 1 year from today.
space.vars.OIM supports LDAP and SAML Authentication, so that user can login with their own LDAP or SAML credentials.
## LDAP
### LDAP Server Limitations
space.vars.OIM does not support configuration and authentication of LDAP servers that are running behind the proxy.
### New LDAP Server Configuration
To proceed, select Login Server Type as LDAP. This will display the form shown above. Provide the following inputs to all the fields:
Select Login Server Type as LDAP and the form shown above would be displayed. Provide inputs to all the fields, as given below:
* **Login Server Name**: Enter a unique name for the LDAP Server configuration.
* **LDAP Domain String**: Enter the exact directory path (Distinguished Name) where LDAP users reside.
If your company structure is as follows:
space.vars.OIM and if not, then user can manually import it as specified in [Import SSL Certificates](/getting-started/installation/ssl-certificate-configuration).
* **Allow Anonymous Login**: Select "Yes" if you want to allow Anonymous login. If the anonymous login feature is enabled on your remote LDAP server and this option is activated in the login server configuration, users can log in without a password.
* Select **Test Connection Before Adding Server** when users want to test the connection before adding it to the records. Otherwise, it would only be added to the database but not validated.
After providing all the inputs, user can test or save the configuration.
* **Save Configuration**: It will save the entire configuration of LDAP Server to database. If **Test Connection Before Adding Server** is put on, then, space.vars.OIM would first test the connection and if the connection to the server is successful, it would save the configuration to the database. The server would be added in the Inactive state.
* **Test Configuration**: This will validate the connection to the LDAP server using the provided configuration details. If no connection username and password are specified, the test will verify only the connectivity to the LDAP server host, without performing a bind or login request.
Once the server is configured, user needs to activate it to authenticate with that server.
**Note** : To use space.vars.OIM using LDAP user, we need to create LDAP user in space.vars.OIM. Refer to Create User section on [User Management](/manage/administrator/user-management) page to create LDAP user.
***
## SAML 2.0
Identity Providers following SAML 2.0 standards and having HTTP/HTTPS metadata URL for downloading their metadata are supported.
### Just-In-Time (JIT) User Provisioning
* We Support SAML-based Just-In-Time (JIT) user provisioning, where users are automatically created in the application upon their first successful login.
* No prior user creation is required. User attributes such as name, email, and roles/groups are populated dynamically from the Identity Provider (IdP) during authentication.
* This ensures consistent user data and streamlined onboarding aligned with the IdP.
### Identity Provider (IdP) Requirements
To enable SAML JIT user provisioning, the Identity Provider must be configured to send the required user attributes in the SAML assertion.
#### Mandatory Attributes
| Attribute Name | Description |
| -------------- | ------------------------------------------ |
| First Name | User’s given name |
| Last Name | User’s family name |
| Email | email id for the user |
| Groups | Group information associated with the user |
| Roles | Roles information associated with the user |
> **Note:** Attribute names and formats must align with the application’s SAML configuration. You can define Groups or Roles, both are not required.
#### User Data Handling
When a SAML response is received:
* The space.vars.OIM checks whether the user already exists.
* If the user does not exist, a new user is automatically created (JIT provisioning).
* User attributes are created or updated from the Identity Provider (IdP), including:
* First Name
* Last Name
* Email Address
* Group or role attributes provided by the IdP
* User details are refreshed on every login to stay aligned with the IdP.
> **Note:** User that was pre-created by admin will not be de provisioner if the IDP is not providing any Group or role information. User that was auto created via JIT approach will be de provisioner.
### Service Provider Metadata
Below information should be used for configuring space.vars.OIM as a Service Provider for Identity Provider(s):
* **Assertion Consumer Service (ACS) URL** or **Single sign on URL** → `space.vars.OIM installation
* hostname: hostname of machine where space.vars.OIM is installed
* port: port on which space.vars.OIM is installed
* **Audience URI** or **Service Provider Entity ID** → `opshubsaml`
**Note** : The complete space.vars.OIM SAML Service Provider metadata can be downloaded from:\
`space.vars.OIM allows administrators to define how IdP groups or roles map to space.vars.OIM roles using a JSON configuration.
* Group‑to‑Role mapping enables automatic role assignment at login, centralized access control through IdP groups and elimination of manual role management in the space.vars.OIM.
* The mapping configuration is defined as a JSON array. Each object in the array specifies:
* An IdP group or role name
* One or more corresponding space.vars.OIM roles
* For example,
```json
[
{
"idpGroupOrRoleName": "IDP_ADMIN_GROUP",
"opshubRoleNames": ["ROLE_ADMIN", "ROLE_MANAGER"]
}
]
```
* If multiple roles given, space.vars.OIM will assign the unique union role to the user.
* The server would be added in Inactive state.
* SSL certificate needs to be imported when SAML Identity Server is on HTTPS. To import the SSL certificate, please follow the steps given on [Import SSL Certificates](/getting-started/installation/ssl-certificate-configuration).\
**Note:** In case of Azure SAML, refer to [Azure Active Directory Configuration](#azure-active-directory-configuration)
* Once the server is configured, user needs to create equivalent SAML Users in space.vars.OIM and then Activate the SAML login server, in order to authenticate with that server. **Note** :Refer to Create User section on [User Management](/manage/administrator/user-management) page to create SAML user.
***
#### Azure Active Directory Configuration
* **For downloading HTTPS Certificate:**
1. Go to **Enterprise applications**
space.vars.OIM is behind the proxy server, and you want to configure SAML authentication, then after configuring proxy using [Proxy Setting](/manage/administrator/proxy-setting), you need to re-start the space.vars.OIM server.
* Users pre-created by an administrator will not be de-provisioned if the IdP does not provide group or role information. However, users created via JIT provisioning will be assigned the default least permission where only login is allowed and not able to read any data even, roles/groups attributes are no receiving from the IdP.
***
## Default space.vars.OIM Server
In the list of login servers, users can find a record for **Default Server** of type space.vars.OIM.\
Using this, users can login with the default credentials or the users configured in space.vars.OIM itself fall in this category.
space.vars.OIM is unable to connect with any of the active LDAP servers, please contact sales/support representative.
### Password Policy Configuration
**Admin** users with the **Super Administration** role can define the password security standards for users authenticating via the default server. By default, the system enforces a password strength policy requiring a **minimum of 10 characters** and at least **three of the four** available character types:
* Uppercase letters (A–Z)
* Lowercase letters (a–z)
* Numbers (0–9)
* Special characters (!@#$%^&\*).
To customize these settings, navigate to the Default space.vars.OIM Server configuration page:
space.vars.OIM.
**Login Server view has the following information:**
* **Server Name** of the servers configured.
* **Server Type** of the servers configured.
* Current **Status** of the servers.
* **Actions**: Following actions could be performed on a server:
* **Edit**: User can edit the server configuration as per their requirement.
* **Activate/Inactivate**: User can change the status of the server as per their requirement.
* **Delete**: User can delete the server configuration.
**Note** All servers cannot be inactivated at the same time. At any point of time, at least one server should be in Active state.
# Managing Licenses
## Overview
This section covers how to install new licenses, renew licenses and uninstall licenses.
The License Management option will be shown under the Administration drop-down.
space.vars.OIM **UI Notifications**
* On space.vars.OIM, upon login, upcoming license expiry warning notifications will be shown for each license starting 60 days till its expiry date. **Note** : No additional configuration is required to enable the same.
* **Mail Notifications**
* To get mail notifications regarding each upcoming license expiry, the SMTP mail server notifications can be configured
* Refer to [Creating SMTP System](/help-center-index/troubleshooting-index/configure-post-failure-notification#smtp-configuration) for creating an SMTP system.
* SMTP Mail Client system must be created in space.vars.OIM and configured in **OpsHub System** under **SMTP System For Notification**.
space.vars.OIM is down) license expiry notification doesn't come, it will be logged in space.vars.OIM logs.
## Uninstall License
* Navigate to the Administration section and select **License Management** from the drop-down options.
* You will see the **Licenses** screen.
* Click the cross icon against the License name which you want to delete.
space.vars.OIM works best with the following browsers: Google Chrome, Mozilla Firefox, and Safari.
## Known Behaviour
* When multiple valid licenses are installed, feature availability is determined by the latest generated license. This license is treated as the active license for feature validation.
* If a newly installed license does not include features that were available in a previously installed license, those features will no longer be available, even if the older license remains installed and valid.
* Before installing a new license, review the feature differences carefully. A warning message will be displayed if the new license contains fewer features than the currently active license.
# Proxy Settings
You need to configure proxy settings to be able to access the external resources from the machine which is behind a proxy server or when space.vars.OIM is behind a proxy server.
## How to Configure Proxy Settings
Watch the following video to learn how to configure proxy settings:
> **Note:** This video has no audio.
{% embed url="space.vars.OIM won't allow you to use the same name for registering the connector.
## View Connectors
* The registered connectors are available in the form of list on the "Registered Connectors" page as shown in the image below:
* There is an audit icon  present on the top right corner of the list. Clicking this icon will show all the audits related to the registered connectors.
## Edit Connectors
* Registered connectors can be edited by clicking the specific connector followed by clicking the pencil icon on the top right corner of the page.
* You can edit the system name, add or remove URLs. There is also a check box in case you want to refresh the metadata of the connector.
> **Note** : Edit register connector option will not allow you to remove the URL if it is already used in any system or in the integration of the systems. An error message will be displayed in case the URL that is already in use is deleted.
### Refresh Connector Metadata
Refresh Connector Metadata checkbox (as shown in the image above) can be selected under the following condition:
* Whenever there is any change (addition or deletion) of metadata in the connector.
While editing the connector, if the refresh connector metadata is checked, a warning pops up as shown in the image below:
space.vars.OIM helps users clean up old or unnecessary data associated with integration configuration changes or previously synchronized records.
* Following are the types of **Purge** provided:
* **Audit Logs**: It enables users to purge different types of change logs, such as **Excel upload audits**, **Job schedule audits**, **Roles audits**, etc. Refer to the [Purge Audit Logs](#purge-audit-logs) section for more details.
* **Integrated Data Records**: It enables users to purge integrated data records from the space.vars.OIM database. Refer to the [Purge Integrated Data Records](#purge-integrated-data-records) section for more details.
### Steps to access the Purge Feature
* Navigate to the top-right corner of the screen and click **Administration**.
space.vars.OIM user interface, eliminating the need for standalone SQL utilities.
* This improves usability and accessibility and simplifies the cleanup process.
* This feature is especially useful in **re-sync** or **re-migration** scenarios, where previously synchronized data needs to be purged before initiating a new sync.
* Users can filter and control purge operations based on the following:
1. **System Pair:** Select the source and target systems involved
2. **Integration Groups:** Choose from configured integration groups between the selected systems
3. **Entity Type Pairs:** Choose from configured entity type mappings within the integration group
### Prerequisites
#### User privileges
Following are the privileges required for the dedicated space.vars.OIM user to purge synchronized entities:
**Required role**
| **Role Name** | **Required in** |
| ------------------- | --------------- |
| Super Administrator | Administration |
| Sync Monitor | Integration |
**Minimum required permissions in case of customized roles**
| **Permissions Name** | **Permissions Scope** |
| --------------------------------------------- | --------------------- |
| Administration Permissions: Server Management | Delete |
| Integration Permissions: Integration | Action |
Refer to the [Permissions and Corresponding Actions](/manage/administrator/user-access-control/role-configuration#permissions-and-corresponding-actions) section to understand which operations can be performed based on the configured role.
#### License requirement
* Users with either a 'Professional' or 'Ultimate' license have access to the **Purge Integrated Data Records** feature.
#### Purge usage guidelines
* For **configured integrations**:
* Integrations must be **inactivated** before purging their synchronized records.
* **Reason:** Purging data from an active integration can accidentally remove information that is still in use or currently being synchronized. This may result in processing failures or even impact other active integrations.
* For **deleted integrations**:
* Purge operations are also supported for **deleted integrations**, allowing removal of previously synchronized records and related data from the database.
* **Important:** Ensure that the **issue type(s)** configured in the deleted integration are **not used in any existing integration** with the same system and scope.
* If they are still in use, the purge will fail with an error, as illustrated in the image below.
space.vars.OIM directory, `@INSTALLATION_PATH@\AppData\PurgedRecords` and kept permanently unless manually removed.
Click on **Purge** to purge the selected records from the **OpsHub** database.
### Important Purge Behaviors and Considerations
#### End System Data Not Cleaned Before Purging
* Before purging records from space.vars.OIM, make sure the synced data is also deleted or archived in the target (end) system.
* If the end system still holds the data, space.vars.OIM will lose reference to it after purge.
* Upon reactivating the integration, space.vars.OIM will treat the existing entities in the end system as new, resulting in:
* Duplicate records
* Orphaned entities
* Data inconsistencies and potential sync conflicts
#### Replication of Source Data to Multiple Target Systems
* When you purge data from a source system that is used in multiple integrations, it impacts **all integrations connected to that same source**.
* This is because the purge removes shared information these other integrations will also need to resynchronize data using correct target lookup settings.
* This scenario requires additional configuration of target lookup to ensure consistent and conflict-free data across all target systems.
* For example:
* Source entity: **Bug**
1. Integration A: **Jira → Rally**, "Bug" → "Defect".
2. Integration B: **Jira → ServiceNow**, "Bug" → "Problem".
* If you purge data for **Integration A** only, you must:
* Either **purge Integration B** as well,
* Or **update the target lookup** in Integration B to make sure data is re-synced correctly and without conflicts.
#### Data Recovery and Audit Trail
* All purged records are automatically saved as CSV files in the space.vars.OIM installation directory: `@INSTALLATION_PATH@\AppData\PurgedRecords`
* Each purge operation generates a unique timestamped file, maintaining a complete audit trail of all cleanup operations.
* These logs are kept permanently unless explicitly deleted.
#### Selective Purging Based on Filters
* If no specific integration or entity type filters are applied, space.vars.OIM purges data for **all configured integrations and entity types** between the selected source and target systems.
* **Warning:** Use with caution, broad scope purging to avoid removing unintended data.
#### REST API implementation
* Purge Integrated Data Records is **not supported with REST APIs**.
* This is to prevent accidental data loss, as API-based purging would skip important warnings and confirmation steps visible in the UI.
# Rules Management
## View Rules
To view Rules, go to Administration > Rules Management. This would lead to a page that lists multiple rules that are already configured for different systems integrated using space.vars.OIM.
space.vars.OIM is by default deployed with 4 GB memory, but if that needs to be changed then refer to the section below.
## Memory Configuration File
From version 7.4 onwards, there is a configuration file **OIM\_Config.properties** added in space.vars.OIM.
You can find this configuration file under the `space.vars.OIM Installation Path>/AppData/OpsHubData` directory.
**OIM\_Config.properties** file contains the server memory parameters that can be configured.
## How to Increase Server Memory
1. From `services.msc`, stop the `Opshub Server Service`.
2. Open the command prompt with administrator privileges, and:
1. Navigate to `space.vars.OIM Installation Path>/OpsHubServer/bin` directory.
2. Run `unregisterservice.bat`. This will remove the `Opshub Server Service`.
3. From Windows Explorer, go to `space.vars.OIM Installation Path>/AppData/OpsHubData` directory and open `OIM_Config.properties` file using any text editor.\
In this file, there will be default memory settings for the server as `Xms=1024m` and `Xmx=4096m`.\
Minimum recommended memory parameter configuration is `Xms=1024m` and `Xmx=4096m` but depending on space.vars.OIM instance load/configuration, these parameters may need to be increased.
* Format for memory parameter is like, `Xms=space.vars.OIM Installation Path>/OpsHubServer/bin` directory.
1. Run `registerservice.bat`. This will register the `Opshub Server Service` with configured parameters in `OIM_Config.properties` file.
5. From `services.msc`, start the `Opshub Server Service`.
# Configure Socket Timeout
* Socket Timeout is the amount of time for which space.vars.OIM will wait for an API response after making an API request.
* Sometimes, the end systems do not respond within the predefined time period, which cause **SocketTimeoutException** failure in the sync. In such cases, it is recommended to update the socket timeout parameter in space.vars.OIM.
* space.vars.OIM is by default deployed with socket timeout set to 30 minutes. However, if the above mentioned failure is observed in the sync, to change the value of the socket timeout parameter, refer to the section below.
## How to Configure Socket Timeout
1. From services.ms, stop the 'OpsHub Server Service'.
2. Open the command prompt with administrator privileges.
1. Navigate to "`space.vars.OIM Installation Path>`/OpsHubServer/bin" directory.
2. Run **unregisterservice.bat**, to remove the 'OpsHub Server Service'.
3. If user wants to configure the socket timeout for **OpsHubTFSService**:
1. From Windows Explorer, go to "`space.vars.OIM Installation Path>`/OpsHub\_Resources/config" and open **TFSProperty.properties.sample** file using any text editor. In this file, there will be default socket timeout settings for the **OpsHubTFSService** as **serviceRequestTimeOutInMinutes=1440**.
2. The format for socket timeout parameter is **serviceRequestTimeOutInMinutes=**`space.vars.OIM Installation Path>`/AppData/OpsHubData" directory and open **OIM\_Config.properties** file using any text editor. In this file, there will be default socket timeout settings for the server as **http.socket.timeout=1800000**.
2. The format for socket timeout parameter is, **http.socket.timeout=**`space.vars.OIM Installation Path>`/OpsHubServer/bin" directory.
1. Run **registerservice.bat**, to register the 'OpsHub Server Service'.
6. From services.ms, start the 'Opshub Server Service'.
# Scheduler
All the users in space.vars.OIM, who have a 'Professional' or 'Ultimate' license , will have access to 'Job Schedules' \[which are associated with the integrations].
## Create Schedules
To create a new schedule, follow the steps given below:
* Click on **"Administration"**
* Click on  given on the left panel. You can see the list of schedules that are already created
* To create a new schedule, click on  given on the top right corner of the screen
visitor.claims.unsigned.product**'s `space.vars.OIM.
| **Log File Name** | **Description** |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| DatabaseCreation.log | Log generated during Database Creation phase of Installation |
| Install.log | Log related to installation steps |
| OpsHubServer.log | Log generated while visitor.claims.unsigned.product Installation (like launching URL). |
| Service.log | Log generated while registering visitor.claims.unsigned.product Application as Service. |
| ConnectionModeConf.log | Log related to the Connection Mode Configuration. |
| OpsHub.log | visitor.claims.unsigned.product Application log file for all the migrations/integrations |
| OpsHubTFSService.log | Common log file for TFS API interaction |
| Integrations | Folder contains the files for the logs of each migrations/integrations |
{% if "OM4ADO" !== visitor.claims.unsigned.product && "OAM" !== visitor.claims.unsigned.product %}
## Log Settings
System log helps to view logs for tracking backend activity in space.vars.OIM. Usually logs are useful when any failure or unusual behavior is detected in integration. System log can store logs in 5 different levels. Logs will capture information based on logging level set in System log.
To navigate to System log
* Click on Administration on top right corner.
* On Left panel click on Global log as shown below
## Settings
Click on Setting button on System log window to configure log settings as mentioned below
## Integration Log Setting
**Class/Package Name:** The name of the package or class for which logs need to be monitored. To monitor the logs within the 'com.opshub', package 'com.opshub' should be entered here.
**Log Level:** Represents the logging level which determines the amount of information recorded in the log files. By default, only Error logged in space.vars.OIM are logged in logs. The coverage of information increases in ascending order from logging level 1 to 6.
1-FATAL, 2-ERROR, 3-WARN, 4-INFO, 5-DEBUG, 6-TRACE
1-FATAL will log minimum amount of data, not sufficient for tracking integrations, while 6-TRACE will log maximum data, most useful for tracking integration but it also creates log sizes and creates multiple log files due to amount of information logged.
**No. of Lines:** Number of lines of logs to be displayed on the log viewer screen of the UI.
**No. of max backup log files:** Maximum number of backup files to store excluding the current log file used by the integration.
**Size of log file \[MB]:** Maximum size (in MB) that an integration log file can have before a new backup log file is created.
**Reset all integrations to global log settings?:** This option reverts all individual/custom log settings for each integration to the global/default log configuration defined at the system level. Any integration-specific overrides will be removed.
## Global Log Setting
**No. of max backup global log files:** Select the maximum number of backup files to store, excluding the current log file used by the UI logs.
**Location to save logs:** Location where log files should be saved, this should be configured if default directory where space.vars.OIM is installed do not have sufficient space to store log files. By default, logs are stored in default directory where space.vars.OIM is installed.
* If you change the default location to another location, all the older logs will be copied to the updated location, except for Tomcat Server logs. The new logs will be logged at the updated location.
**Size of global log files \[MB]:** Select the maximum size (in MB) that a UI log file can have before a backup log file is created.
**Compress Backup Log Files:** Enable the toggle button to store all the backup log files in **compressed(.zip)** format.
> **Note**: Following points should be considered:
* When the toggle button for 'Compress Backup Log Files' is enabled or disabled, ensure that no other application is using the backup files.
* When the toggle button for 'Compress Backup Log Files' is enabled or disabled, ensure to configure the values for 'No. of max backup global log files' and 'No. of max backup log files' appropriately.
## Refresh Log
**Refresh log** button on the top of window can be used to refresh logs once to display latest logged data.
**Auto Refresh Log** is a toggle button, it can be set on to automatically refresh logs in every few seconds (2-3 seconds).
## Export Logs
Click on Export logs button to export logs as zip file.
## Word Wrap
Click on Word Wrap to enable/disable the word wrapping behavior in the log viewer.
* Word wrap is enabled by default.
* When word wrap is enabled, long log entries are wrapped, making them easier to read without horizontal scrolling.
* When word wrap is disabled, log entries remain on a single line, preserving the visual alignment of timestamps and structure. However, horizontal scrolling may be needed.
{% endif %}
# User Access Control
[Role Configuration](/manage/administrator/user-access-control/role-configuration)
[User Role Association](/manage/administrator/user-access-control/user-role-association)
# User Role Association
## Overview
* space.vars.OIM allows to associate roles with users defining what actions a user can perform.
* One user can have multiple Integration and Administration Roles. The permissions available to that role will be a union of permissions associated with all individual roles.
* Only users with permission **Permission Grant** can associate roles with users.
* Roles can be associated with user from **View associated roles** button in rightmost column against a given user.
## Associating Administration Role to a User
* Navigate to user role association screen and click on edit icon in top right corner.
* Select roles to be associated with given user. Refer to [Permissions and Corresponding Actions](/manage/administrator/user-access-control/role-configuration#permissions-and-corresponding-actions) section to understand which operations can be performed based on the configured role.
* Under the drop down list, only Administration roles will be available.
* For instance, if Sync Administrator role is to be associated with user 'David Smith', it can be selected under Administration as shown below:
* Click on **Save** button to save user role association.
## Associating Integration Role to a User
* Navigate to User Role Association screen and click on edit icon in top right corner as shown below:
* Select roles to be associated with the given user. Refer to [Permissions and Corresponding Actions](/manage/administrator/user-access-control/role-configuration#permissions-and-corresponding-actions) section to understand which operations can be performed based on the configured role.
* Under the drop down list, only Integration roles will be available.
* Here, roles can be assigned folder-wise.
* Permissions' Inheritance in Child Hierarchy:
* Roles associated with given folder would be inherited in entire child hierarchy of that folder.
* Associating roles in the child folder will override roles of parent folder.
* Assigning any role in a given folder indicates that user will have **Read** access to all integration resources in that folder and its child hierarchy as well.
* Assigning any role with **Read** access to integration or mapping in a child folder indicates **Read** access to all associated mappings and systems in the parent folder.
* For above configuration, the user will be able to perform the following operations:
| **Folder** | **Actions supported** |
| ------------------------ | ------------------------------------------------------- |
| Default/Parent 1 | All actions associated with **Sync Monitor** role |
| Default/Parent 1/Child 1 | All actions associated with **Sync Monitor** role |
| Default/Parent 1/Child 2 | All actions associated with **Sync Monitor** role |
| Default/Parent 1/Child 3 | All actions associated with **Sync Administrator** role |
| Default/Parent 2 | All actions associated with **Sync Administrator** role |
# Role Configuration
## Overview
space.vars.OIM supports User Access Control, enabling users manage permissions in space.vars.OIM by associating users with specific roles. Each role encapsulates a set of permissions suited to particular responsibilities.
## Permission
Permission refers to specific rights like Read, Write, Delete, Grant on different resources like System, Mapping, Integration, User Management associated with a given role.
## Role
* A Role is a set of permissions that define what actions a user is permitted to perform on a resource.
* Integration Role:
* An Integration role allows user to configure permissions for operations that can be performed on **Integration** tab in space.vars.OIM like System, Mapping, Integration, etc.
* Refer to [Associating Integration Role to a User](/manage/administrator/user-access-control/user-role-association#associating-integration-role-to-a-user) section to understand how integration roles can be associated with user.
* Administration Role:
* An Administration role allows user to configure permissions for operations that can be performed on **Administration** in space.vars.OIM tab like Proxy Settings, License Management, etc.
* Refer to [Associating Administration Role to a User](/manage/administrator/user-access-control/user-role-association#associating-administration-role-to-a-user) section to understand how administration roles can be associated with user.
## Default Roles
space.vars.OIM provides with the following default roles:
| **Role Name** | **Description** |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Super Administrator | All administration permissions are available
|
| Sync Administrator | All integration permissions are available
|
| Sync Monitor | All read and sync action permissions are available
|
## Create Custom Roles
* Navigate to **Role Management** screen under **Administration** tab and click on Create Role button on the top right corner as shown below:
* Add Role Name, Description, Type and select permissions that a user want to associate with the role. For instance, if a role is to be configured for performing all system operations, select **Integration** under Role type and tick mark **write** permission checkbox as shown below:
* Save the role and it will be accessible from **Role Management** screen as shown below:
## Standard Role Behaviors
* In Integration type role, **read** permission is granted by default on all resources like System, Mapping, Folder, etc.
* In Integration type role, with **Write** permission, **Action** permission is granted by default for **Integration**.
* Default roles cannot be edited or deleted.
* In Administration type Role, with **write** permission on **User Management**, all write operations can be performed in all user accounts.
* Role type cannot be changed after the role is created.
## Permissions and Corresponding Actions
* Permissions and operations that can be performed are listed below:
| **Permission Name** | **Permission Scope** | **Actions Supported** |
| -------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration Permissions** | | |
| Folder | Read | Read Folders |
| Folder | Write | Create, update, delete folders |
| Folder | Grant | Allows user to manage integration permissions of other users on the folders on which the user has access |
| Integration | Read | Read integrations, reconciliations, failures
Export sync report
Read failure notifications' configuration
|
| Integration | Write | Create, update, delete, merge, move integrations
Create, update reconciliations
|
| Integration | Action | Failures: Retry, delete, edit event xml, configure failure notifications
Integrations: Activate, inactive, execute
Delete Synchronization: Execute
Switch to integration mode (from reconciliation)
|
| Mapping | Read | Read, import, export mappings
Read, export excel uploads
|
| Mapping | Write | Create, update, delete, clone, merge, move mappings
Create, update, delete excel uploads
|
| System | Read | Read systems |
| System | Write | Create, update, move systems |
| Workflow | Read | Read, export workflows |
| Workflow | Write | Create, update, move, delete workflows |
| *Note:* Move operation requires **write** permission in both source and destination folders. | | |
| **Administration Permissions** | | |
| User Management | Read | Read users
Read login servers
|
| User Management | Write | Create, update users
Create, update login servers
|
| Server Management | Read | Read licenses
Read proxy settings
Read registered connectors
Read system logs
Read purge
Read rules management
Read schedule
|
| Server Management | Write | Install license
Update proxy settings
Create, update registered connectors
Create, update rules management
Create, update schedules
|
| Server Management | Delete | Uninstall License
Apply purge
Delete rules management
Delete schedules
|
| Permission Management | Read | Read roles |
| Permission Management | Write | Create, update roles |
| Permission Management | Delete | Delete roles |
| Permission Management | Grant | Grant permissions to other users |
# Advanced Utilities
1. [Migrating Database](/manage/advanced-utilities/database-migration)
2. [Updating Database Password](/manage/advanced-utilities/updating-database-password)
3. [Changing MSSQL Server Host](/manage/advanced-utilities/how-to-change-mssql-database-server-host)
4. [Switching to Windows authentication](/manage/advanced-utilities/switching-to-windows-authentication-mode-for-mssql-server)
{% if "OM4ADO" !== visitor.claims.unsigned.product && "OAM" !== visitor.claims.unsigned.product %}
5\) [Usage Report Manual](/manage/advanced-utilities/usage-reports)
6\) [Change Keystore and Private Key passwords](/manage/advanced-utilities/change-keystore-and-private-key-passwords)
7\) [Secret Key Reset Utility](/manage/advanced-utilities/regenerate-secret-key)
8\) [Certificate Private Key Password Encryptor Utility](/manage/advanced-utilities/certificate-private-key-password-encryptor-utility)
9\) [Data Count Utility](/manage/advanced-utilities/data-count-utility)
10\) Encrypt Password Utility
{% endif %}
# Usage Report Manual
## Overview
The **Usage Reports** feature enables administrators to export detailed system usage data for analysis and licensing purposes. Reports can be downloaded directly from the **Licenses screen** or through the **Admin API**, providing a convenient and efficient way to access usage information.
The exported report is provided as a **Usage Reports.zip** file, which contains two Excel reports:
* **Usage Report (Last 6 Months)**
* **Usage Report (Last 1 Year)**
Each report includes both **summary and detailed insights** about activity across integrated systems. The reports provide information such as unique users, integrated projects, integrated entity types, synced data, and detailed information about processed users across systems.
User activity is captured across multiple interaction points, including mapped user fields, comments, attachments, user mentions, and updates. This helps provide a comprehensive view of system usage and user interactions across integrations.
These reports help administrators review usage patterns, monitor integration activity, and obtain the necessary insights for operational analysis and licensing purposes.
***
## Prerequisites
To access and download the reports, the user must:
* Have an **Administrator role**
* Have **Read permission for Server Management**
***
## Download Usage Reports
### Using UI
Follow these steps to download the usage reports from the application:
1. Navigate to the **Licenses** screen.
2. Locate the **Export Usage Reports** button on the screen, as shown in the image below. The button is highlighted with a red rectangular box.
3. Click the **Export Usage Reports** button.
4. The **Usage Reports.zip** file will be downloaded to your browser’s default download location.
5. Extract the ZIP file to access the reports.
### Using Admin API
Administrators can also download the usage reports using the Admin API.
**Endpoint** GET `/export/usage-reports`
**Response**
* Returns the **Usage Reports.zip** file.
***
## Contents of the Downloaded File
After extracting **Usage Reports.zip**, the following files will be available:
* `Usage Report (Last 6 Months).xlsx`
* `Usage Report (Last 1 Year).xlsx`
Each Excel report contains the following sheets:
1. `Summary`
2. `Unique User Count`
3. `Entity Type Count`
4. `Integrated Project Count`
5. `Synced Data Count`
6. `Detailed User Report`
### Summary Sheet
This sheet provides an overall summary of all the reports included in the Usage Reports. It gives a quick overview of key metrics, allowing administrators to quickly understand system usage and user activity.
#### Example
#### Explanation of Metrics
* **Total Unique Users** – Displays the total number of unique users observed across all systems, with a breakdown based on available identifiers such as emails, display names, and usernames.
* **Total Unique Entity Types** – Shows the total number of different entity types involved in synchronization across the systems.
* **Total Unique Projects** – Represents the total number of integrated projects observed during the selected period.
* **Total Entities Synced** – Counts all entities that were successfully synchronized between systems.
This summary sheet provides a **high-level overview of system usage**, allowing administrators to quickly assess usage from a single sheet instead of reviewing each detailed report individually.
***
### Unique User Count Sheet
Displays the total number of unique users identified across integrated systems, along with a system-wise breakdown.
#### Explanation of Columns
* **System / Source** – The system where the users were detected.
* **Count** – Total number of unique users identified in the system.
* **Identifiers** – Breakdown of how users were identified, following a **priority order**:
1. **Usernames or Emails** – Users matched using **username or email** when both fields are available. If either username or the local part of email (case-insensitive) matches an existing user, it is considered the same user. **This is the highest priority.**
2. **Emails** – Users identified **by email only** when no match was found using username or username/email combination in the first step.
3. **Display Names** – Users identified by display name if no email is available.
4. **Usernames** – Users identified by username if both email and display name are empty.
This information helps administrators understand how user identities are detected and matched across different integrated systems.
#### Example
***
### Entity Type Count Sheet
Displays the entity types involved in synchronization across system pairs during the selected period.
#### Explanation of Columns
* **System Pairs** – The pair of systems involved in synchronization.
* **End System** – The system where the entity resides or is synced to.
* **Entity Types** – The types of entities synced between the systems.
* **Status** – The current status of the integration (Active or Inactive).
* **Last Synced** – The most recent timestamp when the entity was successfully synced.
***
### Integrated Project Count Sheet
Lists the unique project pairs that were involved in integrations during the selected timeframe, along with their status and last updated time.
#### Explanation of Columns
* **End System 1 / End System 2** – The source and target systems involved in the integration.
* **End System 1 Project / End System 2 Project** – Source and target projects participating in the integration.
* **Status** – The current status of the integration (Active or Inactive).
* **Last Updated** – The timestamp when the integration was last updated.
* **Last Synced** – The timestamp when the last entity was successfully synced between the project pair.
This table provides a **clear view of project-level integrations**, helping administrators monitor integration activity and identify inactive or outdated integrations.
***
### Synced Data Count Sheet
Displays the total number of entities successfully synchronized between integrated system pairs.
#### Explanation of Columns
* **End System 1 / End System 2** – The source and target systems between which entities are synchronized.
* **Counts Based on System Pair** – The total number of entities successfully synced between the two systems.
* **Last Synced** – The most recent timestamp when entities were fully synchronized.
***
### Detailed User Report Sheet
The **Detailed User Report** sheet provides comprehensive information about each observed user across integrated systems.
The report includes the following information:
* **Email** – User email address
* **Username** – Username of the user
* **Display Name** – Display name of the user
* **Interaction Types** – Areas where the user was detected (such as comment authors, attachment authors, mapped user fields, mentions in rich text fields, etc.)
* **Observed In** – Systems where the user was detected, along with timestamps
* **Service Account** – Indicates whether the user is used as a service account
* **Last Seen** – The last observed activity time of the user in the system
* **Duplicates** – Identifies users with matching email IDs but different usernames across systems
# Migrating Database
Please refer to [Database Prerequisites](/getting-started/prerequisites#database-prerequisites) before proceeding with the migration details.
### Introduction
As HSQL is not suitable for production usage, space.vars.OIM needs to be migrated to one of three databases supported by space.vars.OIM. There is a utility provided with space.vars.OIM installation and packaged in space.vars.OIM's `\OpsHub_Resources\DatabaseMigrator` directory \[Migrator directory].
### Steps to migrate from HSQL to other supported databases
* Keep driver for database for which migration needs to be done in: space.vars.OIM's `\OpsHubServer\lib` directory.
* For MySQL connector driver jar 5.1.8 is not supported, hence the latest connector driver jar should be used from
* Change `destinationconnection.properties` and `sourceconnection.properties` in Migrator directory:
* **sourceconnection.properties**: Change `CONNECTION_HSQL_FILE_PATH` property and replace `` with installation path
* **destinationconnection.properties**: Provide all properties value as guided in file.
{% if "OM4ADO" === visitor.claims.unsigned.product %}
* Close OM4ADO application.
{% endif %}
{% if "OM4ADO" !== visitor.claims.unsigned.product && "OAM" !== visitor.claims.unsigned.product %}
* Shut down server (ensure service is not running if registered).
{% endif %}
* Take back up of database
Refer to Database Backup section on [Taking Application Backup](/manage/upgrade-index/taking-application-backup) page for details.
### Migrating on Windows
Run `migrator.bat` in Migrator directory
{% if "OM4ADO" !== visitor.claims.unsigned.product && "OAM" !== visitor.claims.unsigned.product %}
### Migrating on Linux
Run `migrator.sh` in Migrator directory\
If file execution fails with ^M bad interpreter error, use following steps:
* Execute command in terminal `dos2unix migrator.sh`
* Now execute the sh file in terminal `migrator`
{% endif %}
### Steps to perform after successful migration
Following are the steps to be performed after successful database migration:
* Go to space.vars.OIM's `\OpsHubServer\webapps\OpsHubWS\META-INF` directory
* Delete `war-tracker` file
* Go to space.vars.OIM's `\OpsHubServer\webapps\OpsHubWS` directory
* Select all the files and add to archive with name `OpsHubWS.zip`
* Rename `OpsHubWS.zip` to `OpsHubWS.war`
* Go to space.vars.OIM's `\OpsHubServer\webapps` and replace newly created `OpsHubWS.war` with the existing one
* Delete space.vars.OIM's `\OpsHubServer\webapps\OpsHubWS` directory and start the service.
# Updating Database Password
If space.vars.OIM database password has been modified by a user, then this utility would update the new password in space.vars.OIM application.
Follow the steps given below for updating database password in OpsHub:
{% if "OM4ADO" !== visitor.claims.unsigned.product && "OAM" !== visitor.claims.unsigned.product %}
* Stop OpsHub Server/ Service before execution of this utility.
{% endif %}
{% if "OM4ADO" === visitor.claims.unsigned.product %}
* Close OM4ADO application before execution of the utility.
{% endif %}
* Go to space.vars.OIM Installation Folder>/Other\_Resources/Resources.
* Unzip `OpsHub Database Management utility.zip`.
* Run `OpsHubDatabaseManagementUtility.bat` for Windows system.
{% if "OM4ADO" !== visitor.claims.unsigned.product && "OAM" !== visitor.claims.unsigned.product %}
* In case of Linux system, run `OpsHubDatabaseManagementUtility.sh`.
{% endif %}
- Enter path for OpsHub Installation Directory.
* Enter the new database password.
* This would update database password in OpsHub application.
# Changing MSSQL Server Host
{% if "OM4ADO" === visitor.claims.unsigned.product %}
* Close OM4ADO application before execution of the utility.
{% endif %}
{% if "OM4ADO" !== visitor.claims.unsigned.product && "OAM" !== visitor.claims.unsigned.product %}
* Stop OpsHub Server Service before execution of the utility.
{% endif %}
* Go to space.vars.OIM's `/Other_Resources/Resources`
* Unzip `HostChange.zip`
{% if "OM4ADO" === visitor.claims.unsigned.product %}
* Open Command Prompt with administrator privileges and go to space.vars.OIM's directory `/Other_Resources/Resources/HostChange` using command **`cd /Other_Resources/Resources/HostChange`**
{% endif %}
{% if "OM4ADO" !== visitor.claims.unsigned.product && "OAM" !== visitor.claims.unsigned.product %}
* Open Command Prompt with administrator privileges and go to space.vars.OIM's directory `/Other_Resources/Resources/HostChange` using command **`cd /Other_Resources/Resources/HostChange`**
{% endif %}
* Run `HostChange.bat` for Windows system.
{% if "OM4ADO" !== visitor.claims.unsigned.product && "OAM" !== visitor.claims.unsigned.product %}
* In case of linux system, run `HostChange.sh`
{% endif %}
- Enter the path for space.vars.OIM's Installation Directory
### HostChange with MYSQL
* Enter the new Host Name for MYSQL:
* If the Host Name input is not entered in the above step, then user will get the notification mentioned in the screen shot below. As the Host Name is a mandatory input that defines the new Host Name you want space.vars.OIM database to refer to:
* Enter the Port for MYSQL:
* If the Port input is not entered in the above step, then utility will use the existing Port \[entered at a time of space.vars.OIM installation]. If that is not the case, then enter the Port here:
* Utility will check the connection with new Host Name:
### HostChange with ORACLE
* Enter the new Host Name for ORACLE:
* If the Host Name input is not entered in the above step, then user will get the notification mentioned in the screen shot below. As the Host Name is a mandatory input that defines the new Host Name you want space.vars.OIM database to refer to:
* Enter the Port for ORACLE:
* If the Port input is not entered in the above step, then utility will use the existing Port \[entered at the time of space.vars.OIM installation]. If that is not the case, then enter the Port here:
* Utility will check the connection with new Host Name:
### HostChange with MSSQL Server
* **Note**: If space.vars.OIM is installed with Windows Authentication mode, then before running the utility, the user needs to make sure that the user who is logged into the Windows \[where the space.vars.OIM is installed] also logs into the new host's MSSQL instance with the same credentials.
* Enter the new Host Name for MSSQL Server:
* If the Host Name input is not entered in the above step, then user will get the notification mentioned in the screen shot below. As the Host Name is a mandatory input that defines the new Host Name you want space.vars.OIM database to refer to:
* If the new Host Name is a named instance, then there is no input required for the Port. Hence, after entering the Host Name, utility will check the connection with the new Host:
* If the new Host Name is a non-named instance, then enter the Port for MSSQL:
* If the Port input is not entered in the above step, then utility will use the existing Port \[entered at the time of space.vars.OIM installation]. If that is not the case, then enter the Port here:
* Utility will check the connection with new Host Name \[In the case of SQL Authentication]:
* Utility will check the connection with new Host Name \[In the case of Windows Authentication]:
### HostChange with PostgreSQL
* Enter the new Host Name for PostgreSQL:
* If the Host Name input is not entered in the above step, then user will get the notification mentioned in the screenshot below. The Host Name is a mandatory input that defines the new Host Name user wants space.vars.OIM database to refer to:
* Enter the Port for PostgreSQL:
* If the Port's input is not entered in the above step, then the utility will use the existing Port \[entered at the time of space.vars.OIM installation]. If that is not the case, enter the Port as shown in the screenshot below:
* Utility will check the connection with the new Host Name:
# Switching to Windows authentication
Please go through the section [Installation Prerequisites](/getting-started/prerequisites#windows) for Windows Authentication mode before executing steps given below.
Please ensure the Windows user (who is used in MS SQL Windows Authentication) has **Read** and **Write** privileges before executing `databaseManagementUtlity`. You can grant the **Read** and **Write** privileges by executing the steps given below.
* Open properties window of space.vars.OIM installation folder (directory in which you have installed space.vars.OIM i.e. `c:\Program Files\OpsHub`), it will show you the dialogue box shown below.
* Select the user (to whom you want to grant privileges) from the Security tab and check Read and Write checkbox.
* Click OK after checking the Read and Write checkbox.
If the database is on MSSQL SQL Authentication mode and you need to switch to Windows Authentication mode, then follow the steps given below:
* Go to `/Other_Resources/Resources`.
* Unzip `OpsHub Database Management utility.zip`.
* Run `DatabaseManagementUtility.bat` for Windows system.
* In case of Linux system, run `DatabaseManagementUtility.sh`.
* Enter path for the installation directory.
* Press `2` to switch to Windows authentication mode.
* Provide Microsoft JDBC Driver 4.0 (`tar.gz`) File Path.
* Provide Windows Service Credentials.
> **Note:**\
> If Windows credentials are not added correctly during switching, the OpsHub Server service will not be started.\
> To avoid such an occurrence, the user will have to manually set the service log-on credentials for OpsHub Server Service in case wrong Windows credentials are added at the time of switching.
## Follow the below mentioned steps to set the credentials in the OpsHub Server Services:
1. Open the services application and search for `OpsHub Server Service`.
2. Right-click on the service, select **Properties** and go to the **Log On** Tab.
3. Enter Windows credentials in **This account**.
> If the user is registered with a domain, the username format will be "{username}@{domain}" or "{domain}{username}". Otherwise, the username format will be ".\username".
# Change Keystore and Private Key passwords
In case of HTTPS deployment of space.vars.OIM, if the user wants to change the existing keystore or private key passwords for space.vars.OIM certificate, this utility can be used to change and update the encrypted passwords in space.vars.OIM application.
Follow the steps given below for updating the encrypted keystore and private key passwords in space.vars.OIM:
* Stop OpsHub Server Service before execution of this utility.
* Navigate to `space.vars.OIM Installation Folder>/Other_Resources/Resources`.
* Unzip `"OpsHub Keystore Password Encryptor Utility.zip"`.
* Run `KeystorePasswordEncryptorUtility.bat` for Windows system. In case of Linux system, run `KeystorePasswordEncryptorUtility.sh`.
* Enter the path for OpsHub Installation Directory.
* Enter the keystore password.
* Enter the private key password.
*If the private key input is not entered in the above step, then user will get the notification mentioned in the screenshot below. In this case, the private key password will be considered same as keystore password.*
* It will update keystore and private key passwords in OpsHub application in the encrypted format.
# Secret Key Reset Utility
This utility regenerates Secret Key for application. This can be used in following cases:
* Secret Key is lost.
* Secret Key has been tampered.
* User wants to change secret key for application.
Please follow below given steps for execution of this utility:
* Stop OpsHub Server/ Service before execution of this utility.
* Go to `/Other_Resources/Resources`.
* Unzip `OpsHub Secret key reset utility.zip`.
* Execute `OpsHubSecretKeyResetUtility.bat` / `OpsHubSecretKeyResetUtility.sh` for Windows/Linux respectively.
* Enter path for OpsHub Installation Directory.
* Enter new location for security. (`opshub.key` should not be available on the same location).
* Select Data Encryption algorithm. By default, AES (128) is selected.
* Provide password for database.
* This would generate new key at specified location.
* In case of HTTPS deployment of space.vars.OIM, run [Change Keystore and Private Key passwords utility](/manage/advanced-utilities/change-keystore-and-private-key-passwords) to store the passwords in encrypted form.
* Start OpsHub Server/ Service.
* Re-enter passwords for all configured systems, configured database connections, configured proxy settings and overridden passwords in Advance Configuration of Integration.
# Certificate Private Key Password Encryptor Utility
If multiple certificates are imported into the Keystore, and the certificates have different private key passwords, this utility can be used to create a `cacerts_config.properties` file having all the certificate alias names and their passwords in encrypted format. The information in this file would be used to load certificates from Keystore.
Follow the steps given below for creating/updating the `cacerts_config.properties` file:
* Stop OpsHub Server Service before execution of this utility.
* Navigate to `space.vars.OIM Installation Folder>/Other_Resources/Resources`.
* Unzip `OpsHub Certificate Passwords Utility.zip`.
* Run `OpsHubCertificatePasswordsUtility.bat` for Windows system. In case of Linux system, run `OpsHubCertificatePasswordsUtility.sh`.
* Enter the path for OpsHub Installation Directory.
* Enter the certificate alias as shown below:
* Enter the private key password of the certificate with the same alias as shown below:
* Type "y" if more alias entries need to be added. The utility will prompt for alias name and password again. Type "n" if no more entries are required.
* The utility will create `cacerts_config.properties` file with certificate alias names and their corresponding passwords in encrypted format.
* If the `cacerts_config.properties` file already exists, then this utility will not create this file, it will just replace the password for the existing alias or add the new alias and encrypted password in the existing `cacerts_config.properties`.
# Data Count Utility
## Overview
* This utility counts the total number of issues across one or more projects. It supports the following systems:
* **Rally ( Cloud )**
* **Jira ( Cloud, DC: 8.x to 11.x )**
* **OpenText ALM ( 12.x to 24.x )**
* **Helix ALM ( 2021, 2024 )**
* **After Downloading the Utility**
* Once the utility is extracted, the folder will contain the following files:
* **OpshubCountUtility.jar** – The main executable JAR file of the utility.
* **run.bat** – Script to run the utility on Windows systems.
* **run.sh** – Script to run the utility on Linux or macOS systems.
* **propertyFiles** – Directory containing configuration property files.
* **jre** – Bundled Java Runtime Environment.
## Configuration
Configuration should be provided in the respective properties file of the system for which you want to count the issues.
* Locate the **propertyFiles** directory. This directory contains the property files for each supported system:
* **Jira.properties**
* **HelixCoreALM.properties**
* **Rally.properties**
* **OpenTextALM.properties**
* Edit and provide the required configuration details in the property file corresponding to the system for which issue counts need to be calculated.
## Steps to Run Utility
Following are the steps to run the utility:
### STEP 01
* Open **Command Prompt**.
* Refer to the screenshot below:
### STEP 02
* Go to the **directory** where the **Utility** is located.
* Refer to the screenshot below:
### STEP 03
* Type **run.bat** and press **Enter**.
* Refer to the screenshot mentioned below:
Once you press Enter, you will see the screen shown below.
### STEP 04
* Once the welcome screen appears, it will prompt you to enter your email ID.
* Provide the **email ID** and press **Enter**.
* Refer to the screenshot below:
### STEP 05
* After providing the email ID, another screen will appear asking you to enter the system code displayed on the screen.
* Enter the **code** corresponding to the system for which you want to count the issues.
* Refer to the screenshot below:
### STEP 06
The utility will prompt you to enter the system credentials. Provide the credentials for the system you selected.
#### For Rally
Supports two types of authentication modes **Authentication Token** and **Username and Password**.\
Based on the configuration in the **Rally.properties** file:
* If the value of the **rallyAuthType** property is set to 1, the user must provide the **Authentication Token**.
* Refer to the screenshot below:
* If the value of the **rallyAuthType** property is set to 2, the user must provide the **Username and Password**.
* Refer to the screenshots below:
#### For Jira
The utility supports both **Data Center (DC)** and **Cloud** instances for Jira. Users must provide credentials based on the type of instance being used.
* If the instance type is **Cloud**, provide the **email address** as the username.\
If the instance type is **Data Center (DC)**, provide the **username**.
* Refer to the screenshot below:
* Provide the API token for **Cloud** instances, or the Password/API token for **Data Center (DC)** instances.
* Refer to the screenshot below:
#### For OpenText ALM
In the case of OpenText ALM, the user must provide only the Username and Password.
* Refer to the screenshots below:
#### For Helix Core ALM
In the case of Helix, the user must provide only the Username and Password.
* Refer to the screenshots below:
### STEP 07
* Once the user provides all the credentials and presses Enter, a **verification code** will be sent to the registered email ID.
* The user must enter this code to complete the validation process.
* Refer to the screenshot below:
> **Note**: The above steps are explained for Windows OS. For **Linux**, the user should execute the **run.sh** file located in the utility folder and follow the steps mentioned above.
### Output
* Once the utility execution starts and all issue details are fetched, it creates an **output** folder. This folder contains subfolders named **Jira**, **Rally**, etc., based on the system selected by the user.
* Based on the system selected, the execution result will be stored in a data count CSV file. For example, for Jira, the file name will be **Jira\_Count\_Data.csv**.
* The CSV file contains counts of all issues of all issue types based on the project. Refer to the screenshot below:
* In case any issue or error occurs, the utility creates another CSV file containing the error details. This CSV file is generated inside the system-specific output folder located within the main **output** directory.
* For example, if the utility encounters an issue while processing a project for Jira, it will store the error details in the **jira\_error\_report.csv** file.
* Once the utility execution starts, it stores all execution logs in the **app.log** file located in the **OpsHubCountUtility/logs** folder.
# APIs
Getting Started with APIs /pages/2il4e1PNRp7sjFvORaiJ Sample Use Cases and Scripts /pages/rUeOtF36W7W2U2xum4F9 API Capability Matrix /pages/QIKKZBLXCJ363nJ3FdDM
# Getting Started with APIs
## Overview
space.vars.OIM has rich user interface for achieving the integration configurations and using other functionality of space.vars.OIM. However, there can be various cases where the user might need to achieve/use them programmatically, i.e., with the external script, external software program, or with some API client, and space.vars.OIM API is useful in such cases. It is an alternate way to communicate with the space.vars.OIM.
The space.vars.OIM API is organized around REST and uses [JSON](https://www.json.org/json-en.html) format for data exchange.
To have a quick look on the use cases samples and space.vars.OIM API usage examples, please refer to [Use Cases](/manage/api/sample-use-cases).
## Prerequisites
Following are the prerequisites to use space.vars.OIM API:
### Access to space.vars.OIM Instance
* An active instance of space.vars.OIM which needs to be accessible from the machine/[platform](#platforms) for invoking the space.vars.OIM API.
* URL of space.vars.OIM instance. Example: `http://10.13.20.20:8989/OIM/` or `https://10.13.20.20:8443/OIM/`.
* User credentials for accessing the space.vars.OIM instance.
> **Note**: Please refer to [Validate access](#validate-access-to-opshub-integration-manager-instance) for validating this prerequisite.
### API License
* Usage of space.vars.OIM API requires "API" add-on in the space.vars.OIM license.
> **Note**: Please refer to [Validate API feature](#validate-api-feature) to determine whether the "API" feature is enabled or not on your space.vars.OIM instance.
### Platforms
* space.vars.OIM APIs can be invoked from the platform which can make the REST API Calls.
* API client such as [postman](https://www.postman.com/).
* Programs written in any programing language which has support for HTTP or HTTPS communication.
* Command line tool such as [curl](https://curl.se/).
## Access to API
Access to API will be available for your instance with URL like below:
`://space.vars.OIM `instance>:space.vars.OIM is `http://10.13.20.20:8989/OIM/`, then the Swagger UI will be available at `http://10.13.20.20:8989/OIM/rest/api/docs`.
## Appendix
### Validate API feature
To check whether the "API" feature is enabled in the space.vars.OIM or not, please perform the below steps:
1. [Login](/getting-started/logging-in) to space.vars.OIM with the valid space.vars.OIM user credentials.
2. Navigate to the Footer and find "Edition" value.
3. Click on the Edition value of the space.vars.OIM
space.vars.OIM instance
To check whether the space.vars.OIM instance is accessible or not, please perform the below steps:
1. Open space.vars.OIM instance URL from any browser from the machine/platform where space.vars.OIM APIs are invoked.
2. Access the space.vars.OIM instance from browser using the credentials you want to use for space.vars.OIM API communication.
3. If you can successfully login, this prerequisite is met.
> **Note**: If space.vars.OIM is configured on HTTPS, then SSL certificates needs to be imported based on the chosen platform:
* For the API clients like [postman](https://www.postman.com/), there are some [steps](https://learning.postman.com/docs/sending-requests/certificates/) to configure it.
* For the [curl](https://curl.se/) command, this can be [configured using -cert](https://curl.se/docs/manpage.html) option.
* For the programs, the steps will differ based on the expectation of the programming languages in which it was written.
## Known Limitations
1. SAML Users won't be able to login through the API.
* Let's say the user has configured SAML login for OIM UI Login. Such users won't be able to login through the API. It would need either Default or LDAP user.
# Sample Use Cases and Scripts
**Sample Use Cases**
* [Get the project pairs configured in integration(s)](/manage/api/sample-use-cases/use-case-get-all-project-pairs)
* [Integration health details like getting list of active integrations with failures count](/manage/api/sample-use-cases/use-case-integration-healthcheck)
* [Trigger integration execution on demand](/manage/api/sample-use-cases/use-case-execute-integration)
* [Add fields to existing Mapping](/manage/api/sample-use-cases/add-fields-to-mapping)
* [Configure Reconciliation on existing Integration](/manage/api/sample-use-cases/configure-reconcile-on-exisiting-integration)
* [Retrieve and Configure Integration Pair Log Settings](/manage/api/sample-use-cases/retrive-and-configure-integration-pair-log-setting)
# Get the project pairs configured in integration(s)
## Description
* Given two systems, if you want to get the projects in synchronization (for all active integration configured) between those systems, then you can use this sample script.
## Input
* Instance details
* Instance details like space.vars.OIM instance url, username and password are to be given in **instanceDetails.properties** file available within script.
* End Point details (To be given at the time of script execution)
* End Point 1 Id
* End Point 2 Id
## Output
* List of project pairs configured in all the active integrations between the two systems.
## Script
You can download the script from [here](https://opshubtrial-my.sharepoint.com/:u:/g/personal/support_opshub_com/IQCYsYXc54Z8T5HPSFXGPA1FAbbDAjg1vtp7umfq3B21Oo8).
Below is an example of execution for this script.
space.vars.OIM instance url, username and password are to be given in **instanceDetails.properties** file available within script.
* End Point details (To be given at the time of script execution)
* End Point 1 Id
* End Point 2 Id
## Output
* Number of active integrations
* Number of active synchronizations
* Synchronization details like synchronization direction, failure count present in the integration, was there any global error in last cycle?, global error timestamp.
## Script
You can download the script from [here](https://opshubtrial-my.sharepoint.com/:u:/g/personal/support_opshub_com/EcIhGxnr2M9Nt1mK2w-i7ZAB0O2XJ1-Sc8q8OnWYgZqPGg).
Below is an example of execution of script which shows the input and output.
space.vars.OIM instance url, username and password are to be given in **instanceDetails.properties** file available within script.
* End Point details (To be given at the time of script execution)
* End Point 1 Id
* End Point 2 Id
## Output
* List of all active integrations between the two systems that were successfully executed.
## Script
You can download the script from [here](https://opshubtrial-my.sharepoint.com/:u:/g/personal/support_opshub_com/EdaLRfGX_KRAoyYTssd-kswBT1VC_QfpRCwwYMkGhAx7rQ).
Below is an example of execution of script which shows the input and output.
space.vars.OIM instance URL, username and password are to be given in **instanceDetails.properties** file available within script.
* Mapping details (to be given at the time of script execution):
* Mapping id to be updated.
* Internal name of the field of system 1.
* Internal name of the field of system 2.
### Output
* Updated mapping
### Script
You can download the script from [here](https://opshub.com/ohftp/AdminAPI/addFieldsToMapping.zip).
Below is an example of execution of script which shows the input and output:
space.vars.OIM instance URL, username and password are to be given in **instanceDetails.properties** file available within script.
* Integration details (to be given at the time of script execution):
* Integration Group id on which Reconciliation is to be configured.
* Select directional integration id.
* Mapping details (to be given at the time of script execution):
* Select the mapped fields on which Reconcile Rule is to be configured
* Select **Mismatch**, and **Reconcile For** options for each field.
* Reconciliation details (to be given at the time of script execution):
* Workflow id (should be a type of Reconciliation)
* Select the reconciliation status
## Output
* Configured Reconciliation for given fields in an Integration.
## Script
You can download the script from [here](https://opshub.com/ohftp/AdminAPI/configureReconciliationOnExistingIntegration.zip).
Below is an example of execution of script which shows the input and output:
space.vars.OIM instance URL, username and password are to be given in **instanceDetails.properties** file available within the script.
* Integration details (to be given at the time of script execution):
* Integration Group id of the entity pair for which you want to retrieve or modify the logSettings.
* Select Integration entity pair.
* Integration Log Setting details (to be given at the time of script execution):
* Select the jobMode from the available options.
* Enter 'y' to modify the Integration Log Setting configuration.
* Enter 'n' to end the execution.
* Update Integration Log Setting details (to be given at the time of script execution):
* Select the value for As per Global Log Settings.
* If As per Global Log Settings is selected as true, Global Log Settings will be followed.
* If As per Global Log Settings is selected as false, enter the Integration Log Setting configuration details.
## Output
Configured Log Settings for the integration pair.
## Script
You can download the script from [here](https://opshub.com/ohftp/AdminAPI/retrieveandconfigurelogsetting.zip).
Here is an example of execution of script showing the input and the output:
space.vars.OIM. It outlines which operations (Get, Create, Update, Delete, List, Execute) are supported across Integration and Admin modules.
Use this matrix as a quick reference to understand API coverage.
***
## Legend
| Symbol | Meaning |
| ------ | -------------------- |
| ✅ | Available in API |
| ❌ | Not Available in API |
| — | Not Applicable |
***
## Integration
| Feature / Module | Get | Create | Update | Delete | List | Execute | Notes |
| -------------------- | --- | ------ | ------ | ------ | ---- | ------- | ------------------------- |
| System | ✅ | ✅ | ✅ | — | ✅ | — | — |
| System Type | — | — | — | — | ✅ | — | — |
| System Template | ✅ | — | — | — | — | — | — |
| Mapping | ✅ | ✅ | ✅ | ✅ | ✅ | — | — |
| Integration | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | API to get sync log files |
| Workflow | ✅ | ✅ | ✅ | ✅ | ✅ | — | — |
| Folder | ✅ | ✅ | ✅ | ✅ | ✅ | — | — |
| Excel Upload | ✅ | ✅ | ✅ | ✅ | ✅ | — | — |
| Reconcile | ✅ | — | — | — | — | ✅ | — |
| Processing Failure | ✅ | — | ✅ | ✅ | ✅ | ✅ | — |
| Global Failure | ✅ | — | — | ✅ | ✅ | — | — |
| Failure Notification | ✅ | ✅ | ✅ | ✅ | — | — | — |
| Sync Report | — | — | — | — | ✅ | — | — |
| Audits | — | — | — | — | ❌ | — | — |
***
## Admin
| Feature / Module | Get | Create | Update | Delete | List | Execute | Notes |
| ----------------------- | --- | ------ | ------ | ------ | ---- | ------- | ------------------- |
| System Information | ❌ | — | — | — | — | — | — |
| User | ❌ | ❌ | ❌ | — | ✅ | — | — |
| User-Role | ✅ | — | ✅ | — | — | — | — |
| Role | ✅ | ✅ | ✅ | ✅ | ✅ | — | — |
| SDK | ✅ | ✅ | ✅ | — | ✅ | — | — |
| Scheduler | ✅ | ✅ | ✅ | ✅ | ✅ | — | — |
| Log Setting | ✅ | — | ✅ | — | — | — | — |
| Usage Report | ✅ | — | — | — | — | — | — |
| Trends Dashboard | ✅ | — | — | — | — | — | — |
| Login Server Management | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | — |
| License | — | — | — | — | — | — | Not there by design |
| Purge | — | — | — | — | — | — | Not there by design |
| Rules | — | — | — | — | — | — | Not there by design |
# MCP Server
| Get Started | /pages/cLSPWRZ3wLbX8cztdoG6 |
| Configuration | /pages/Gqx3GCMgGFWVkoaKUB9A |
| Available Tools | /pages/ltKrkSC5trGJnyvzCdXr |
| MCP Capability Matrix | /pages/oPxrNrW8f7It28CP6HiF |
| Sample Use Cases | /pages/4VfirohKVp3ty4v0kLQ1 |
| Known Behaviours and Limitations | /pages/lC07eg85W2yA4dDKsfXZ |
| Troubleshooting | /pages/ziOnmevr0th7LA4V6RAb |
space.vars.OIM MCP (Model Context Protocol) server connects your AI assistant directly to your space.vars.OIM instance, enabling you to query, configure, and manage integrations through natural language - while fully preserving the security and role-based access controls configured in space.vars.OIM.
> **Tip**: For best results, it is recommended to also connect the **OpsHub Documentation MCP** alongside the space.vars.OIM MCP server. This allows your AI assistant to access OpsHub product documentation - including connector, providing richer context when generating configurations.
To explore what operations are supported, kindly refer to [MCP Capability Matrix](/manage/mcp/mcp-capability-matrix).\
To get started with sample interactions, kindly refer to [Sample Use Cases](/manage/mcp/mcp-sample-use-cases).
***
## Prerequisites
### License
MCP server access is available with the **Professional** and **Ultimate** editions of space.vars.OIM. It is **not available** with OM4ADO.
To verify whether the MCP feature is enabled on your instance:
1. [Login](/getting-started/logging-in) to space.vars.OIM.
2. Navigate to the Footer and click on the **Edition**.
space.vars.OIM user account with appropriate roles and permissions to perform the desired operations via MCP.
> **Recommendation**: A dedicated user of OIM rather than individual user accounts improves traceability of all actions performed via MCP and ensures access is limited to only the permissions needed. To create a new user, navigate to **Administration → User Management** in space.vars.OIM and create a new user with the appropriate role.
### MCP-compatible AI client
The MCP server works with any client that supports the Model Context Protocol over HTTP. Supported clients include:
* [Claude Desktop](https://claude.ai/download)
* [Claude Code](https://docs.anthropic.com/en/docs/claude-code/getting-started)
* [Visual Studio Code](https://code.visualstudio.com/) with a compatible MCP extension (Github Copilot)
* [Cline](https://github.com/cline/cline)
* [Continue](https://www.continue.dev/)
* Any other MCP-compatible client that supports HTTP transport
***
## Accessing the MCP server
The space.vars.OIM MCP server is available at the following endpoint:
```
space.vars.OIM application URL is `http://10.13.20.20:8989/OIM/`, then the MCP endpoint will be:
```
http://10.13.20.20:8989/OpsHubWS/mcp
```
To configure your AI client to connect to this endpoint, kindly refer to [Configuration](/manage/mcp/mcp-configuration).
# Configuration
This page covers how to authenticate with the space.vars.OIM MCP server and how to configure popular MCP-compatible clients.
***
## Authentication
The space.vars.OIM MCP server supports the following authentication methods. Credentials are passed as part of the MCP client configuration headers.
> **Note**: LDAP and SAML users cannot authenticate with the MCP server. This is because MCP clients do not perform browser-based or redirect-based login flows that LDAP and SAML require. Use a local space.vars.OIM user account for MCP access.
Credentials can be passed in one of the following ways in your client configuration:
### Option 1 — API Key header (recommended)
Use an API Key generated from the space.vars.OIM UI. Refer to API Key Management for details. This is the most secure option as the key is dedicated, revocable, and keeps your user credentials out of configuration files entirely. Pass it via the `x-api-key` header:
```json
{
"servers": {
"opshub-mcp": {
"url": "space.vars.OIM. See API Key Management for step-by-step instructions.
### Option 2 — base64-encoded authorization header
Encode your credentials as a Base64 string in the format `username:password` and pass them via the standard `Authorization` header. This avoids exposing plain-text credentials in your configuration file.
```json
{
"servers": {
"opshub-mcp": {
"url": "space.vars.OIM instance.
### Visual Studio Code
{% tabs %}
{% tab title="API Key" %}
```json
{
"servers": {
"opshub-mcp": {
"url": "space.vars.OIM instance is configured on HTTPS, your MCP client must trust the SSL certificate used by the server.
* For clients that use `mcp-remote` as a bridge (Claude Desktop, Cline, Continue), the certificate must be trusted by your OS certificate store or Node.js environment.
* If you are using a self-signed or internal CA certificate, you may need to explicitly add it to Node.js using the `NODE_EXTRA_CA_CERTS` environment variable:
```bash
NODE_EXTRA_CA_CERTS=/path/to/your/certificate.pem
```
* For VS Code and Claude Code, which connect directly over HTTP/HTTPS, ensure the certificate is trusted at the OS level.
> **Note**: If you encounter SSL errors, contact your system administrator to obtain the correct certificate file and follow the steps above.
# Available Tools
This page lists all tools exposed by the space.vars.OIM MCP server. Your AI assistant uses these tools to perform operations on your space.vars.OIM instance.
> **Note**: You do not invoke these tools directly. Your AI assistant selects and calls the appropriate tools based on your natural language prompt. This reference helps you understand what is available and what each tool does.
> **Note**: Delete operations are not supported via any MCP tool. See [Known Behaviours and Limitations](/manage/mcp/mcp-known-limitations) for details.
***
### Planner tools
Planner tools guide the AI assistant through the correct sequence of steps before performing complex operations. The AI assistant calls the relevant planner automatically before executing create, update, or action operations on the corresponding resource.
| Tool | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `system_planner` | Provides a step-by-step execution plan for system operations (create, update, list, get). Ensures the AI assistant gathers all required inputs before calling system API tools. |
| `mapping_planner` | Provides a step-by-step execution plan for mapping operations (create, update, list, get). Ensures field metadata, entity types, and transformation requirements are resolved before creating or updating a mapping. |
| `integration_planner` | Provides a step-by-step execution plan for integration operations (create, update, list, get, activate, inactivate, execute). |
| `folder_planner` | Provides a step-by-step execution plan for folder operations (create, update, list, get). |
| `schedules_planner` | Provides a step-by-step execution plan for schedule operations (create, update, list, get). |
| `health_checkup_planner` | Guides the AI assistant through a comprehensive multi-stage health checkup of the space.vars.OIM instance — covering integrations, systems, mappings, failures, and instance resource parameters. Produces a visual dashboard with colour-coded health status and prioritised recommendations. |
| `failure_resolution_planner` | Guides the AI assistant through a structured diagnostic process to identify the root cause of integration failures. Covers integration configuration, mapping, system connectivity, and permissions, and produces a step-by-step resolution plan. |
***
### System tools
| Tool | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getSystemTypes` | Lists all supported system types available in space.vars.OIM with their system type IDs. Supports search by system name and pagination. |
| `getSystemTypeTemplate` | Retrieves the required fields and configuration template for a given system type. Used by the AI assistant to understand what inputs are needed before creating or updating a system. |
| `get_systems_list` | Lists all systems configured in the space.vars.OIM instance with search, filter, and sort capabilities. |
| `get_system` | Retrieves full details of a specific system by its ID. |
| `create_system` | Creates a new system (endpoint) in space.vars.OIM. |
| `update_system` | Updates an existing system's configuration by its ID. |
***
### Metadata tools
Metadata tools retrieve structural information about systems — such as available projects, entity types, fields, and lookup values. These are used by the AI assistant when building or validating mappings.
| Tool | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_projects` | Retrieves the list of projects available in a specific system. |
| `get_entities` | Retrieves the list of entity types (e.g., issues, defects, stories) available for a given system and project. |
| `get_fields_meta` | Retrieves field metadata for a given system and entity type, including field names, types, and whether they are required or read-only. |
| `get_lookup_values` | Retrieves the allowed values for a specific lookup-type field in a system (e.g., status values, priority values). |
| `get_complex_fields_meta` | Retrieves internal metadata for complex field types — comments, links, and attachments — for both systems in a mapping. Used to configure advanced field-level transformations. |
***
### Mapping tools
| Tool | Description |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_mappings_list` | Lists all mappings configured in the instance with search, filter, and sort capabilities. |
| `get_mapping` | Retrieves the full configuration of a specific mapping by its ID, including all field mappings and transformation rules. |
| `create_mapping` | Creates a new mapping between two entity types. |
| `update_mapping` | Updates an existing mapping by its ID. |
| `get_advanced_transformation_comment` | Retrieves the advanced XSLT transformation scripts for comment field mapping, including user mention, entity mention, and comment XSLT scripts. Called after a base mapping is created when comment field mapping requires advanced configuration. |
***
### XSLT tools
XSLT tools provide reference guidance that the AI assistant uses when generating or validating advanced field-level transformations in mappings.
| Tool | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `Advanced_XSLT_Transformation_Guidelines` | Provides the strict rules and constraints that the AI assistant must follow when generating or updating advanced XSLT used in field mappings. |
| `Core_Utility_Methods_Reference_for_advanced_XSLT` | Provides the library of available utility method definitions that can be used within XSLT transformations for field mappings. |
***
### Integration tools
| Tool | Description |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_integrations_list` | Lists all integrations configured in the instance with search, filter, and sort capabilities. |
| `get_integration` | Retrieves the full configuration of a specific integration by its ID, including project pairs, entity pairs, sync directions, and settings. |
| `create_integration` | Creates a new integration. |
| `update_integration` | Updates an existing integration by its ID. |
| `execute_status_change` | Changes the execution status of one or more integrations. Supports three actions: **activate** (enable the integration for scheduled sync), **inactivate** (disable the integration), and **execute** (trigger an immediate on-demand sync cycle). |
| `get_advanced_config_settings_integration` | Retrieves all advanced configuration settings available for a given integration and direction — including override parameters for read/write operations and criteria configuration. |
***
### Folder tools
| Tool | Description |
| ------------------ | ----------------------------------------------------------------------------- |
| `get_folders_list` | Lists all folders in the instance with search, filter, and sort capabilities. |
| `get_folder` | Retrieves details of a specific folder by its ID. |
| `create_folder` | Creates a new folder. The parent folder must exist. |
| `update_folder` | Updates an existing folder by its ID. |
***
### Schedule tools
| Tool | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `get_schedules_list` | Lists all schedules configured in the instance. Supports filtering by schedule type, status, and name. |
| `get_schedule` | Retrieves details of a specific schedule by its ID, including type, configuration, status, and next execution time. |
| `create_schedule` | Creates a new schedule for automating integration execution. |
| `update_schedule` | Updates an existing schedule by its ID. |
***
### Workflow tools
| Tool | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `get_workflows` | Lists all workflows available in the instance with search, filter, and sort capabilities. Workflows can be referenced when configuring integration settings. |
***
### Failure tools
| Tool | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_global_failures_list` | Lists global failures across all integrations with search, filter, and sort capabilities. Global failures indicate errors that stopped an entire integration cycle. |
| `get_global_failure` | Retrieves full details of a specific global failure by its ID, including the stack trace. |
| `get_processing_failures_list` | Lists processing failures with search, filter, and sort capabilities. Processing failures are record-level failures where a specific item failed to sync. |
| `get_processing_failure` | Retrieves full details of a specific processing failure by its ID. Can optionally include dependent failure records. |
| `retry_processing_failures` | Retries one or more processing failures, re-queuing the failed records for synchronization. |
***
### Health & diagnostics tools
| Tool | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `get_oim_system_information` | Retrieves complete details about the space.vars.OIM instance — including OS, heap memory usage, disk space, database connection pool utilisation, HTTP thread pool usage, active thread count, log folder size, and global log level. Used during health checkup to assess instance resource health. |
# MCP Capability Matrix
This document provides an overview of the operations available through the space.vars.OIM MCP server. It outlines which operations (Get, Create, Update, List, Execute) are supported across functional areas exposed as MCP tools.
Use this matrix as a quick reference to understand MCP coverage.
> **Note**: Delete operations and modification of failed synchronization records are not supported via MCP. Refer to [Known Behaviours and Limitations](/manage/mcp/mcp-known-limitations) for details.
***
### Legend
| Symbol | Meaning |
| ------ | --------------------- |
| ✅ | Supported via MCP |
| ❌ | Not Supported via MCP |
| — | Not Applicable |
***
### Operations matrix
#### Systems, Mappings & Integrations
| Feature / Module | Get | Create | Update | List | Execute | Notes |
| -------------------- | --- | ------ | ------ | ---- | ------- | -------------------------------------------------------------------------- |
| System | ✅ | ✅ | ✅ | ✅ | — | — |
| System Type | — | — | — | ✅ | — | — |
| System Type Template | ✅ | — | — | — | — | — |
| Mapping | ✅ | ✅ | ✅ | ✅ | — | Includes advanced/customized mapping with XSLTs and mapped fields settings |
| Integration | ✅ | ✅ | ✅ | ✅ | ✅ | — |
#### Folders & Schedules
| Feature / Module | Get | Create | Update | List | Execute | Notes |
| ---------------- | --- | ------ | ------ | ---- | ------- | ----- |
| Folder | ✅ | ✅ | ✅ | ✅ | — | — |
| Schedule | ✅ | ✅ | ✅ | ✅ | — | — |
| Workflow | ❌ | ❌ | ❌ | ✅ | — | — |
#### Integration monitoring & maintenance
| Feature / Module | Get | Create | Update | List | Execute | Notes |
| -------------------- | --- | ------ | ------ | ---- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Global Failure | ✅ | — | — | ✅ | — | — |
| Processing Failure | ✅ | — | ❌ | ✅ | — | — |
| Failure Notification | ❌ | ❌ | ❌ | — | — | — |
| Health Checkup | ✅ | — | — | — | — | Includes integration health analysis, failure diagnostics, and visibility into OIM instance configuration and resource utilization details |
#### Metadata
| Feature / Module | Get | Create | Update | List | Execute | Notes |
| ---------------- | --- | ------ | ------ | ---- | ------- | ----------------------------------------------------- |
| Projects | — | — | — | ✅ | — | — |
| Entity Types | — | — | — | ✅ | — | — |
| Fields | ✅ | — | — | — | — | Includes fields, comments, attachments, relationships |
#### Others
| Feature / Module | Get | Create | Update | List | Execute | Notes |
| ---------------- | --- | ------ | ------ | ---- | ------- | ----- |
| Sync Report | — | — | — | ❌ | — | — |
| Audit | — | — | — | ❌ | — | — |
| Excel Upload | ❌ | ❌ | ❌ | ❌ | — | — |
| Reconcile | ❌ | — | — | ❌ | — | — |
# Sample Use Cases
The following sample use cases demonstrate how the space.vars.OIM MCP server can be used with an AI assistant to perform common integration management tasks through natural language.
* [Integration health monitoring](/manage/mcp/mcp-sample-use-cases/mcp-use-case-integration-healthcheck)
* [Create mapping between systems](/manage/mcp/mcp-sample-use-cases/mcp-use-case-create-mapping)
* [Trigger on-demand integration execution](/manage/mcp/mcp-sample-use-cases/mcp-use-case-execute-integration)
* [View configured systems and project counts](/manage/mcp/mcp-sample-use-cases/mcp-use-case-get-systems-and-projects)
* [View and retry failed synchronizations](/manage/mcp/mcp-sample-use-cases/mcp-use-case-retry-failures)
# Integration Health Monitoring
### Description
To get a complete picture of space.vars.OIM instance — not just whether integrations are running, but also the machine's memory consumption, disk space, database connection usage, active threads, and whether there are any unresolved failures that need attention. All of this without opening the UI.
### Example interaction
| Component | Detail |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User prompt** | "Give me a full health check of my OIM instance — I want to know the resource usage, how integrations are doing, and if there are any failures I should be worried about." |
| **MCP tools invoked** | `health_checkup_planner` → `get_oim_system_information` → `get_integrations_list` → `get_systems_list` → `get_processing_failures_list` → `get_global_failures_list` → `get_mappings_list` |
| **AI assistant steps** | Fetches instance resource data (RAM allocation, memory used, disk space, DB connections, HTTP threads) → retrieves integrations with entity pair execution statuses, last sync times, and failure counts → retrieves and groups failures by cause. |
| **AI assistant output** | A health dashboard with overall status (HEALTHY / WARNING / CRITICAL), resource summary, integration and failure summaries, and prioritised recommendations. |
### Notes
* You can scope the check to specific systems: *"Health check for integrations between Jira and Rally."*
* To avoid stale results from a previous query in the same session, include "Do not use previously fetched data" in your prompt.
# Create Mapping Between Systems
### Description
A user wants to create a new field mapping between entity types of two systems — for example, mapping Jira Issues to Rally Defects.
### Example interaction
| Component | Detail |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User prompt** | "Create a mapping between Jira Issues and Rally Defects for the Alpha (Jira) - Beta (Rally) project integration." |
| **MCP tools invoked** | `mapping_planner` → `get_fields_meta` (for both systems) → `create_mapping` |
| **AI assistant steps** | Retrieves field metadata for both entity types → checks for duplicate mappings → presents proposed mapping for user confirmation → creates on confirmation. |
| **AI assistant output** | Confirmation of the created mapping with its ID and a summary of the fields mapped. |
### Notes
* The AI assistant will always check for existing mappings before creating and will warn of potential duplicates.
* Advanced configurations such as XSLT transformations, conflict detection rules, and overwrite settings can be applied by requesting them in your prompt.
# Trigger On-Demand Integration Execution
### Description
A user wants to immediately trigger all active integrations between two configured systems without navigating the space.vars.OIM UI.
### Example interaction
| Component | Detail |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User prompt** | "Execute all active integrations between Jira and HP ALM right now." |
| **MCP tools invoked** | `get_integrations_list` (filtered by system pair and ACTIVE status) → `execute_status_change` (status: EXECUTE) |
| **AI assistant steps** | Retrieves active integrations between the specified systems → presents list for user confirmation → triggers sync cycle for each and reports results. |
| **AI assistant output** | A list of integrations that were successfully triggered, along with their IDs and names. |
# View Configured Systems and Project Counts
### Description
A user wants to find out which systems are configured in space.vars.OIM and which project pairs are synchronizing between two specific systems.
### Example interaction
| Component | Detail |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **User prompt** | "What systems are configured in OIM? And what projects are integrated between System A and System B?" |
| **MCP tools invoked** | `get_systems_list` → `get_integrations_list` → extract project pairs from integration details |
| **AI assistant steps** | Retrieves all configured systems → filters integrations by the two specified systems → extracts project pairs and sync directions. |
| **AI assistant output** | A summary of all configured systems, followed by a list of project pairs with sync directions between the two specified systems. |
### Sample output
| System Pair | Project (System A) | Direction | Project (System B) |
| ------------ | ------------------ | ------------- | ------------------ |
| Jira ↔ Rally | Project Alpha | BIDIRECTIONAL | Rally Project 1 |
| Jira ↔ Rally | Project Beta | FORWARD | Rally Project 2 |
> **Tip**: To avoid stale results from a previous query in the same session, include "Do not use previously fetched data" in your prompt.
# View and Retry Failed Synchronizations
### Description
A user wants to review the processing failures across integrations and retry them without navigating to the space.vars.OIM UI. Processing failures are record-level failures — individual items that failed to sync — and can be re-queued for synchronization once the underlying issue is resolved.
### Example interaction
| Component | Detail |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **User prompt** | "Show me the processing failures and retry them." |
| **MCP tools invoked** | `get_processing_failures_list` → `retry_processing_failures` |
| **AI assistant steps** | Retrieves failures with messages and item details → presents list for user review → retries on confirmation → reports results. |
| **AI assistant output** | A list of processing failures with failure details, followed by confirmation of which failures were successfully re-queued. |
### Notes
* Global failures can be listed and retrieved for review.
* Updating `eventXML` for processing failures is not supported via MCP tools, as the `eventXML` contains actual source record data and modifying it could lead to unintended mutation of user data.
# Troubleshooting
### MCP logs
The space.vars.OIM MCP server writes its activity to a dedicated log file. The log file captures all incoming MCP requests and tool invocations.
The MCP log file is located at:
```