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.

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);
  

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
}