Migrating old APIs to the PubServer API

This article collects migration hints for replacing old CometServer4SDK and Planner API calls with the newer PubServer API.

It lists direct replacements where the old SDK already points to a PubServer API method, and gives more detailed notes where the call style or parameters changed. The mappings below are based on the PubServer API interfaces and deprecated SDK interfaces and utilities, especially CometDataRemote, PubPlannerFacadeLocal, AdminLocal, PublishingPlannerFacadeLocal, AMFLocal, NotesLocal, MailRemote, and ImageUtils.

General access pattern

Old code usually retrieved services through CometServer4ServiceLocator:

CometServer4ServiceLocator.ServiceLocatorEnum serviceLocator =
    CometServer4ServiceLocator.ServiceLocatorEnum.INSTANCE;

CometDataLocal cometDataLocal = serviceLocator.getCometDataLocal();

New code retrieves the document service through PlannerEngineServiceLocator:

DocumentServiceLocal documentServiceLocal =
    PlannerEngineServiceLocator.INSTANCE.getDocumentServiceLocal();

DocumentServiceLocal migration overview

New PubServer API method	Old API candidate	Migration note
`getDocumentById(DocumentId documentId)`	`CometDataRemote#getPucDocument(String sessionID, String documentId)`, `PubPlannerFacadeLocal#getDocumentById(String documentId)`	Use `DocumentId.of(documentId)`. The new method returns `Optional<Document>` instead of `PucDocument` or `null`.
`createDocumentQuery()`	`CometDataRemote#getPucDocuments(...)`, `PubPlannerFacadeLocal#getDetailSearchDocument(...)`, `CometDataRemote#getDocumentBySourceId(...)`	Replace parameter-heavy finder methods with a fluent `DocumentQuery` and call `list()` or `singleResult()`.
`duplicateDocument(DocumentId documentId, PublicationId destinationPublicationId, String name, boolean tryToUseDocumentTemplate)`	`CometDataRemote#insertUpdatePucDocument(...)`, `CometDataRemote#multiDupicateDocument2(...)`	Use this method when the old code duplicated an existing document. The destination publication is now a typed `PublicationId`.
`createDocumentFromTemplate(PublicationId parentPublicationId, DocumentId documentTemplateId, String newDocumentName, String masterPage)`	`CometDataRemote#insertUpdatePucDocument(...)`, `CometDataRemote#multiDupicateDocument2(...)`	Use this method when the old code created one document from a document template.
`createMultipleDocumentsFromTemplate(PublicationId parentPublicationId, DocumentId documentTemplateId, List<String> newDocumentNames, String masterPage)`	`CometDataRemote#multiDupicateDocument2(...)`	Use this method when several documents are created from the same template.
`update(Document document)`	`CometDataRemote#insertUpdatePucDocument(...)`, `CometDataRemote#documentChangeLabel2(...)`, `CometDataRemote#documentChangeDescription(...)`	Retrieve the `Document`, change fields such as label or description, then call `update(document)`.
`update(List<Document> documents)`	Multiple calls to `CometDataRemote#insertUpdatePucDocument(...)` or document change methods	Use the list overload when several documents should be updated together.
`delete(DocumentId documentId)`	`CometDataRemote#deletePucDocument(...)`	The new method performs soft deletion, moving the document to the trash.
`createDocumentParameterQuery()`	`CometDataRemote#getPucDocumentParam(...)`, `CometDataRemote#getPucDocumentParamByDocumentID(...)`, `CometDataRemote#getParamsForDocument(...)`, `PubPlannerFacadeLocal#getDocumentParameters(...)`	Use a fluent `DocumentParameterQuery`. For simple key-value access, query by `documentId` and `identifier`.
`getDocumentParameterById(ParameterId parameterId)`	`CometDataRemote#getPucDocumentParam(...)`	Use this when the old code selected a document parameter by its row ID.
`updateDocumentParameter(DocumentParameter documentParameter)`	`CometDataRemote#insertUpdatePucDocumentParam(...)`, `CometDataRemote#setParamValueOfDocuments(...)`, `PubPlannerFacadeLocal#setDocumentParameter(...)`	Retrieve or create the `DocumentParameter`, change its value fields, then call `updateDocumentParameter`.
`updateDocumentParameters(List<DocumentParameter> documentParameters)`	`CometDataRemote#setParamValueOfDocuments(...)`, `CometDataRemote#massSetEntityParametersForDocument(...)`	Use the list overload for batch updates.
`createDocumentTemplate(String documentTemplateName, DocumentTemplateStatus status)`	`CometDataRemote#insertUpdatePucDocument(...)` with template/master-document semantics	Use the dedicated template method instead of encoding template creation through document insert/update parameters.
`addDocumentParameter(DocumentId documentId, ParameterDefinitionId parameterId)`	`CometDataRemote#insertUpdatePucDocumentParam(...)`	Use this when a parameter definition is assigned to a document before values are set.
`deleteDocumentParameter(DocumentParameter parameter)`	`CometDataRemote#deletePucDocumentParam(...)`	Pass the loaded `DocumentParameter` object instead of the old expanded parameter list.
`permanentlyDeleteDocument(DocumentId documentId)`	`CometDataRemote#pernamentDeleteDocument(String sessionID, String documentID)`	Direct replacement for permanently deleting a document from the trash together with its related data. Use `DocumentId.of(documentID)`; the new method omits `sessionID`. Note the corrected spelling of `permanently` in the new method name.
`restoreDeletedDocument(DocumentId documentId)`	`CometDataRemote#restoreDeletedDocument(String sessionID, String sourceDocumentId)`, `CometDataRemote#restoreDocument(...)`	Use the typed `DocumentId` method to restore a soft-deleted document.
`assignGridPageTemplate(String documentId, int pageId, int pageTemplateId)`	`AMFLocal#page_setTemplateID(...)`, `AMFLocal#pageSetTemplateID(...)`	The new method removes the old AMF parameters such as session ID, old template ID and options.

