Headline

The Multisite Management API in FirstSpirit extends the capabilities of FirstSpirit Multisite Management (MSM) by providing a programmable interface for managing bundles and distributing them across multiple projects. While editors and administrators can already configure and control multisite processes via FirstSpirit’s user interfaces, the API enables developers to integrate and automate these functions in a structured manner within custom applications and workflows.

The API allows you to manage bundles, control project assignments, and edit specific elements within a bundle. This enables centralized content to be distributed across different projects in a controlled manner and allows existing multisite processes to be integrated into automated deployment and integration scenarios.

The Multisite Management API supports the following core features:

Listing, creating, modifying, and deleting bundles
Managing bundle metadata such as name, description, and settings
Managing bundle subscriptions, including adding and removing projects
Excluding individual projects from existing subscriptions
Listing the explicit elements of a bundle
Adding and removing items within a bundle
Creating change requests for the reversal of modified content

Example use cases

The following sample scripts are based on the Multisite Management API (

) .

Change request for back transport

The following script checks whether the currently selected content element in the FirstSpirit target project has been modified compared to the corresponding element in the master project. If changes are detected, it automatically creates a change request. If the selected element is a page, all contained sections are also checked and, if necessary, transferred as well. Finally, the script logs the results and displays a summary of the actions performed.

import java.util.*;
import de.espirit.firstspirit.agency.*;
import de.espirit.firstspirit.ui.operations.*;
import de.espirit.firstspirit.access.store.pagestore.*;
import de.espirit.firstspirit.modules.multisite.agency.MultisiteAgents;
import de.espirit.firstspirit.modules.multisite.agency.operation.*;

// Helper method that checks if an element has been modified and creates a new TransportRequest for it in that case.
createRequestIfModified(sourceProject, targetProject, language, element) {
    transportable = itemAgent.isTransportable(element, targetProject, language);
    if (!transportable) {    
        return TransportOperation.State.INVALID;
    } 
    modified = itemAgent.isModified(element, targetProject, language);
    if (!modified) {    
        return TransportOperation.State.UNCHANGED;
    }  
    // call operation
    transportOperation = itemAgent.getTransportOperation(element);
    transportOperation.source(language, element.getRevision()).target(targetProject);
    return transportOperation.perform().state();
}

// Helper method for result handling
addToResult(map, element, operationResult) {
    list = map.get(operationResult);
    list.add(element);
}

resultsToString(map) {
  text = "";
  for (entry : map.entrySet()) {
      text += entry.getKey() + " : ";
      for (idProvider : entry.getValue()) {
          text += idProvider.getName() + ", ";
      }
      text += "\n";
  }
  return text;
}

// initialize variables
operationAgent = context.requireSpecialist(OperationAgent.TYPE);
requestOperation = operationAgent.getOperation(RequestOperation.TYPE);
element = context.getElement();
sourceProject = element.getProject();

// get target project
targetProjectName = "Master";
targetProject = context.getConnection().getProjectByName(targetProjectName);
if (targetProject == null) {
    requestOperation.setKind(RequestOperation.Kind.ERROR);
    requestOperation.perform("Project '" + targetProjectName + "' not found.");
    context.logError("Project '" + targetProjectName + "' not found.");
}

// get language to transport
languageAbbreviation = "EN";
language = sourceProject.getLanguage(languageAbbreviation);
if (language == null) {
   requestOperation.setKind(RequestOperation.Kind.ERROR);
   requestOperation.perform("Language '" + languageAbbreviation + "' not found.");
   context.logError("Language '" + languageAbbreviation + "' not found.");
   return;
}

// prepare result map
results = new HashMap();
for (value : TransportOperation.State.values()) {
    results.put(value, new ArrayList());
}

// get ItemAgent
itemAgent = MultisiteAgents.create(context).getItemAgent();

// create request for the current element
addToResult(results, element, createRequestIfModified(sourceProject, targetProject, language, element));

// special handling for pages: iterate over sections and create a request for each modified section
if (element instanceof Page) {
    page = element;  
    for (section: page.getChildren(Section.class, true).toList()) {
        addToResult(results, section, createRequestIfModified(sourceProject, targetProject, language, section)); 
    }
}

// log info
context.logInfo("Script executed without any errors.\n\n" + resultsToString(results));
requestOperation.perform("Script executed without any errors.\n\n" + results

Create a bundle and subscribe to the target project

The following script demonstrates how to interact with bundles programmatically using the MSM API: It retrieves the BundleAgent from the master project, creates a new bundle, configures its name and release mode, and subscribes a target project so that it can receive the bundle contents. Finally, all changes are saved.

import de.espirit.firstspirit.modules.multisite.agency.*;
import de.espirit.firstspirit.access.project.Project;
import de.espirit.firstspirit.modules.multisite.dto.BundleSettings;
import de.espirit.firstspirit.modules.multisite.dto.BundleSettings.ReleaseMode;

Project masterProject = context.getElement().getProject();
long targetProjectId = 4211;

// Retrieve Agents
MultisiteAgents agents = MultisiteAgents.create(context, masterProject);
BundleAgent bundleAgent = agents.getBundleAgent();

// Create a new Bundle
Bundle bundle = bundleAgent.createBundle("My Bundle", "Description");
 
// Modify Bundle
bundle.setName("Updated Name");
bundle.getSettings().setReleaseMode(BundleSettings.ReleaseMode.RELEASE);

// Manage subscriptions
bundle.getSubscriptions().subscribe(targetProjectId);

// MANDATORY: save changes
bundle.save();

Headline

Example use cases

Change request for back transport

Create a bundle and subscribe to the target project

Table of Contents