org.bonitasoft.engine.api.OrganizationAPI Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of bonita-common Show documentation
Bonita Common is the useful layer common to bonita-client and bonita-server
There is a newer version: 10.2.0
/**
 * Copyright (C) 2019 Bonitasoft S.A.
 * Bonitasoft, 32 rue Gustave Eiffel - 38000 Grenoble
 * This library is free software; you can redistribute it and/or modify it under the terms
 * of the GNU Lesser General Public License as published by the Free Software Foundation
 * version 2.1 of the License.
 * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU Lesser General Public License for more details.
 * You should have received a copy of the GNU Lesser General Public License along with this
 * program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
 * Floor, Boston, MA 02110-1301, USA.
 **/
package org.bonitasoft.engine.api;

import java.util.List;

import org.bonitasoft.engine.bpm.process.DesignProcessDefinition;
import org.bonitasoft.engine.business.application.Application;
import org.bonitasoft.engine.exception.DeletionException;
import org.bonitasoft.engine.identity.ImportPolicy;
import org.bonitasoft.engine.identity.OrganizationExportException;
import org.bonitasoft.engine.identity.OrganizationImportException;
import org.bonitasoft.engine.identity.UserUpdater;

/**
 * Manages the Organization, that is the users, groups, roles, memberships, through import / export methods.
 *
 * @author Yanyan Liu
 * @author Matthieu Chaffotte
 * @author Emmanuel Duchastenier
 */
public interface OrganizationAPI {

    /**
     * Deletes the organization.
     * 
     * It deletes all user memberships, roles, groups, users and custom user info.
     * 
     * Use this method with caution: some artifacts like {@link Application}s and {@link DesignProcessDefinition}s
     * may present display problems in the Bonita
     * BPM Portal if the referenced user was deleted. Note that you can disable a user instead of deleting it. To do so,
     * use the method
     * {@link IdentityAPI#updateUser(long, UserUpdater)} to set the attribute 'enabled' to false.
     *
     * @throws DeletionException
     *         If an exception occurs during the organization deletion
     * @throws org.bonitasoft.engine.session.InvalidSessionException
     *         If the session is invalid (expired, unknown, ...)
     * @since 6.0.0
     * @see IdentityAPI#updateUser(long, UserUpdater)
     * @see Application
     * @see DesignProcessDefinition
     */
    void deleteOrganization() throws DeletionException;

    /**
     * Imports the organization using the {@link ImportPolicy#MERGE_DUPLICATES} policy.
     * 
     * An organization is composed by users, roles, groups and user memberships.
     * 
     *
     * @param organizationContent
     *        the XML content of the organization
     * @throws OrganizationImportException
     *         If an exception occurs during the organization import
     * @throws org.bonitasoft.engine.session.InvalidSessionException
     *         If the session is invalid (expired, unknown, ...)
     * @since 6.0.0
     */
    void importOrganization(String organizationContent) throws OrganizationImportException;

    /**
     * Imports the organization. Returns the error/info messages about what occurred during the process.
     * Functionally this method informs the end-user of particular non-critical events that occurred during the import.
     * 
     * Ex: If a group in the organization contains an illegal character in their name, the method will import all the
     * other
     * groups in the organization, and return a List with one String : "The group name (...) contains the illegal
     * character (...). The group has not been imported"
     * 
     * 
     * An organization is composed by users, roles, groups and user memberships.
     * 
     *
     * @return List of warning messages
     * @param organizationContent
     *        the XML content of the organization
     * @param policy
     *        the import policy
     * @throws OrganizationImportException
     *         If an exception occurs during the organization import
     * @throws org.bonitasoft.engine.session.InvalidSessionException
     *         If the session is invalid (expired, unknown, ...)
     */
    List importOrganizationWithWarnings(String organizationContent, ImportPolicy policy)
            throws OrganizationImportException;

    /**
     * Exports the organization.
     * 
     * An organization is composed by users, roles, groups and user memberships.
     * 
     *
     * @return the organization contented in an XML format
     * @throws OrganizationExportException
     *         If an exception occurs during the organization export
     * @throws org.bonitasoft.engine.session.InvalidSessionException
     *         If the session is invalid (expired, unknown, ...)
     * @since 6.0.0
     */
    String exportOrganization() throws OrganizationExportException;

}