Examples

Get a document by ID

Old:

CometServer4ServiceLocator.ServiceLocatorEnum serviceLocator =
    CometServer4ServiceLocator.ServiceLocatorEnum.INSTANCE;

CometDataLocal cometDataLocal = serviceLocator.getCometDataLocal();
PucDocument document = cometDataLocal.getPucDocument(sessionId, docId);

New:

DocumentServiceLocal documentServiceLocal =
    PlannerEngineServiceLocator.INSTANCE.getDocumentServiceLocal();

Document document = documentServiceLocal
    .getDocumentById(DocumentId.of(docId))
    .orElseThrow(() -> new ServiceRuntimeException("Document not found: " + docId));

Search for documents in a publication

Old:

PucDocument[] documents = cometDataLocal.getPucDocuments(
    sessionId,
    null,
    publicationId,
    null
);

New:

List<Document> documents = documentServiceLocal
    .createDocumentQuery()
    .parentId(publicationId, false)
    .list();

Use parentId(publicationId, true) when the old search also included subpublications.

Search for document templates

Old:

PucDocument[] templates = cometDataLocal.getPucMasterDocuments(sessionId);

New:

List<Document> templates = documentServiceLocal
    .createDocumentQuery()
    .isDocumentTemplate(true)
    .list();

Update document label or description

Old:

cometDataLocal.documentChangeLabel2(sessionId, docId, newLabel);
cometDataLocal.documentChangeDescription(sessionId, docId, newDescription);

New:

Document document = documentServiceLocal
    .getDocumentById(DocumentId.of(docId))
    .orElseThrow(() -> new ServiceRuntimeException("Document not found: " + docId));

document.setLabel(newLabel);
document.setDescription(newDescription);

documentServiceLocal.update(document);

Get a document parameter

Old:

CometServer4ServiceLocator.ServiceLocatorEnum serviceLocator =
    CometServer4ServiceLocator.ServiceLocatorEnum.INSTANCE;

CometDataLocal cometDataLocal = serviceLocator.getCometDataLocal();
Map<String, String> params = cometDataLocal.getParamsForDocument(sessionId, docId);
String lang = params.get("lm_sortiment");

New:

DocumentServiceLocal documentServiceLocal =
    PlannerEngineServiceLocator.INSTANCE.getDocumentServiceLocal();

DocumentParameter docParam = documentServiceLocal
    .createDocumentParameterQuery()
    .identifier("lm_sortiment")
    .documentId(docId)
    .singleResult();

String lang = null;
if (docParam != null) {
    lang = docParam.getValue();
}

Update a document parameter

Old:

cometDataLocal.setParamValueOfDocuments(
    sessionId,
    List.of(docId),
    paramId,
    value,
    null,
    null,
    true,
    false,
    false,
    null,
    null,
    null
);

New:

DocumentParameter docParam = documentServiceLocal
    .createDocumentParameterQuery()
    .documentId(docId)
    .parameterDefinitionId(Integer.parseInt(paramId))
    .singleResult();

if (docParam != null) {
    docParam.setValue(value);
    documentServiceLocal.updateDocumentParameter(docParam);
}

Create a document from a template

Old:

String newDocumentId = cometDataLocal.insertUpdatePucDocument(
    sessionId,
    null,
    newDocumentName,
    null,
    null,
    null,
    null,
    1,
    null,
    0,
    documentTemplateId,
    publicationId,
    null,
    0,
    0,
    0,
    true,
    null,
    null,
    masterPage
);

New:

DocumentId newDocumentId = documentServiceLocal.createDocumentFromTemplate(
    PublicationId.of(publicationId),
    DocumentId.of(documentTemplateId),
    newDocumentName,
    masterPage
);

Soft-delete and restore a document

Old:

cometDataLocal.deletePucDocument(sessionId, docId, publicationId, null);
cometDataLocal.restoreDeletedDocument(sessionId, docId);

New:

documentServiceLocal.delete(DocumentId.of(docId));
documentServiceLocal.restoreDeletedDocument(DocumentId.of(docId));

DocumentServiceLocal notes for further verification

assignGridPageTemplate most closely matches the AMF page template methods, but old callers may have used page_setTemplateID, pageSetTemplateID, SOAP setTemplateID, or lower-level InDesign proxy methods.
Some old methods accepted sessionID. The new DocumentServiceLocal methods do not take it directly; session context is handled by the current PubServer API runtime.

PublicationServiceLocal migration overview

