Creating Digital articles using the API of Studio Server

This article describes how the Studio Server 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 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 <Studio Server path>/config/plugins/ContentStation/config.php file.

Creating a Digital article object

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 Studio Server plug-in will decode the file to obtain the version. This negatively affects the processing time.

Specifying a Component Set

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 Studio Server plug-in and therefore it invokes the WoodWing 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

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

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

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 Studio 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

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 Studio 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 WoodWing Cloud Services to convert the restored template on-the-fly to the currently supported file format version.

Creating a print variant from a Digital article

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 Studio Server plug-in invokes WoodWing 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 Studio a need to act differently; it is all handled by the back-end.