API Dokumentation

API Dokumentation / Wiki

Die folgenden Seiten geben einen Überblick über die Funktionen des API (Programmierschnittstelle) des hyper Content & Digital Asset Management Servers.
Bitte beachten Sie, dass Sie in der Regel nur wenige Funktionen für die Entwicklung von Plugins oder speziellen Template-Funktionen, wie automatische Erstellung einer Navigation, Sitemap und so weiter, benötigen. Bitte studieren Sie den Template Designers Guide und Programers Guide für eine bessere Einsicht in die Handhabung dieser Funktionen.
Das API dient primär für die Umsetzung eigenständiger Anwendungen, die die Funktionen des hyper Content & Digital Asset Management Servers nutzen. Das API ist nicht mit dem OpenAPI zu verwechseln, welchen auf einer SOA (Service Oriented Architecture) basiert und nicht Bestandteil der Free Edition ist.

Fragen und Antworten bitte innerhalb der Google Group.

hyperCMS API Function Reference

  1. Main API Functions
  2. Get API Functions
  3. Set API Functions
  4. Connect API Functions
  5. Security API Functions
  6. Media API Functions
  7. Metadata API Functions
  8. Link API Functions
  9. Plugin API Functions
  10. User Interface API Functions
  11. Template Engine API Functions
  12. XML API Functions
  13. Report API Functions
  14. Project API Functions
  15. Task API Functions
  16. Workflow API Functions
  17. Cloud Storage API Functions
  18. Import/Export API Functions

Media API Functions

valid_jpeg


Description
Checks for the existence of the EOI segment header at the end of the file.
Mainly used to verify JPEG images extracted from older Adobe InDesign files.

Syntax
valid_jpeg ($filepath)

Input parameters
  • $filepath ... path to multimedia file [string]

Output
  • true / false


ocr_extractcontent


Description
This function extracts the text content of multimedia objects using OCR and returns the text.
It is a helper function for function indexcontent. Do not use function ocr_extractcontent directly since it will not support encrypted media files or media files in cloud storages.

Syntax
ocr_extractcontent ($site, $location, $file)

Input parameters
  • $site ... publication name [string]
  • $location ... path to multimedia file [string]
  • $file ... multimedia file name (file to be indexed) [string]

global input parameters
  • $mgmt_config
  • $mgmt_parser
  • $mgmt_imagepreview
  • $hcms_lang
  • $lang

Output
  • extracted content as text string / false


indexcontent


Description
This function extracts the text content of multimedia objects and writes it the text to the container.
The given charset of the publication (not set by default), container or publication (not set by default) will be used.
The default character set of default.meta.tpl is UTF-8, so all content should be saved in UTF-8.

Syntax
indexcontent ($site, $location, $file, $container="", $container_content="", $user="", $return_content=false)

Input parameters
  • $site ... publication name [string]
  • $location ... path to multimedia file [string]
  • $file ... multimedia file name (file to be indexed) [string]
  • $container ... container name or ID [string] (optional)
  • $container_content ... container XML-content [string] (optional)
  • $user ... user name [string]
  • $return_content ... return the content without saving it in the system [boolean] (optonal)

global input parameters
  • $mgmt_config
  • $mgmt_parser
  • $mgmt_imagepreview
  • $mgmt_uncompress
  • $hcms_ext
  • $hcms_lang
  • $lang

Output
  • true / false


unindexcontent


Description
This function removes media objects from the container

Syntax
unindexcontent ($site, $location, $file, $container, $container_content, $user)

Input parameters
  • $site ... publication name [string]
  • $location ... file location [string]
  • $file ... file name [string]
  • $container ... multimedia file to index [string]
  • $container_content ... container name or ID [string]
  • $user ... container XML-content [string]

global input parameters
  • $mgmt_config
  • $mgmt_parser
  • $hcms_lang
  • $lang

Output
  • true / false


reindexcontent


Description
Reindexes all media files of a publication. Optionally only for specific containers.

Syntax
reindexcontent ($site, $container_id_array="")

Input parameters
  • $site ... publication name [string]
  • $container_id_array ... container IDs [array] (optional)

global input parameters
  • $mgmt_config

Output
  • true / false


base64_to_file


Description
Decodes a base64 encoded string and saves it to as a file.

Syntax
base64_to_file ($base64_string, $location, $file)

Input parameters
  • $base64_string ... base64 encoded [string]
  • $location ... path to destination dir [string]
  • $file ... file name [string]

Output
  • new file name / false on error