New PubServer API method	Old API candidate	Migration note
`createPublicationQuery()`	`CometDataRemote#getPucPublications(...)`, `CometDataRemote#getPublicationByType(...)`, `CometDataRemote#getPucPublicationsByLabel(...)`, `PubPlannerFacadeLocal#getRootPublications()`, `PubPlannerFacadeLocal#getSubPublications(...)`	Replace finder methods with `createPublicationQuery()` and filters such as `id`, `label`, `labelLike`, `parentId`, `publicationTypeId`, or `deleted`.
`duplicatePublication(PublicationId publicationId, PublicationId destinationParentPublicationId, String name, boolean tryToUseDocumentTemplate)`	`CometDataRemote#insertUpdatePucPublication(...)`, `CometDataRemote#duplicatePublicationElements(...)`	Use when the old code copied a publication node. Decide separately whether linked elements such as templates or rights must be copied.
`duplicateSinglePublication(...)`	`CometDataRemote#insertUpdatePucPublication(...)`, custom duplication code	New API exposes document-copy control via `duplicateDocuments`. No direct single old method was found.
`createPublication(...)`	`CometDataRemote#insertUpdatePucPublication(...)`	Old create/update was parameter-heavy. New API separates create from update and uses typed IDs.
`isPublicationTypeInUse(PublicationTypeId publicationTypeId)`	`CometDataRemote#isPublicationTypeInUse(String sessionId, String publicationTypeId)`	Direct replacement with typed ID and no `sessionId` parameter.
`update(Publication publication)`	`CometDataRemote#insertUpdatePucPublication(...)`	Retrieve or build a `Publication`, modify its fields, then call `update`.
`update(List<Publication> publications)`	Multiple calls to `CometDataRemote#insertUpdatePucPublication(...)`	Use list overload for batch updates.
`delete(PublicationId publicationId)`	`CometDataRemote#deletePucPublication(...)`	New method uses typed `PublicationId`.
`getAssignedDocumentTemplates(PublicationId publicationId)`	`CometDataRemote#getPucPublicationxtemplate(...)`, publication-template relation methods	The old API returned relation entities. The new method returns assigned document templates directly.
`assignDocumentTemplateToPublication(...)` / `unAssignDocumentTemplateFromPublication(...)`	`CometDataRemote#insertUpdatePucPublicationxtemplate(...)`, `CometDataRemote#deletePucPublicationxTemplate(...)`	Use dedicated assignment methods instead of editing relation rows.
`assignTemplateToPublication(...)` / `unAssignTemplateFromPublication(...)`	`CometDataRemote#insertUpdatePucPublicationxtemplate(...)`, `CometDataRemote#deletePucPublicationxTemplate(...)`	Direct replacement for template-publication relation updates.
`assignPageTemplateToPublication(...)` / `unAssignPageTemplateFromPublication(...)`	`CometDataRemote#insertUpdatePucPublicationxpagetemplate(...)`, `CometDataRemote#deletePucPublicationxpageTemplate(...)`	Direct replacement for page-template-publication relation updates.
`createPublicationParameterQuery()`	`CometDataRemote#getPucPublicationParam(...)`	Use `PublicationParameterQuery` filters such as `publicationId`, `identifier`, or `parameterDefinitionId`.
`getPublicationParameterById(ParameterId parameterId)`	`CometDataRemote#getPucPublicationParam(...)`	Use when the old call searched by parameter row ID.
`updatePublicationParameter(...)` / `updatePublicationParameters(...)`	`CometDataRemote#insertUpdatePucPublicationParam(...)`, `CometDataRemote#updatePublicationParameter(...)`, `CometDataRemote#massSetEntityParametersForPublication(...)`	Retrieve or create `PublicationParameter`, update values, then call the service method.
`copyPublicationElements(CopyPublicationElementsParams parameters)`	`CometDataRemote#duplicatePublicationElements(...)`	New API groups the old boolean flags into one parameter object.
`addPublicationParameter(...)`	`CometDataRemote#insertUpdatePucPublicationParam(...)`	Use when linking a parameter definition to a publication before setting values.
`deletePublicationParameter(PublicationParameter parameter)`	`CometDataRemote#deletePucPublicationParam(...)`	Pass the parameter object instead of the old expanded argument list.
`permanentlyDeletePublication(PublicationId publicationId)`	`CometDataRemote#pernamentDeletePublication(String sessionID, String pubID)`	Direct replacement for permanently deleting a publication, its subpublications, and their documents. Use `PublicationId.of(pubID)`; the new method omits `sessionID`. Note the corrected spelling of `permanently` in the new method name.
`restoreDeletedPublication(PublicationId publicationId)`	`CometDataRemote#restorePublication(String sessionID, String pubID, boolean recursive)`	Use `PublicationId.of(pubID)`; the new method omits `sessionID` and restores the publication together with all its children, corresponding to the old call with `recursive` set to `true`.

Search for publications

Old:

PucPublication[] publications = cometDataLocal.getPucPublications(
    sessionId,
    null,
    projectId,
    parentPublicationId,
    "Summer",
    publicationTypeId
);

New:

List<Publication> publications = publicationServiceLocal
    .createPublicationQuery()
    .parentId(parentPublicationId)
    .labelLike("Summer")
    .publicationTypeId(publicationTypeId)
    .list();

PublicationTypeServiceLocal migration overview

