Creating Digital articles using the API of Enterprise Aurora

Info: This feature requires Content Station 11.3 or higher.

This article describes how the Enterprise API can be used by 3rd-party integrations for creating Digital articles.

For more information about the JSON Digital article format, see The JSON Digital article format specification.

Supported file format versions

The currently supported file format for Digital articles is version 2.0. The previous version was version 1.2.

When during the process of handling existing Digital articles an older version is encountered, it is automatically converted to the supported version.

Note: The version of the file format that is currently supported can be found in the CS_DIGITAL_ARTICLE_VERSION setting in the Enterprise/plugins/ContentStation/config.php file of the Content Station Server plug-in.

Creating a Digital article object

Invoked Web services: CreateObjects.

To create a Digital article object, a custom object property named C_CS_FILEFORMATVERSION should be provided and should match the version field in the article JSON file:

Note: When the version is not provided, the Content Station Server plug-in will decode the file to obtain the version. This negatively affects the processing time.

Specifying a Component Set

In Content Station 11.18, Component Sets were introduced. In short, a Component Set controls which components a user can make use of in the article, how these components look and how they work.

Component Sets are made available for a Digital article by assigning them to the template on which a Digital article is based when it is created. In the API this can be done by using the ExtraMetadata property C_CS_COMPONENTSET. Its ID can be retrieved from a Digital Article template to which it is assigned.

{
 "method": "CreateObjects",
 "id": "1",
 "params": {
 "req": {
 ...
 "Objects": [
 {
 "MetaData": {
 ...
 "ExtraMetaData": [
 {
 "Property": "C_CS_FILEFORMATVERSION",
 "Values": [
 "2.0"
 ],
 "__classname__": "ExtraMetaData"
 },
 {
 "Property": "C_CS_COMPONENTSET",
 "Values": [
 "ce88cb50-90b2-11e8-9039-2f37d7b0725b
 ],
 "__classname__": "ExtraMetaData"
 }
 ],
 "__classname__": "MetaData"
 },
 ...
 "Files": [
 {
 "Rendition": "native",
 "Type": "application\/ww-digital+json",
 "Content": null,
 "FilePath": null,
 "FileUrl": "http:\/\/127.0.0.1\/Ent102x\/transferindex.php?fileguid=9b2bd5be-9aa8-4529-044d-507d47ad277a\u0026format=application%2Fww-digital%2Bjson",
 "EditionId": null,
 "ContentSourceFileLink": null,
 "__classname__": "Attachment"
 }
 ],
 ...
 "__classname__": "Object"
 }
 ],
 ...
 "__classname__": "WflCreateObjectsRequest"
 }
 },
 "jsonrpc": "2.0"
} 

Creating a Digital article template

Digital article templates can be created in the same way that a Digital article is created. However, a file format version other than the currently supported version is not accepted by the Content Station Server plug-in and therefore it invokes the Enterprise Cloud Services to convert the template to the currently supported file format version on-the-fly.

Example: After uploading a version 1.2 template, a version 2.0 template is stored in the file store for template object version 0.1.

Saving a Digital article

Invoked Web services: SaveObjects.

Saving a Digital article or Digital article template works identical to the WflCreateObjectsRequest described above, but now a WflSaveObjectsRequest is used. The same rules and limitations as for a Digital article apply.

Getting a Digital article

Invoked Web services: GetObjects.

To retrieve a native Digital article file, a special RequestInfo parameter should be provided named DigitalArticleFileFormatVersion.

It should have the following notation:

DigitalArticleFileFormatVersion:<version>

where <version> stands for the desired file format version of the Digital article file.

The following example shows how to request a 2.0 version:

{
    "method": "GetObjects",
    "id": "1",
    "params": {
        "req": {
            "Ticket": "...",
            "IDs": [
                "123"
            ],
            "Lock": true,
            "Rendition": "native",
            "RequestInfo": [
                "DigitalArticleFileFormatVersion:2.0",
                ...
            ],
            ...
            "__classname__": "WflGetObjectsRequest"
        }
    },
    "jsonrpc": "2.0"
}

Deleting and restoring from the Trash Can

Invoked Web services: DeleteObjects and RestoreObjects

Digital articles (and templates) can be sent to the Trash Can and restored from the Trash Can in the usual way.

When the Digital article template has a different file format version than the current version the Content Station Server plug-in, an error will appear when running the Health Check, even when the file is found in the Trash Can. Such files have to be permanently deleted (removed from the Trash Can).

Restoring Digital article object versions

Invoked Web services: RestoreVersion, GetVersion and ListVersions.

Older versions of Digital article objects can be restored. Note that an old version may have an old file format version.

When restoring a Digital article template, the Content Station Server plug-in will prevent an older file format version to become the most active one. If that is about to happen, the plug-in invokes the Enterprise Could Service to convert the restored template on-the-fly to the currently supported file format version.

Creating a print variant from a Digital article

Invoked Web services: InstantiateTemplate, CreateObjectOperation.

A print variant of a Digital article can be created in the following ways:

• Through the context menu of a Digital article listed in the search results
• By dragging a Digital article onto a layout preview

For detailed information, see Creating a print variant of a Digital article.

In both cases, when the file format version of the Digital article is not the currently supported version, the Content Station Server plug-in invokes the Enterprise Cloud Services to convert the article to the current version on-the-fly.

However, this does not result in a new version for the Digital article, but it is used as input to create the print variant. In other words: the Digital article remains untouched (even when it has an older file format version) yet a print variant is created.

For the end user there is no difference in the system response, nor is there for Content Station a need to act differently; it is all handled by the back-end.

Document history

• 8 August 2018: Added section 'Specifying a Component Set'.
• 8 August 2018: Updated the note for DigitalArticleFileFormatVersion in section 'Getting a Digital article'.