exec_in_background


Description
Executes a shell command in the background

Syntax
exec_in_background ($cmd)

Input parameters
  • $cmd ... exec command [string

global input parameters
  • $mgmt_config

Output
  • %


createthumbnail_indesign


Description
Creates a thumbnail by extracting the thumbnail from an indesign file and transferes the generated image via remoteclient.
For good results, InDesign Preferences must be set to save preview image at an extra large size.

Syntax
createthumbnail_indesign ($site, $location_source, $location_dest, $file)

Input parameters
  • $site ... publication name [string]
  • $location_source ... path to source dir [string]
  • $location_dest ... path to destination dir [string]
  • $file ... file name [string]

global input parameters
  • $mgmt_config
  • $mgmt_mediametadata
  • $user

Output
  • new file name / false on error (saves only thumbnail media file in destination location
  • only jpeg format is supported as output)


createthumbnail_video


Description
Creates a thumbnail picture of a video frame. Saves only the thumbnail media file in destination location. Only jpeg format is supported as output.
Media files with a valid container identifier in their name will be saved in the cloud storage.

Syntax
createthumbnail_video ($site, $location_source, $location_dest, $file, $frame, $width=0, $height=0, $filename="")

Input parameters
  • $site ... publication name [string]
  • $location_source ... path to source dir [string]
  • $location_dest ... path to destination dir [string]
  • $file ... file name [string]
  • $frame ... frame of video in seconds or hh:mm:ss.xxx [integer, time]
  • $width ... image width in pixel and -1 to keep aspect ratio based on height [integer] (optional)
  • $height ... image height in pixel and -1 to keep aspect ratio based on width [integer] (optional)
  • $filename ... individual file name without the file extension of the created image [string] (optional)

global input parameters
  • $mgmt_config
  • $mgmt_mediapreview
  • $mgmt_mediaoptions
  • $user

Output
  • new file name / false on error


createimages_video


Description
Creates and saves images of video screen size from a video to a directory.
The media files will be saved in the local repository and not in the cloud storage.

Syntax
createimages_video ($site, $location_source, $location_dest, $file, $name="", $fs=1, $format="jpg", $width=0, $height=0)

Input parameters
  • $site ... publication name [string]
  • $location_source ... path to source dir [string]
  • $location_dest ... path to destination dir [string]
  • $file ... file name [string]
  • $name ... name for image files [string] (optional)
  • $fs ... frames per second to create from the video [number] (optional)
  • $format ... image format [jpg, png, bmp] (optional)
  • $width ... image width in pixel and -1 to keep aspect ratio based on height [integer] (optional)
  • $height ... image height in pixel and -1 to keep aspect ratio based on width [integer] (optional)

global input parameters
  • $mgmt_config
  • $mgmt_mediapreview
  • $mgmt_mediaoptions
  • $user

Output
  • true / false on error


createmedia


Description
Creates an new image or video from the original file or creates a thumbnail and transferes the generated image via remoteclient.
Saves original or thumbnail media file in destination location. For the thumbnail only JPEG is supported as output format.

Syntax
createmedia ($site, $location_source, $location_dest, $file, $format="", $type="thumbnail", $force_no_encrypt=false, $setmediainfo=true, $exec_in_background=false)

Input parameters
  • $site ... publication name [string]
  • $location_source ... path to source dir [string]
  • $location_dest ... path to destination dir [string]
  • $file ... file name [string]
  • $format ... format (file extension w/o dot) [string] (optional)
  • $type ... type of image/video/audio file [thumbnail(for thumbnails of images), origthumb(thumbnail made from original video/audio), original(to overwrite original video/audio file), annotation(for annotation images), any other string present in $mgmt_imageoptions/$mgmt_mediaoptions, temp(for temporary files)] (optional)
  • $force_no_encrypt ... force the file to be not encrypted even if the content of the publication must be encrypted [boolean] (optional)
  • $setmediainfo ... set media information [boolean] (optional)
  • $exec_in_background ... create image files in the background [boolean] (optional)

global input parameters
  • $mgmt_config
  • $mgmt_imagepreview
  • $mgmt_mediapreview
  • $mgmt_mediaoptions
  • $mgmt_imageoptions
  • $mgmt_maxsizepreview
  • $mgmt_mediametadata
  • $hcms_ext
  • $user

Output
  • new file name / false on error


splitmedia


Description
Splits a video or audio file in segments measured in seconds. Used for synchronous Google Cloud Speech Service that only supports max. 1 minute audio files.

Syntax
splitmedia ($site, $location_source, $location_dest, $file, $sec=60, $format="", $force_no_encrypt=false)

Input parameters
  • $site ... publication name [string]
  • $location_source ... path to source dir [string]
  • $location_dest ... path to destination dir [string]
  • $file ... file name [string]
  • $sec ... seconds of a segment [integer] (optional)
  • $format ... target format (file extension w/o dot) of destination file [string] (optional)
  • $force_no_encrypt ... force the file to be not encrypted even if the content of the publication must be encrypted [boolean] (optional)

global input parameters
  • $mgmt_config
  • $mgmt_imagepreview
  • $mgmt_mediapreview
  • $mgmt_mediaoptions
  • $mgmt_imageoptions
  • $mgmt_maxsizepreview
  • $mgmt_mediametadata
  • $hcms_ext
  • $user

Output
  • array of new file names / false on error


convertmedia


Description
Converts and creates a new image, video, audio, or document from the source file. This is a wrapper function for createmedia, createimages_video and createdocument.
If the destination media file exists already or is newer than the source file the file name will be returned without conversion.

Syntax
convertmedia ($site, $location_source, $location_dest, $mediafile, $format, $media_config="", $force_no_encrypt=false)

Input parameters
  • $site ... publication name [string]
  • $location_source ... path to source dir [string]
  • $location_dest ... path to destination dir [string]
  • $mediafile ... file name [string]
  • $format ... target format (file extension w/o dot) of destination file [string]
  • $media_config ... media configuration to be used [string] (optional)
  • $force_no_encrypt ... force the file to be not encrypted even if the content of the publication must be encrypted [boolean] (optional)

global input parameters
  • $mgmt_config
  • $mgmt_imagepreview
  • $mgmt_mediapreview
  • $mgmt_mediaoptions
  • $mgmt_imageoptions
  • $mgmt_maxsizepreview
  • $mgmt_mediametadata
  • $mgmt_compress
  • $hcms_ext

Output
  • new file name / false on error


convertimage


Description
Converts and creates a new image from original. The new image will be resized and cropped to fit width and height.
This is a wrapper function of function createmedia.

Syntax
convertimage ($site, $file_source, $location_dest, $format="jpg", $colorspace="RGB", $iccprofile="", $width="", $height="", $slug=0, $units="px", $dpi=72, $quality="", $watermark=true)

Input parameters
  • $site ... publication name [string]
  • $file_source ... path to source image file [string]
  • $location_dest ... path to destination dir [string]
  • $format ... format (file extension w/o dot) of destination file [string] (optional)
  • $colorspace ... colorspace of new image [CMY, CMYK, Gray, HCL, HCLp, HSB, HSI, HSL, HSV, HWB, Lab, LCHab, LCHuv, LMS, Log, Luv, OHTA, Rec601YCbCr, Rec709YCbCr, RGB, scRGB, sRGB, Transparent, XYZ, YCbCr, YCC, YDbDr, YIQ, YPbPr, YUV] (optional)
  • $iccprofile ... width in pixel/mm/inch [integer] (optional)
  • $width ... height in pixel/mm/inch [integer] (optional)
  • $height ... slug in pixel/mm/inch [integer] (optional)
  • $slug ... units for width [string]
  • $units ... height and slug [px, mm, inch] (optional)
  • $dpi ... dpi [integer] (optional)
  • $quality ... image quality [1 to 100]
  • $watermark ... apply watermark [boolean] (optional)

global input parameters
  • $mgmt_config
  • $mgmt_imagepreview
  • $mgmt_mediapreview
  • $mgmt_mediaoptions
  • $mgmt_imageoptions
  • $mgmt_maxsizepreview
  • $mgmt_mediametadata
  • $hcms_ext
  • $user

Output
  • new file name / false on error


rotateimage


Description
Rotates an image (must be jpg, png or gif) using GD library. not used if ImageMagick is available

Syntax
rotateimage ($site, $filepath, $angle, $imageformat)

Input parameters
  • $site ... publication name [string]
  • $filepath ... path to source media file [string]
  • $angle ... rotation angle [integer]
  • $imageformat ... destination image format [jpg, png, gif]

global input parameters
  • $mgmt_config
  • $user

Output
  • new image file name / false on error


hex2rgb


Syntax
hex2rgb ($hex)

Input parameters
  • $hex ... image color as hex-code [string]

Output
  • RGB-color values as array / false on error


rgb2hex


Syntax
rgb2hex ($red, $green=0, $blue=0)

Input parameters
  • $red ... image color in RGB [array] or red value [integer]
  • $green ... green value [integer]
  • $blue ... blue value [integer]

Output
  • CMYK color percentage values as array / false on error


readmediaplayer_config


Syntax
readmediaplayer_config ($location, $configfile)

Input parameters
  • $location ... path to media config file [string]
  • $configfile ... config file name [string]

global input parameters
  • $mgmt_config
  • $mgmt_mediaoptions
  • $user

Output
  • config array / false on error


savemediaplayer_config


Syntax
savemediaplayer_config ($location, $configfile, $mediafiles, $width=320, $height=240, $rotation="", $filesize="", $duration="", $videobitrate="", $audiobitrate="", $audiofrequenzy="", $audiochannels="", $video_codec="", $audio_codec="")

Input parameters
  • $location ... path to media config file [string]
  • $configfile ... media config file name [string]
  • $mediafiles ... media file name [array or string]
  • $width ... width in px [integer] (optional)
  • $height ... height in px [integer] (optional)
  • $rotation ... rotation in degree [integer] (optional)
  • $filesize ... file size in kB [integer] (optional)
  • $duration ... duration [hh:mmm:ss] (optional)
  • $videobitrate ... video bitrate in kb/s [string] (optional)
  • $audiobitrate ... audio bitrate in kb/s [string] (optional)
  • $audiofrequenzy ... audio frequenzy in Hz [string] (optional)
  • $audiochannels ... audio channels [mono, stereo] (optional)
  • $video_codec ... video codec name [string] (optional)
  • $audio_codec ... audio codec name [string] (optional)

global input parameters
  • $mgmt_config
  • $user

Output
  • true / false on error


createdocument


Description
Creates a new multimedia file of given format at source destination using UNOCONV and saves it as a thumbnail file in the destination location

Syntax
createdocument ($site, $location_source, $location_dest, $file, $format="", $force_no_encrypt=false)

Input parameters
  • $site ... publication name [string]
  • $location_source ... path to source location [string]
  • $location_dest ... path to destination location [string]
  • $file ... file name [string]
  • $format ... destination file format (extension w/o dot) [string]
  • $force_no_encrypt ... force the file to be not encrypted even if the content of the publication must be encrypted [boolean] (optional)

global input parameters
  • $mgmt_config
  • $mgmt_docpreview
  • $mgmt_docoptions
  • $mgmt_docconvert
  • $mgmt_maxsizepreview
  • $hcms_ext
  • $hcms_lang
  • $lang
  • $user

Output
  • new file name / false on error


unzipfile


Description
Unpacks ZIP file and creates media files in destination location for components or unzips files directly for pages (not recommended due to the security risks by uploading files that can be executed).

Syntax
unzipfile ($site, $zipfilepath, $location, $filename, $cat="comp", $user="")

Input parameters
  • $site ... publication name [string]
  • $zipfilepath ... path to source zip file [string]
  • $location ... path to destination location [string]
  • $filename ... category [page, comp]
  • $cat ... name of file for extraction [string]
  • $user ... user name [string]

global input parameters
  • $mgmt_config
  • $mgmt_uncompress
  • $mgmt_imagepreview
  • $mgmt_mediapreview
  • $mgmt_mediaoptions

Output
  • result array with all object paths / false


clonefolder


Description
Help function for function zipfiles that reads all multimedia files from their multimedia objects and copies them to the same folder structure using the object names.

Syntax
clonefolder ($site, $source, $destination, $user, $activity="")

Input parameters
  • $site ... publication name [string]
  • $source ... source location [string]
  • $destination ... destination location [string]
  • $user ... user name [string]
  • $activity ... activity that need to be set for daily stats [download] (optional)

global input parameters
  • $mgmt_config
  • $pageaccess
  • $compaccess
  • $hiddenfolder
  • $hcms_linking
  • $globalpermission
  • $setlocalpermission

Output
  • container IDs as array / false


zipfiles_helper


Description
Compresses all files and includes their folder structure in a ZIP file. This function does not support multimedia objects and is only a helper function for native file system operations.

Syntax
zipfiles_helper ($source, $destination, $zipfilename, $remove=false)

Input parameters
  • $source ... source directory [string]
  • $destination ... destination directory [string]
  • $zipfilename ... name of ZIP-file [string]
  • $remove ... remouse all files from source [boolean] (optional)

global input parameters
  • $mgmt_config
  • $mgmt_compress

Output
  • true/false


zipfiles


Description
Compresses all media files and includes their folder structure in a ZIP file.

Syntax
zipfiles ($site, $multiobject_array, $destination="", $zipfilename="", $user="", $activity="", $flatzip=false)

Input parameters
  • $site ... publication name [string]
  • $multiobject_array ... array with path to source files [array]
  • $destination ... destination location (if this is null then the $location where the zip-file resists will be used) [string]
  • $zipfilename ... name of ZIP-file [string]
  • $user ... user name [string]
  • $activity ... activity that need to be set for daily stats [download] (optional)
  • $flatzip ... flat hierarchy means no directories [boolean] (optional)

global input parameters
  • $mgmt_config
  • $mgmt_compress
  • $pageaccess
  • $compaccess
  • $hiddenfolder
  • $hcms_linking
  • $globalpermission
  • $setlocalpermission
  • $hcms_lang
  • $lang

Output
  • true/false


px2mm


Description
Convert mm to pixel

Syntax
px2mm ($pixel, $dpi=72)

Input parameters
  • $pixel ... pixel [integer]
  • $dpi ... dpi [integer] (optional)

Output
  • pixel / false


px2inch


Description
Convert pixel to inches

Syntax
px2inch ($pixel, $dpi=72)

Input parameters
  • $pixel ... pixel [integer]
  • $dpi ... dpi [integer] (optional)

Output
  • inch / false


inch2px


Description
Convert inches to pixel

Syntax
inch2px ($inch, $dpi=72)

Input parameters
  • $inch ... pixel [integer]
  • $dpi ... dpi [integer] (optional)

Output
  • pixel / false


sec2time


Description
Convert seconds to time format hh:mm:ss.mmm

Syntax
sec2time ($input)

Input parameters
  • $input ... time in seconds [float]

Output
  • time in hh:mm:ss.mmm / false


mediasize2frame


Description
Calculates the width and height of a media to fit into a given frame size.

Syntax
mediasize2frame ($mediawidth, $mediaheight, $framewidth="", $frameheight="", $keepmaxsize=true)

Input parameters
  • $mediawidth ... media width [integer]
  • $mediaheight ... media height [integer]
  • $framewidth ... frame width [integer] (optional)
  • $frameheight ... frame height [integer] (optional)
  • $keepmaxsize ... keep maximum media size based on original dimensions of media without stretching [boolean] (optional)

Output
  • width and height as array / false


vtt2array


Description
Converts VTT string to array

Syntax
vtt2array ($vtt)

Input parameters
  • $vtt ... video text track [string]

Output
  • array / false


html2pdf


Description
Converts html to pdf using WKHTMLTOPDF and XSERVER. The CSS media print style will be applied.
For full support you might want to install the package provided from WKHTMLTOPDF directly (patched QT).
See the event log in case the function does not create a proper result since you are not using a patched QT version.
See also: https://wkhtmltopdf.org/usage/wkhtmltopdf.txt

Syntax
html2pdf ($source, $dest, $cover="", $toc=false, $page_orientation="Portrait", $page_size="A4", $page_margin=10, $image_dpi=144, $image_quality=95, $smart_shrinking=true, $options="")

Input parameters
  • $source ... URLs or pathes to html source files [array]
  • $dest ... path of pdf destination output file [string]
  • $cover ... cover page html file [string] (optional)
  • $toc ... create TOC table of contents [boolean] (optional)
  • $page_orientation ... page orientation [Landscape, Portrait] (optional)
  • $page_size ... page size like A4 or Letter [string] (optional)
  • $page_margin ... page margin in mm [integer] (optional)
  • $image_dpi ... image DPI [integer] (optional)
  • $image_quality ... image quality 1-100 [integer] (optional)
  • $smart_shrinking ... use smart shrinking of the content so it can fit in the page [boolean] (optional)
  • $options ... additional WKHMTLTOPDF options [string] (optional)

global input parameters
  • $mgmt_config

Output
  • true / false on error


mergepdf


Description
Merges pdf files into one pdf file. Do NOT USE special characters in file names.
See also: https://www.pdflabs.com/docs/pdftk-man-page/

Syntax
mergepdf ($source, $dest)

Input parameters
  • $source ... pathes to pdf source files [array]
  • $dest ... path of pdf destination output file [string]

global input parameters
  • $mgmt_config

Output
  • true / false on error


Diese Website verwendet Cookies, um Ihnen das bestmögliche Erlebnis auf unserer Website zu ermöglichen. Mehr info