New PubServer API method	Old API candidate	Migration note
`createPublicationTypeQuery()`	`CometDataRemote#getPucPublicationTypes(...)`, `PubPlannerFacadeLocal#getPublicationTypes()`	Use filters `id`, `label`, `labelLike`, and `keyNameOfEntity`.
`getPublicationTypeById(PublicationTypeId publicationTypeId)`	`CometDataRemote#getPucPublicationTypes(...)` with `id`	New method returns `Optional<PublicationType>`.
`create(PublicationType publicationType)`	`CometDataRemote#insertUpdatePucPublicationType(...)`	New API separates create from update.
`update(PublicationType publicationType)` / `update(List<PublicationType> publicationTypes)`	`CometDataRemote#insertUpdatePucPublicationType(...)`	Use typed model objects instead of individual arguments.
`delete(PublicationTypeId publicationTypeId)`	`CometDataRemote#deletePucPublicationType(...)`	Direct replacement with typed ID.
`createPublicationTypeXParamQuery()`	`CometDataRemote#getPucPublicationtypexparam(...)`	Query parameter links for publication types.
`linkParameterToPublicationType(...)`	`CometDataRemote#insertUpdatePucPublicationtypexparam(...)`, `CometDataRemote#insertUpdateCrossPublicationtypeXparam(...)`	Use dedicated link method and pass `ParameterDefinitionId`.
`unlinkParameterFromPublicationType(...)`	`CometDataRemote#deletePucPublicationtypexparam(...)`	New API offers overloads by relation ID or type/parameter pair.
`updateSortOfLinkedParameter(...)`	`CometDataRemote#insertUpdatePucPublicationtypexparam(...)`, `CometDataRemote#updateParametersSort(...)`	Use when only link sort changes.
`getPublicationTypeOfPublication(PublicationId publicationId)`	`CometDataRemote#getPucPublicationTypes(...)` with publication-related filtering	New method exposes the common lookup directly.

PublicationRightsServiceLocal and AssignedAccessRightServiceLocal migration overview

New PubServer API method	Old API candidate	Migration note
`PublicationRightsServiceLocal#createPublicationRightQuery()`	`CometDataRemote#getRightPub(...)`	Use query filters `publicationId`, `teamId`, and `personId`.
`getPublicationRightsByPublicationId(String publicationId)`	`CometDataRemote#getRightPub(...)`	Direct convenience replacement for publication rights lookup.
`create(...)` / `update(...)` publication rights	Old publication-right insert/update methods around `PublicationRightResult`	New API uses `PublicationRight` model objects and list overloads.
`deleteByPersonId(...)`, `deleteByTeamId(...)`, `delete(...)` publication rights	Old publication-right delete methods around `PublicationRightResult`	Choose the new delete overload that matches the old key.
`AssignedAccessRightServiceLocal#createAssignedAccessRightQuery()`	`AdminLocal#getRightsForRole(...)`, `AdminLocal#getAllAccessRightsForUser(...)`, `AdminLocal#getAccesForRole(...)`, `AdminLocal#getRolexAccessRights(...)`	Use filters `rightKeyName`, `roleName`, `execRight`, and `login`.
`AssignedAccessRightServiceLocal#create(...)`	`AdminLocal#addAccessToRole(...)`, `AdminLocal#insertUpdateRolexAccessRight(...)`	New API stores the execute right as `execRight`.
`AssignedAccessRightServiceLocal#changeExecRight(...)`	`AdminLocal#editRightsForRole(...)`, `AdminLocal#insertUpdateRolexAccessRight(...)`	Use for changing an existing role/right assignment.
`AssignedAccessRightServiceLocal#delete(...)`	`AdminLocal#removeAccessFromRole(...)`	Direct replacement by right key and role name.

ParameterServiceLocal migration overview

New PubServer API method	Old API candidate	Migration note
`getParameterDefinitionById(...)`	`CometDataRemote#getPucParam(...)`	New method returns `Optional<ParameterDefinition>`.
`createParameterDefinitionQuery()`	`CometDataRemote#getPucParam(...)`, `CometDataRemote#getAllPucParam(...)`, `PubPlannerFacadeLocal#getParameters()`	Use filters `id`, `identifier`, `name`, `groupName`, `publicationTypeId`, `dropDownDefinitionId`, and `deleted`.
`createParameterDefinition(...)` / `updateParameterDefinition(...)`	`CometDataRemote#insertUpdatePucParam(...)`, `CometDataRemote#insertUpdateParamDef(...)`	New API separates create/update and uses a `ParameterDefinition` object.
`deleteParameterDefinition(..., boolean permanently)`	`CometDataRemote#deletePucParam(...)`	New API makes permanent deletion explicit.
`isParameterLinkedToDocuments(...)`	`CometDataRemote#isParameterLinkedToDocuments(String sessionId, int paramId)`	Direct replacement with `ParameterDefinitionId`.
`isParameterLinkedToPublications(...)`	`CometDataRemote#isParameterLinkedToPublications(String sessionId, int paramId)`	Direct replacement with `ParameterDefinitionId`.
`createDropDownDefinitionQuery()` / `getDropDownDefinitionById(...)`	`CometDataRemote#getPucParamDropDown(...)`	Query or retrieve dropdown definitions.
`createDropDownDefinition(...)` / `updateDropDownDefinition(...)`	`CometDataRemote#insertUpdatePucParamDropDown(...)`	New API separates create/update.
`deleteDropDownDefinition(...)`	`CometDataRemote#deletePucParamDropDown(...)`	Direct replacement with typed ID.
`createDropDownValueQuery()` / `getDropDownValueById(...)`	`CometDataRemote#getPucParamDropDownValue(...)`	Query dropdown values by ID, parent definition, or values.
`createDropDownValue(...)` / `updateDropDownValue(...)`	`CometDataRemote#insertUpdatePucParamDropDownValue(...)`	New API separates create/update.
`deleteDropDownValue(...)`	`CometDataRemote#deletePucParamDropDownValue(...)`	Direct replacement with typed ID.
`createDropDownLanguageQuery()` / `getDropDownLanguageById(...)`	`CometDataRemote#getPucParamDdLanguageValue(...)`	Query translated dropdown values.
`createDropDownLanguage(...)` / `updateDropDownLanguage(...)`	`CometDataRemote#insertUpdatePucParamDdLanguageValue(...)`	New API separates create/update.
`deleteDropDownLanguage(...)`	`CometDataRemote#deletePucParamDdLanguageValue(...)`	Direct replacement with typed ID.

