Action Resources

The RESTful approach tries to make rest resources accessible for API users without requiring much documentation. However, the approach only really allows for modifications of data and does not think in tasks or actions.

However, in iPIM actions on resources are a frequent requirement. This is implemented by providing a sub-path for the targeted resource.

There are two types of action endpoints implemented currently:

• Specific action endpoints
• Multiple actions endpoints

Specific Actions Endpoints

Some of the actions endpoints are implemented for a specific action, so the action is directly included in the path.
like: preview, import, export, copy, duplicate, move, validate, ...

Examples:

• Attributes Preview & Import:

Endpoints implementing attributes import feature which is excecuted in 2 steps: preview to validate an import file and preview the import results and import to import attributes from an excel template file.

• Preview:
  The attributes can be: standard, category or sales category attributes

  POST .../iPIM/rest/api/attributes/preview?previewMode=standard_attributes&locale=enGB
  POST .../iPIM/rest/api/attributes/preview?previewMode=category_attributes&locale=enGB&versionIdentifier=VER_EK

  body:

  {
    "filePath": "<file_name.xlsx>",
    "attributesFileContent": "<base-64-encoded-string>"
  }

• Import:
  The attributes can be: standard, category or sales category attributes

  POST .../iPIM/rest/api/attributes/import?importMode=standard_attributes&locale=enGB
  POST .../iPIM/rest/api/attributes/import?importMode=category_attributes&locale=enGB&versionIdentifier=VER_EK

• Attributes Export:

Endpoint implementing attributes export feature.
The attributes can be: standard, category or sales category attributes

GET .../iPIM/rest/api/attributes/export?exportMode=standard_attributes&locale=enGB
GET .../iPIM/rest/api/attributes/export?exportMode=category_attributes&locale=enGB&versionIdentifier=VER_EK&nodeIdentifiers=CATALOG

Multiple Actions Endpoints

The iPIM Server REST API expose a few endpoints that define calls used to trigger asynchronous actions. The endpoints path follows this pattern: .../<resource>/action/{action}, like:

.../iPIM/rest/api/assets/action/{action}
.../iPIM/rest/api/attributes/action/{action}
.../iPIM/rest/api/categories/action/{action}
.../iPIM/rest/api/products/action/{action}
.../iPIM/rest/api/items/action/{action}
.../iPIM/rest/api/dimensions/action/{action}
.../iPIM/rest/api/processes/action/{action}
.../iPIM/rest/api/jobs/action/{action}
.../iPIM/rest/api/plugins/action/{action}
.../iPIM/rest/api/ratings/action/{action}
.../iPIM/rest/api/reports/actions/{action}
.../iPIM/rest/api/workflows/action/{action}
.../iPIM/rest/api/worklists/{pimRef}/action/{action}

Where the {action} path parameter is used to decide which action will be trigerred from the resource's implemented options, the available implemented actions are:
Note: not all actions are implemented for all endpoints, each endpoint allow only a few actions of these. You can find the allowed options for each endpoint by checking the {action} path parameter in the API Index.

Actions
triggerAddRelations	triggerDeleteAttributes	triggerGenerateAttributes	triggerRemoveFromVersion
triggerAddText	triggerDeleteTexts	triggerGenerateTexts	triggerRemoveRelatedArticlesSequence
triggerAddToCategory	triggerDependentValueMapping	triggerImportSupplierData	triggerRemoveRelations
triggerAddToWorklist	triggerDetachArticlesFromCategory	triggerInheritDefaultValuesOfNode	triggerReplenishAttributeValues
triggerApplyNodeAttributeRels	triggerDeterminingValueMapping	triggerPurchaseCategoryValidation	triggerSalesCategoryValidation
triggerArchiveProducts	triggerDragAssets	triggerReactivateProducts	triggerSendTo
triggerAssignAssets	triggerDynamicSearch	triggerReduceAttributeValues	triggerStopProcess
triggerCategoryMapping	triggerEnrichSupplierData	triggerRejectTask	triggerSynchronizeSalesCategories
triggerCategoryMappingByNodeIdentifier	triggerExecuteJob	triggerRemoveAssets	triggerUpdateJobStatus
triggerCopyCategoryAttributes	triggerFinishTask	triggerRemoveFromCategory	triggerValidateProductsOfNode
triggerDeleteArticles	triggerApplyProductVersion	triggerCreateProductVersion	triggerExportAllForCategoryNode
triggerExportArticlesForDestination	triggerMoveItems	triggerSearchAndReplaceText	triggerSecondaryCategoryValidation

Hint

Custom actions can also be added in customer projects by implementing the interface for asynchronous actions RSActionExecutable.

The RSActionExecutable interface has 3 methods that need to be overwritten for any new action:

• String getActionName(); to get the action identifier.

• Long getRightId(); to get the action User Right.

• RSMessageResult<RSProcess> execute(...); to add action execution implementation.

  RSMessageResult<RSProcess> execute(final RSAction rsAction, final DataLevel dataLevel, final List<Long> articleIds, final String category, final String categoryVersion, final String eventTypeIdentifiers, final RSValueMappingResult valueMappingResult, final boolean fetchArticleIds,
    final WsUser wsUser, final EntityManager entityManager, final Map<String, Serializable> beans);

Parameter	Description
rsAction	the action
dataLevel	the data level
articleIds	the article ids
category	optional category
categoryVersion	optional category version
eventTypeIdentifiers	optional event type identifiers
valueMappingResult	optional value mapping result
fetchArticleIds	if true, article ids are used for fetching
wsUser	the user
entityManager	the entity manager
beans	pool of business beans

The RSActionExecutable interface also contains an already implemented method default RSMessageResult<RSProcess> executeDefaultAsynchronousAction(...) that handles returning progress tracking information for the action.

For example:

POST .../iPIM/rest/api/products/action/triggerSecondaryCategoryValidation?productNos=100990,100118

Request

{
 "identifiers": [
  "Secondary_version"
 ]
}

Response

{
 "id": 10062525,
 "pimRef": "10062525",
 "progressInterval": 10,
 "processInfo": "[REST] Check_Secondary_Quality",
 "startDate": "2022-01-31T21:10:50",
 "lastUpdate": "2022-01-31T21:10:50",
 "referenceId": "[REST] Check_Secondary_Quality",
 "stoppable": false
}