TemplateServiceLocal and PageTemplatesServiceLocal migration overview

New PubServer API method	Old API candidate	Migration note
`TemplateServiceLocal#createTemplateQuery()`	`CometDataRemote#getPucPublicationxtemplate(...)`, template relation methods	Use `TemplateQuery` filters such as `id`, `label`, `templateType`, and `publicationId`.
`TemplateServiceLocal#getTemplateById(TemplateId templateId)`	Old template lookup methods and relation entities	New method returns `Optional<Template>`.
`TemplateServiceLocal#getTemplatesForPublicationId(PublicationId publicationId)`	`CometDataRemote#getPucPublicationxtemplate(...)`	Direct convenience replacement for publication-template lookup.
`PageTemplatesServiceLocal#createPageTemplatesQuery()`	`CometDataRemote#getPucPublicationxpagetemplate(...)`	Use `PageTemplatesQuery` filters such as `id`, `label`, `publicationId`, and `gridTemplate`.
`PageTemplatesServiceLocal#getPageTemplateById(PageTemplateId pageTemplateId)`	Old page-template lookup methods	New method returns `Optional<PageTemplate>`.
`PageTemplatesServiceLocal#getPageTemplatesForPublicationId(PublicationId publicationId)`	`CometDataRemote#getPucPublicationxpagetemplate(...)`	Direct convenience replacement for publication-page-template lookup.

SpreadServiceLocal migration overview

New PubServer API method	Old API candidate	Migration note
`createSpreadQuery()`	`CometDataRemote#getPucSpreads(...)`, `PubPlannerFacadeLocal#getSubnodes(...)` where subnodes include spreads	Use `SpreadQuery` filters `id`, `label`, `labelLike`, and `documentId`.
`getSpreadById(SpreadId spreadId)`	`CometDataRemote#getPucSpreads(...)` with `id`	New method returns `Optional<Spread>`.
`getSpreadsByDocumentId(DocumentId documentId)`	`CometDataRemote#getPucSpreads(sessionID, id, documentID)`	Direct convenience replacement.
`getSpreadPreview(SpreadId spreadId)`	`AMFLocal#spread_getPreview(...)`, `AMFLocal#document_getSpreadPreviews(...)`, InDesign proxy preview methods	New API returns a `SpreadPreview`; verify old preview options/resolution behavior manually.

NoteServiceLocal migration overview

New PubServer API method	Old API candidate	Migration note
`createNoteQuery()`	`AMFLocal#notes_getNotes(...)`, old `PucPagenote` lookup methods	Use `NoteQuery` filters such as `documentId`, `type`, `spreadId`, `page`, `status`, `assignedTo`, `isDraft`, and `createdBy`.
`getNoteById(NoteId noteId)`	`AMFLocal#notes_getNotes(...)` with note ID	New method returns `Optional<Note>`.
`create(Note note)`	`AMFLocal#addNote(...)`	New API creates notes from a `Note` object.
`update(Note note)` / `update(List<Note> notes)`	`AMFLocal#notes_applyChanges(String sessionID, String documentID, Note[] arrayOfNotes)` for notes marked `STATUS_CHANGED`	The old method selected create, update, or delete behavior from each note's status. The new methods update notes directly, individually or as a list, without an AMF status flag. `AMFLocal#saveNotes(...)` only persisted the complete notes XML and is not a direct replacement.
`delete(NoteId noteId)` / `delete(List<NoteId> noteId)`	`AMFLocal#deleteNote(...)`	Direct replacement with typed note IDs.
`createComment(NoteId noteId, NoteComment noteComment)`	`NotesLocal#changeNoteComment(String sessionID, String documentID, String noteID, int num, String comment)` with `num <= 0`	The old method generated the next numeric comment number. The new method accepts a `NoteComment` and returns a typed `NoteCommentId`; session, author, and timestamps are set by the runtime.
`updateComment(NoteComment noteComment)`	`NotesLocal#changeNoteComment(String sessionID, String documentID, String noteID, int num, String comment)` with `num > 0`	Replace the old numeric comment reference with `NoteComment.id`. Unlike the old method, the new API only permits updating the last comment when it was created by the current user; the old method also created a comment when `num` was not found.

UserServiceLocal, RoleServiceLocal, TeamServiceLocal, PersonServiceLocal, and ProjectServiceLocal migration overview

New PubServer API method	Old API candidate	Migration note
`UserServiceLocal#createUserQuery()`	`AdminLocal#getUsers(...)`, `AdminLocal#getAllUsers()`, `AdminLocal#getUsersByRole(...)`, `AdminLocal#getUserByDataSet(...)`	Use `UserQuery` filters such as `login`, `email`, `surname`, `givenName`, `active`, `personId`, `teamId`, `roleName`, and `dataSourceId`.
`UserServiceLocal#getUserByLogin(String login)`	`AdminLocal#getUserByLogin(...)`, `AdminLocal#getUser(...)`, `PublishingPlannerFacadeLocal#getUser(...)`	New method returns `Optional<User>`.
`UserServiceLocal#create(...)` / `createSsoUser(...)`	`AdminLocal#createUser(...)`, `AdminLocal#addUser(...)`	Use `User` model object; SSO creation has a dedicated method.
`UserServiceLocal#update(...)`	`AdminLocal#updateUser(...)`, `PublishingPlannerFacadeLocal#updateUser(...)`, `PublishingPlannerFacadeLocal#editUser(...)`	Replace long argument lists with a `User` object.
`UserServiceLocal#deleteByLogin(...)`	`AdminLocal#deleteUser(...)`	Direct replacement by login.
`UserServiceLocal#assignToProjects(...)` / `unassignFromProjects(...)`	`AdminLocal#setUserDataSet(...)`, `AdminLocal#createUserDataSet(...)`, `AdminLocal#deleteUserDataSet(...)`	Old "dataset" naming maps to project assignment.
`UserServiceLocal#getUserProjects(...)`	`AdminLocal#getDataSets(...)`, `AdminLocal#getUserByDataSet(...)`	New API uses project terminology.
`UserServiceLocal#assignToRoles(...)` / `unassignFromRoles(...)`	`AdminLocal#setUserRole(...)`, `AdminLocal#addUserToRole(...)`, `AdminLocal#removeUserFromRole(...)`	Direct replacement by login and role names.
`UserServiceLocal#getUserCheckedOutDocuments(...)`	Document lock/check-out code in old document services	New method returns `DocumentLocks` for a user. Verify if old code queried locks directly.
`UserServiceLocal#resetPassword(...)`	`AdminLocal#resetUserPassword(...)` or old user update with password	Use dedicated method for password reset.
`UserServiceLocal#synchronizeUser(...)`	`AdminLocal#synchronizeUser(...)`, `AdminLocal#synchronizeUserWithRolesAndTeams(...)`	New API uses `User` plus role/team/project sets.
`UserServiceLocal#updateAvatar(...)` / `getUserAvatar(...)`	`AdminLocal#updateUserAvatar(...)`, `AdminLocal#getUserAvatar(...)`, `PublishingPlannerFacadeLocal#updateUserAvatar(...)`, `PublishingPlannerFacadeLocal#getUserAvatar(...)`	Direct replacement.
`RoleServiceLocal#createRoleQuery()`	`AdminLocal#getAllRoles()`, `AdminLocal#getRoles(String adminSessionID, String login)`	Use `list()` to retrieve roles. The `login` filter replaces the old user-role lookup; the new query also supports `roleName`, `roleLabel`, and `roleLabelLike`.
`RoleServiceLocal#getRoleByName(String roleName)`	`AdminLocal#getAllRoles()` followed by matching the role name	Use the direct lookup instead of loading and filtering all roles. The new method returns `Optional<Role>`.
`RoleServiceLocal#create(Role role)`	`AdminLocal#addRole(String adminSessionID, String roleID, String label)`	Set the old `roleID` as `Role.name` and the old `label` as `Role.label`; session context is handled by the PubServer API runtime.
`TeamServiceLocal#createTeamQuery()`	`WfmPersonLocal#getAllTeams(String sessionID)`, `WfmPersonLocal#getTeamByPersonId(String sessionID, String personId)`	Use `list()` for all teams or the `personId` filter for teams assigned to a person. Filters for `id`, `name`, and `login` are also available; `withPersons(true)` includes team members in the result.
`TeamServiceLocal#getTeamById(TeamId teamId)`	`WfmPersonLocal#getTeamById(String sessionID, String teamId, EntityManager em)`	Use `TeamId.of(teamId)`. The new method returns `Optional<Team>` and no longer exposes session or persistence-context parameters.
`TeamServiceLocal#create(Team team)`	`WfmPersonLocal#addTeam(String sessionID, String name, boolean addTransaction)`	Create a `Team` with its name and pass it to `create`. The new method returns a typed `TeamId`; session and transaction handling are managed by the runtime.
`TeamServiceLocal#update(Team team)`	`WfmPersonLocal#editTeam(String sessionID, String teamId, String name, boolean addTransaction)`	Set `Team.id` with `TeamId.of(teamId)` and update its name before calling `update`.
`TeamServiceLocal#delete(TeamId teamId)`	`WfmPersonLocal#deleteTeam(String sessionID, String teamId, boolean addTransaction)`	Use `TeamId.of(teamId)`; the new method omits the session and transaction flag.
`TeamServiceLocal#assignPersonToTeam(PersonId personId, TeamId teamId)`	`WfmPersonLocal#addPersonToTeam(String sessionID, String personId, String teamId, boolean addTransaction)`	Use `PersonId.of(personId)` and `TeamId.of(teamId)`; session and transaction handling are managed by the runtime.
`TeamServiceLocal#unAssignPersonFromTeam(PersonId personId, TeamId teamId)`	`WfmPersonLocal#removePersonFromTeam(String sessionID, String personId, String teamId, boolean addTransaction)`	Direct replacement using typed person and team IDs.
`PersonServiceLocal#createPersonQuery()`, `getPersonById(...)`	Workflow `WfmPerson` lookups, person-related reporting methods	New API is read/query oriented. No direct old one-to-one mapping found for all filters.
`ProjectServiceLocal#createProjectQuery()`, `create(...)`, `delete(...)`	`AdminLocal#getDataSets(...)`, `AdminLocal#setUserDataSet(...)`, `AdminLocal#createUserDataSet(...)`, `AdminLocal#deleteUserDataSet(...)`	Old "dataset" maps to new project terminology in many admin calls.
`ProjectServiceLocal#assignUserToProject(...)` / `unassignUserFromProject(...)`	`AdminLocal#setUserDataSet(...)`, `AdminLocal#createUserDataSet(...)`, `AdminLocal#deleteUserDataSet(...)`	Prefer these project-specific methods over user-side assignment if the workflow starts from a project.
`ProjectServiceLocal#linkProjectToResource(...)`	`AdminLocal#linkCometProject2Resource(...)`	Direct replacement with renamed terminology.
`ProjectServiceLocal#getModelIdentifier(...)`	Old project/dataset configuration lookups	No direct public equivalent found.
`ProjectServiceLocal#getProjectUsers(...)`	`AdminLocal#getUserByDataSet(...)`	New API returns users for a project.

PreferencesServiceLocal and CustomPreferencesServiceLocal migration overview

New PubServer API method	Old API candidate	Migration note
`PreferencesServiceLocal#createPreferenceQuery()` with `PreferenceType.PUBSERVER`	`AdminLocal#getServerProperty(String adminSessionID, String propertyType)` with property type `"1"`	Set the mandatory `type` filter to `PUBSERVER`. Use `keyName(...)` for one predefined PubServer setting or `list()` for all settings.
`PreferencesServiceLocal#createPreferenceQuery()` with `PreferenceType.PRIINTBPM`	`AdminLocal#getServerProperty(String adminSessionID, String propertyType)` with property type `"4"`	Set the mandatory `type` filter to `PRIINTBPM`; the old API and configuration called this property group `camundaServer`.
`PreferencesServiceLocal#update(Preference preference)`	`AdminLocal#updateServerProperty(...)`, `AdminLocal#insertUpdateServerProperty(...)` for predefined property types `"1"` / `CometServer` and `"4"` / `camundaServer`	Set `Preference.type`, `keyName`, and `value`. Unlike the old insert/update method, the new service does not create arbitrary server preference keys; use `CustomPreferencesServiceLocal` for custom keys.
`CustomPreferencesServiceLocal#createPreferenceQuery()`	`AdminLocal#getUserProperty(...)`, `AdminLocal#getUserProperties(...)`, `CometDataRemote#getUserProperty(...)`, `CometDataRemote#getUserDefineSpreadLines(...)`, `CometDataRemote#getUserDefineSpreadLinesDef(...)`	Despite the old `UserProperty` name, these values were global key-value properties rather than values assigned to individual users. The new query matches an exact `keyName`; when replacing an old prefix lookup such as `getUserProperties(..., keyStart)`, call `list()` and filter the result by prefix.
`CustomPreferencesServiceLocal#create(CustomPreference preference)` / `update(CustomPreference preference)`	`AdminLocal#setUserProperty(...)`, `CometDataRemote#setUserProperty(...)`, `CometDataRemote#setUserDefineSpreadLines(...)`	The old setters performed an upsert. The new API requires `create` for a new key and `update` for an existing key. Existing values also need data migration from the old database table to the custom-preferences configuration.
`CustomPreferencesServiceLocal#delete(String keyName)`	`AdminLocal#deleteUserProperty(...)`, `CometDataRemote#deleteUserProperty(...)`, `CometDataRemote#deleteUserDefineSpreadLines(...)`	Direct replacement by key name.

MailServiceLocal migration overview

New PubServer API method	Old API candidate	Migration note
`send(List<Address> recipients, String subject, MessageBody body)`	`MailRemote#mailIt(...)`, workflow mail methods	New API groups body content in `MessageBody` and recipients in typed `Address` objects.
`send(..., List<Attachment> attachments)`	`MailRemote#mailItWithAttachment(...)`	Replace `Vector<MailAttachment>` with `List<Attachment>`.

DownloadServiceLocal migration overview

New PubServer API method	Old API candidate	Migration note
`createDownloadQuery()`	Old download/job tables or process-specific download helpers	No clear public CometServer4SDK equivalent found. Use query filters such as `processName`, `processIdentifier`, `objectId`, `createdBy`, `downloadObjectType`, and `finished`.
`getDownloadById(DownloadId downloadId)`	Old download/job tables	New method returns `Optional<Download>`.
`delete(DownloadId downloadId)`	Old download cleanup code	No clear direct public old API equivalent found.

Object storage, cache, image, lock, check-in/check-out, and state services

New PubServer API method	Old API candidate	Migration note
`PriintCacheServiceLocal#getPriintCacheManager()`	`CometDataCacheLocal`, `ListCache`, other internal cache helpers	New API provides a general cache manager; old named caches do not map one-to-one automatically.
`ImageUtilsServiceLocal#getPreviewOfMediaAsset(...)`	`ImageUtils#getPreviewOfMediaAsset(...)`	Direct replacement through a service instance instead of a static utility method. Replace the old source-order string with `ImageSource.URL` or `ImageSource.PATH`; use `URL` for old overloads that did not specify a source. The old utility retried the other source when reading the preferred source failed, whereas the new service primarily falls back when the preferred URL or path is absent.
`ImageUtilsServiceLocal#getPreviewOfMediaObject(...)`	`ImageUtils#getPreviewOfMediaObject(...)`	Replace the old source-order string with the corresponding `ImageSource` enum value. Width, height, optional `sessionId`, and the returned image bytes retain their roles.
`ImageUtilsServiceLocal#readMediaObject(...)`	`ImageUtils#readMediaObject(...)`	Direct replacement for reading image bytes from a `MediaObject`. `ImageSource.PATH` can read either a local file or an object-storage media object, depending on the `MediaObject` metadata.
`ImageUtilsServiceLocal#downloadImage(...)`	`ImageUtils#downloadImage(...)`	Direct replacement for both the `URI` overload and the overload with `sessionId`.
`ImageUtilsServiceLocal#getMediaAssetImageInfo(...)`	`ImageUtils#getMediaAssetImageInfo(...)`	The old method returned a `Map<String, Object>` containing height, width, color depth, and resolution. The new method returns `Optional<ImageInfo>` with typed `heightPixels`, `widthPixels`, `colorDepth`, and `dpi` components. The old overload's `mediaObjectFilePath` argument was ignored.
`ImageUtilsServiceLocal#getImageInfoOfMediaObject(...)`	`ImageUtils#getImageInfoOfMediaObject(...)`	Use this method when information is required for a specific media object. Replace a `null` map result with handling of `Optional.empty()`.
`ImageUtilsServiceLocal#scaleProportional(...)`	`ImageUtils#scaleProportional(...)`	Direct replacement with the same source bytes and maximum width and height.
`DocumentCheckServiceLocal#checkOut(...)`, `checkIn(...)`	Old document open/save/lock flows, `AMFLocal#documentSave(...)`, document lock handling	New API uses command objects `CheckOutCommand` and `CheckInCommand`. Verify file fetching/saving behavior.
`DocumentLockServiceLocal#lockDocument(...)`, `unlockDocument(...)`, `release...`, `createLockedDocumentsQuery()`	Old document locking/check-out code	New API exposes locks directly and query filters by document, tenant, project, user, time range, and session.
`ObjectStorageStateServiceLocal#getObjectStorageState()`	Old object-storage configuration checks	No direct old public equivalent found.
`RenderingServiceStateServiceLocal#listCurrentWorkers()`	Rendering service status/admin checks	No direct old public equivalent found in CometServer4SDK.
`PriintBpmStateServiceLocal#getPriintBpmVersions()`	Priint BPM/Camunda deployment checks	No direct old public equivalent found in CometServer4SDK.
`ServerMessagesServiceLocal#sendInfoMessage(...)`, `sendSuccessMessage(...)`, `sendWarningMessage(...)`, `sendErrorMessage(...)`	UI/server notification helpers, if used in custom code	No direct old public equivalent found.
`PublicationSequenceServiceLocal#getNextSequenceValue(...)`	`PublicationSequenceUtilsLocal`	New API exposes sequence access through PlannerEngine service locator.

Common query-builder migration pattern

Old finder methods usually accepted many nullable arguments:

PucPublication[] publications = cometDataLocal.getPucPublications(
    sessionId,
    null,
    null,
    parentPublicationId,
    null,
    publicationTypeId
);

New code builds only the required filters:

List<Publication> publications = publicationServiceLocal
    .createPublicationQuery()
    .parentId(parentPublicationId)
    .publicationTypeId(publicationTypeId)
    .list();

Use singleResult() only when the query is expected to return at most one result. Use list() when the old method returned arrays or collections.

General access pattern​

DocumentServiceLocal migration overview​

Examples​

Get a document by ID​

Search for documents in a publication​

Search for document templates​

Update document label or description​

Get a document parameter​

Update a document parameter​

Create a document from a template​

Soft-delete and restore a document​

DocumentServiceLocal notes for further verification​

PublicationServiceLocal migration overview​

Search for publications​

PublicationTypeServiceLocal migration overview​

PublicationRightsServiceLocal and AssignedAccessRightServiceLocal migration overview​

ParameterServiceLocal migration overview​

TemplateServiceLocal and PageTemplatesServiceLocal migration overview​

SpreadServiceLocal migration overview​

NoteServiceLocal migration overview​

UserServiceLocal, RoleServiceLocal, TeamServiceLocal, PersonServiceLocal, and ProjectServiceLocal migration overview​

PreferencesServiceLocal and CustomPreferencesServiceLocal migration overview​

MailServiceLocal migration overview​

DownloadServiceLocal migration overview​

Object storage, cache, image, lock, check-in/check-out, and state services​

Common query-builder migration pattern​

General access pattern

DocumentServiceLocal migration overview

Examples

Get a document by ID

Search for documents in a publication

Search for document templates

Update document label or description

Get a document parameter

Update a document parameter

Create a document from a template

Soft-delete and restore a document

DocumentServiceLocal notes for further verification

PublicationServiceLocal migration overview

Search for publications

PublicationTypeServiceLocal migration overview

PublicationRightsServiceLocal and AssignedAccessRightServiceLocal migration overview

ParameterServiceLocal migration overview

TemplateServiceLocal and PageTemplatesServiceLocal migration overview

SpreadServiceLocal migration overview

NoteServiceLocal migration overview

UserServiceLocal, RoleServiceLocal, TeamServiceLocal, PersonServiceLocal, and ProjectServiceLocal migration overview

PreferencesServiceLocal and CustomPreferencesServiceLocal migration overview

MailServiceLocal migration overview

DownloadServiceLocal migration overview

Object storage, cache, image, lock, check-in/check-out, and state services

Common query-builder migration pattern