REST APIs for working with tasks

The following REST APIs are available for working with publishing tasks.

Create a task

A POST method that creates a new publishing task. A task can be created using the preconfigured output presets, such as PDF, ePub, Responsive HTML5, and more, or a custom preset. To create a task with custom preset, you must have the settings file and DITAVAL (optional) file IDs before creating a task. Use the Upload an STS file and Upload a DITAVAL file APIs to upload the settings and DITAVAL files and get the file IDs.

Request URL

http://<FMPS_server>:<port>/v16/tasks

Header

Name	Type	Description
`content-type`	String	Type of content that is sent in the request.
`X-Access-Token`	String	The authentication token that is sent in the request.

Header example

{
  "content-type": "application/json",
  "X-Access-Token": "eyJ0eXAiOiJKhjshjafakjfkadfas"
}

Request body

Name	Type	Description
Name	String	A unique name of the task that you want to create.
Input	JSON	Contains the path of the file to publish and parameters to configure the book components. In case the input files are hosted on a CMS, then the connector settings are also included in the Input parameter.
PrePublish	JSON	Path of the script file to execute during the prepublish process.
PostPublish	JSON	Path of the script file or commands to execute after the publishing process completes.
LogInfo	JSON	Specify the information to capture in the log file for the current task.
Outputs	JSON	Contains the path to publish the output, the output format, and the preset ID to use. In case the output is to be stored on a CMS, then the login credentials for the CMS are also included in the Outputs parameter. If you are using GUID-based file system, then you must configure the `PublishedFileName` option in the `Outputs` parameter.
Notification	JSON	Specify an email ID on which the notification email is sent.

JSON body example

The following JSON request is for creating a task with the preconfigured output presets.

{
    "Name": "SamePresetMultiOut4322",
    "FMServerTask": {
        "Version": 16,
        "Jobs": [
            {
                "Input": {
                    "InputFile": "C:\\Sample\\Books\\Special\\Tables.fm",
                    "UpdateBook": {
                        "UpdateOLELinks": "NO",
                        "UpdateTextInsets": "NO",
                        "UpdateNumbering": "NO",
                        "UpdateXrefs": "NO",
                        "ApplyMasterPages": "NO",
                        "UpdateGeneratableComponents": "NO"
                    }
                },
                "PrePublish": {
                    "ExtendScript": {
                        "ScriptFile": ""
                    },
                    "prePublishid": ""
                },
                "PostPublish": {
                    "SystemCommand": {
                        "ScriptFile": ""
                    },
                    "postPublishid": ""
                },
                "LogInfo": {
                    "SupportedEncodings": "NO",
                    "AvailableFontFamilies": "NO",
                    "NumberofChaptersInBook": "NO",
                    "EmptyBookError": "NO",
                    "NumberofIndexMarkersPresent": "NO",
                    "ListofReferencedGraphics": "NO",
                    "ListofMissingGraphics": "NO",
                    "UnresolvedXrefInBook": "NO",
                    "UnresolvedTextRefInBook": "NO",
                    "ListofFilesInBook": "NO",
                    "ListofChaptersInBook": "NO",
                    "ListofGeneratableFilesInBook": "NO",
                    "NumberofAuthorMarkers": "NO",
                    "NumberofHF1Markers": "NO",
                    "NumberofHF2Markers": "NO",
                    "NumberofCommentMarkers": "NO",
                    "NumberofSubjectMarkers": "NO",
                    "NumberofGlossaryMarkers": "NO",
                    "NumberofEquationMarkers": "NO",
                    "NumberofHyperTextMarkers": "NO",
                    "NumberofCrossRefMarkers": "NO",
                    "NumberofConditionalTextMarkers": "NO",
                    "NumberofHTMLMacroMarkers": "NO"
                },
                "Outputs": [
                    {
                        "OutputFile": "Z:\\SamePresetMultiOut32323\\Responsive",
                        "OutputFormat": "RH_RESPONSIVEHELP",
                        "Configuration": {
                            "presetid": "2346453767sfgfddfhfgdhfdgh"
                        }
                    },
                    {
                        "OutputFile": "Z:\\SamePresetMultiOut65646464\\html",
                        "OutputFormat": "RH_BASICHTML",
                        "Configuration": {
                            "presetid": "gfsdsdhfghdhhgd"
                        }
                    },
                    {
                        "OutputFile": "Z:\\SamePresetMultiOut543534543542\\pdf",
                        "OutputFormat": "FM_PDF",
                        "Configuration": {
                            "presetid": "235542352354235234sgsdg"
                        }
                    }
                ]
            }
        ],
        "Notification": {
            "Emails": "test@adobe.com"
        }
    }
}

The following JSON request is for creating a task with the custom output presets.

{
   "Name": "testcustompreset",
   "_id": null,
   "runtaskid": "",
   "FMServerTask": {
      "Version": 16,
      "Jobs": [{
         "Input": {
            "InputFile": "/content/dam/testfm/Samples/UserGuide/Legal.fm",
            "Connector": {
               "ConnectorType": "Adobe Experience Manager",
               "Server": "http://yyyy.corp.adobe.com:4502/",
               "UserField1": "crx.default",
               "UserName": "",
               "Password": "",
               "id": ""
            },
            "UpdateBook": {
               "UpdateOLELinks": "NO",
               "UpdateTextInsets": "NO",
               "UpdateNumbering": "NO",
               "UpdateXrefs": "NO",
               "ApplyMasterPages": "NO",
               "UpdateGeneratableComponents": "NO"
            }
         },
         "PrePublish": {
            "ExtendScript": {
               "ScriptFile": ""
            },
            "prePublishid": ""
         },
         "PostPublish": {
            "SystemCommand": {
               "ScriptFile": ""
            },
            "postPublishid": ""
         },
         "LogInfo": {
            "SupportedEncodings": "NO",
            "AvailableFontFamilies": "NO",
            "NumberofChaptersInBook": "NO",
            "EmptyBookError": "NO",
            "NumberofIndexMarkersPresent": "NO",
            "ListofReferencedGraphics": "NO",
            "ListofMissingGraphics": "NO",
            "UnresolvedXrefInBook": "NO",
            "UnresolvedTextRefInBook": "NO",
            "ListofFilesInBook": "NO",
            "ListofChaptersInBook": "NO",
            "ListofGeneratableFilesInBook": "NO",
            "NumberofAuthorMarkers": "NO",
            "NumberofHF1Markers": "NO",
            "NumberofHF2Markers": "NO",
            "NumberofCommentMarkers": "NO",
            "NumberofSubjectMarkers": "NO",
            "NumberofGlossaryMarkers": "NO",
            "NumberofEquationMarkers": "NO",
            "NumberofHyperTextMarkers": "NO",
            "NumberofCrossRefMarkers": "NO",
            "NumberofConditionalTextMarkers": "NO",
            "NumberofHTMLMacroMarkers": "NO"
         },
         "Outputs": [{
            "OutputFile": "/content/dam/fmdita-outputs",
            "Connector": {
               "ConnectorType": "Adobe Experience Manager",
               "Server": "http://abc.def.adobe.com:4502",
               "UserField1": "crx.default",
               "UserName": "",
               "Password": "",
               "id": ""
            },
            "OutputFormat": "FM_PDF",
            "Configuration": {
               "PresetName": "Custom",
               "PresetType": "PDF",
               "FM_PDFConfiguration": {
                  "DitaValFile": "ProductA_Administrator.ditaval",
                  "SettingsFile": "Default.sts",
                  "stsfileid": "5f083bb493655a1fc060f5d4",
                  "ditavalid": "5f083bb593655a1fc060f5d5"
               },
               "presetid": ""
            }
         }]
      }],
      "Notification": {
         "Emails": "123@adobe.com"
      }
   },
   "Schedule": {
      "_id": null
   }
}

The following JSON request is for creating a task using the input files available on a CMS.

{
    "Name": "AEM Task1",
    "_id": null,
    "runtaskid": "",
    "FMServerTask": {
        "Version": 16,
        "Jobs": [
            {
                "Input": {
                    "InputFile": "/content/dam/testfm/Samples/PartsCatalog/PartsCatalog.book",
                    "Connector": {
                        "ConnectorType": "Adobe Experience Manager",
                        "Server": "AEMHOST",
                        "UserField1": "crx.default",
                        "UserName": "AEMUSER",
                        "Password": "AEMPASS",
                        "id": ""
                    },
                    "UpdateBook": {
                        "UpdateOLELinks": "NO",
                        "UpdateTextInsets": "NO",
                        "UpdateNumbering": "NO",
                        "UpdateXrefs": "NO",
                        "ApplyMasterPages": "NO",
                        "UpdateGeneratableComponents": "NO"
                    }
                },
                "PrePublish": {
                    "ExtendScript": {
                        "ScriptFile": ""
                    },
                    "prePublishid": ""
                },
                "PostPublish": {
                    "SystemCommand": {
                        "ScriptFile": ""
                    },
                    "postPublishid": ""
                },
                "LogInfo": {
                    "SupportedEncodings": "NO",
                    "AvailableFontFamilies": "NO",
                    "NumberofChaptersInBook": "NO",
                    "EmptyBookError": "NO",
                    "NumberofIndexMarkersPresent": "NO",
                    "ListofReferencedGraphics": "NO",
                    "ListofMissingGraphics": "NO",
                    "UnresolvedXrefInBook": "NO",
                    "UnresolvedTextRefInBook": "NO",
                    "ListofFilesInBook": "NO",
                    "ListofChaptersInBook": "NO",
                    "ListofGeneratableFilesInBook": "NO",
                    "NumberofAuthorMarkers": "NO",
                    "NumberofHF1Markers": "NO",
                    "NumberofHF2Markers": "NO",
                    "NumberofCommentMarkers": "NO",
                    "NumberofSubjectMarkers": "NO",
                    "NumberofGlossaryMarkers": "NO",
                    "NumberofEquationMarkers": "NO",
                    "NumberofHyperTextMarkers": "NO",
                    "NumberofCrossRefMarkers": "NO",
                    "NumberofConditionalTextMarkers": "NO",
                    "NumberofHTMLMacroMarkers": "NO"
                },
                "Outputs": [
                    {
                        "OutputFile": "/content/dam/fmdita-outputs",
                        "Connector": {
                            "ConnectorType": "Adobe Experience Manager",
                            "Server": "AEMHOST",
                            "UserField1": "crx.default",
                            "UserName": "AEMUSER",
                            "Password": "AEMPASS",
                            "id": ""
                        },
                        "OutputFormat": "FM_PDF",
                        "Configuration": {
                            "presetid": "PresetId"
                        }
                    }
                ]
            }
        ],
        "Notification": {
            "Emails": "user@enterprise.com"
        }
    },
    "Schedule": {
        "_id": null
    }
}

The following JSON request is for creating a task and scheduling the execution time.

{
   "Name": "ScheduledTask",
   "_id": null,
   "runtaskid": "",
   "FMServerTask": {
      "Version": 16,
      "Jobs": [{
         "Input": {
            "InputFile": "E:\\HTMLBUGS\\basic.fm",
            "UpdateBook": {
               "UpdateOLELinks": "NO",
               "UpdateTextInsets": "NO",
               "UpdateNumbering": "NO",
               "UpdateXrefs": "NO",
               "ApplyMasterPages": "NO",
               "UpdateGeneratableComponents": "NO"
            }
         },
         "PrePublish": {
            "ExtendScript": {
               "ScriptFile": ""
            },
            "prePublishid": ""
         },
         "PostPublish": {
            "SystemCommand": {
               "ScriptFile": ""
            },
            "postPublishid": ""
         },
         "LogInfo": {
            "SupportedEncodings": "NO",
            "AvailableFontFamilies": "NO",
            "NumberofChaptersInBook": "NO",
            "EmptyBookError": "NO",
            "NumberofIndexMarkersPresent": "NO",
            "ListofReferencedGraphics": "NO",
            "ListofMissingGraphics": "NO",
            "UnresolvedXrefInBook": "NO",
            "UnresolvedTextRefInBook": "NO",
            "ListofFilesInBook": "NO",
            "ListofChaptersInBook": "NO",
            "ListofGeneratableFilesInBook": "NO",
            "NumberofAuthorMarkers": "NO",
            "NumberofHF1Markers": "NO",
            "NumberofHF2Markers": "NO",
            "NumberofCommentMarkers": "NO",
            "NumberofSubjectMarkers": "NO",
            "NumberofGlossaryMarkers": "NO",
            "NumberofEquationMarkers": "NO",
            "NumberofHyperTextMarkers": "NO",
            "NumberofCrossRefMarkers": "NO",
            "NumberofConditionalTextMarkers": "NO",
            "NumberofHTMLMacroMarkers": "NO"
         },
         "Outputs": [{
            "OutputFile": "E:\\HTMLBUGS\\OUT",
            "OutputFormat": "FM_PDF",
            "Configuration": {
               "PresetName": "test1597120516",
               "PresetType": "PDF",
               "presetid": "5f322004900d1e21a89e92de"
            }
         }]
      }],
      "Notification": {
         "Emails": ""
      }
   },
   "MetaInfo": {
      "Creator": "{\"username\":\"fmpsuser\",\"email\":\"fmpsuser@adobe.com\",\"userType\":\"ADMIN\"}"
   },
   "Schedule": {
      "_id": null,
      "Daily": {
         "StartDate": {
            "Year": 2022,
            "Month": "DEC",
            "DayofMonth": 16
         },
         "Time": {
            "Hour": 9,
            "Minute": 15,
            "AMPM": "AM"
         },
         "Interval": 1
      }
   }
}

The following JSON request is for creating a task using the preconfigured output presets to generate PDF output. If you are integrating with Adobe Experience Manager (AEM), which uses GUID-based file naming convention, then you must configure the PublishedFileName option. If you do not specify the file name, then FMPS will generate the PDF using the same GUID as the source file, which will result in deletion of the source file. While specifying the PublishedFileName option, you don’t need to specify the file extension, which defaults to .pdf.

The PublishedFileName option is optional for systems that do not use GUID-based file naming convention.

{
    "Name": "Publish PDF GUID AEM",
    "FMServerTask": {
        "Version": 16,
        "Jobs": [
            {
                "Input": {
                    "InputFile": "C:\\Samples\\UserGuide\\UserGuide.book",
                    "UpdateBook": {
                        "UpdateOLELinks": "NO",
                        "UpdateTextInsets": "NO",
                        "UpdateNumbering": "NO",
                        "UpdateXrefs": "NO",
                        "ApplyMasterPages": "NO",
                        "UpdateGeneratableComponents": "NO"
                    }
                },
                "PrePublish": {
                    "ExtendScript": {
                        "ScriptFile": ""
                    },
                    "prePublishid": ""
                },
                "PostPublish": {
                    "SystemCommand": {
                        "ScriptFile": ""
                    },
                    "postPublishid": ""
                },
                "LogInfo": {
                    "SupportedEncodings": "NO",
                    "AvailableFontFamilies": "NO",
                    "NumberofChaptersInBook": "NO",
                    "EmptyBookError": "NO",
                    "NumberofIndexMarkersPresent": "NO",
                    "ListofReferencedGraphics": "NO",
                    "ListofMissingGraphics": "NO",
                    "UnresolvedXrefInBook": "NO",
                    "UnresolvedTextRefInBook": "NO",
                    "ListofFilesInBook": "NO",
                    "ListofChaptersInBook": "NO",
                    "ListofGeneratableFilesInBook": "NO",
                    "NumberofAuthorMarkers": "NO",
                    "NumberofHF1Markers": "NO",
                    "NumberofHF2Markers": "NO",
                    "NumberofCommentMarkers": "NO",
                    "NumberofSubjectMarkers": "NO",
                    "NumberofGlossaryMarkers": "NO",
                    "NumberofEquationMarkers": "NO",
                    "NumberofHyperTextMarkers": "NO",
                    "NumberofCrossRefMarkers": "NO",
                    "NumberofConditionalTextMarkers": "NO",
                    "NumberofHTMLMacroMarkers": "NO"
                },
                "Outputs": [
                    {
                        "OutputFile": "C:\\FMPS\\output",
                        "PublishedFileName": "samplePublishedFile",
                        "OutputFormat": "FM_PDF",
                        "Configuration": {
                            "presetid": "6011f0bc301fb91fa0e0e97c"
                        }
                    }
                ]
            }
        ],
        "Notification": {
            "Emails": "punagpal@adobe.com"
        }
    },
"Creator": "{\"username\":\"fmpsuser\",\"email\":\"fmpsuser@adobe.com\",\"userType\":\"ADMIN\"}"
   },
    "Schedule": {
        "Once": {
            "Date": {
                "Year": 2021,
                "Month": "MAR",
                "DayofMonth": 8
            },
            "Time": {
                "Hour": 1,
                "Minute": 15,
                "AMPM": "PM"
            }
        }
    }
}

Successful response

Returns a HTTP 200 (Successful) response with the newly created task’s object.

Error response

Code	Type	Description
`400`	String	A bad request is sent.

Delete a task

A DELETE method that deletes a task using the task’s ID.

Request URL

http://<FMPS_server>:<port>/v16/tasks/:id

Header

Name	Type	Description
`content-type`	String	Type of content that is sent in the request.
`X-Access-Token`	String	The authentication token that is sent in the request.

Header example

{
  "content-type": "application/json",
  "X-Access-Token": "eyJ0eXAiOiJKhjshjafakjfkadfas"
}

Parameter

Name	Type	Description
id	String	The unique ID of the task that you want to delete.

Parameter example

5e4302fafdfdfadsfdfasgafsafgsag

Successful response

Returns a HTTP 200 (Successful) response with the deleted task’s object.

Error response

Code	Type	Description
`400`	String	A bad request is sent.

Get all tasks

A GET method that retrieves all tasks available in the system.

Request URL

http://<FMPS_server>:<port>/v16/tasks

Header

Name	Type	Description
`content-type`	String	Type of content that is sent in the request.
`X-Access-Token`	String	The authentication token that is sent in the request.

Header example

{
  "content-type": "application/json",
  "X-Access-Token": "eyJ0eXAiOiJKhjshjafakjfkadfas"
}

Successful response

Returns a HTTP 200 (Successful) response with an array of all task objects.

Error response

Code	Type	Description
`400`	String	A bad request is sent.

Get a specific task

A GET method that retrieves an existing task using its unique ID.

Request URL

http://<FMPS_server>:<port>/v16/task/:id

Header

Name	Type	Description
`content-type`	String	Type of content that is sent in the request.
`X-Access-Token`	String	The authentication token that is sent in the request.

Header example

{
  "content-type": "application/json",
  "X-Access-Token": "eyJ0eXAiOiJKhjshjafakjfkadfas"
}

Parameter

Name	Type	Description
id	String	The unique ID of the task that you want to retrieve.

Parameter example

5e4302fafdfdfadsfdfasgafsafgsag

Successful response

Returns a HTTP 200 (Successful) response with the task’s object.

Error response

Code	Type	Description
`400`	String	A bad request is sent.

Get the status of a task of a specific user

A GET method that retrieves the status of an existing task created by a specific user.

Request URL

http://<FMPS_server>:<port>/v16/tasks/status/:taskid/:userid

Header

Name	Type	Description
`content-type`	String	Type of content that is sent in the request.
`X-Access-Token`	String	The authentication token that is sent in the request.

Header example

{
  "content-type": "application/json",
  "X-Access-Token": "eyJ0eXAiOiJKhjshjafakjfkadfas"
}

Parameter

Name	Type	Description
taskid	String	The unique ID of the task that you want to retrieve.
userid	String	The unique ID of the user who has created the task.

Parameter example

5e4302fafdfdfadsfdfasgafsafgsag

5e4302fafdfdfadsfdfasgafsafgsag

Successful response

Returns a HTTP 200 (Successful) response with the status of the retrieved task.

Error response

Code	Type	Description
`400`	String	A bad request is sent.

Get the status of a running task

A GET method that retrieves the status of a running task.

Request URL

http://<FMPS_server>:<port>/v16/queue/status/:runid

Header

Name	Type	Description
`content-type`	String	Type of content that is sent in the request.
`X-Access-Token`	String	The authentication token that is sent in the request.

Header example

{
  "content-type": "application/json",
  "X-Access-Token": "eyJ0eXAiOiJKhjshjafakjfkadfas"
}

Parameter

Name	Type	Description
runid	String	The unique ID of the task whose status you want to retrieve.

Parameter example

5e4302fafdfdfadsfdfasgafsafgsag

Successful response

Returns a HTTP 200 (Successful) response with the running status of the retrieved task. The status could have the following values: NOT_SCHEDULED, QUEUED, RUNNING, COMPLETED, FAILED, orKILLED.

Error response

Code	Type	Description
`400`	String	A bad request is sent.

Update a task

A PUT method that updates a task using its task ID.

Request URL

http://<FMPS_server>:<port>/v16/tasks/:id

Header

Name	Type	Description
`content-type`	String	Type of content that is sent in the request.
`X-Access-Token`	String	The authentication token that is sent in the request.

Header example

{
  "content-type": "application/json",
  "X-Access-Token": "eyJ0eXAiOiJKhjshjafakjfkadfas"
}

Parameter

Name	Type	Description
id	String	The unique ID of the task that you want to update.

Parameter example

5e4302fafdfdfadsfdfasgafsafgsag

Request body

Name	Type	Description
Name	String	A unique name of the task that you want to update. Note: The name of the task cannot be updated.
Input	JSON	Contains the path of the file to publish and parameters to configure the book components. In case the input files are hosted on a CMS, then the connector settings are also included in the `Input` parameter.
PrePublish	JSON	Path of the script file to execute during the prepublish process.
PostPublish	JSON	Path of the script file or commands to execute after the publishing process completes.
LogInfo	JSON	Specify the information to capture in the log file for the current task.
Outputs	JSON	Contains the path to publish the output, the output format, and the preset ID to use. In case the output is to be stored on a CMS, then the login credentials for the CMS are also included in the `Outputs` parameter.
Notification	JSON	Specify the email ID on which the notification email is sent.

JSON body example

Refer to the example given under Create a task.

Successful response

Returns a HTTP 200 (Successful) response with the updated task’s object.

Error response

Code	Type	Description
`400`	String	A bad request is sent.

Upload a post-publish script file

A POST method that uploads a post-publish script file to use in a task. Once the file is uploaded, you can use the file’s ID in a task to associate with the corresponding task.

Request URL

http://<FMPS_server>:<port>/v16/tasks/post/upload

Header

Name	Type	Description
`content-type`	String	Type of content that is sent in the request.
`X-Access-Token`	String	The authentication token that is sent in the request.

Header example

{
  "content-type": "multipart/form-data",
  "X-Access-Token": "eyJ0eXAiOiJKhjshjafakjfkadfas"
}

Request body

Name	Type	Description
`file`	form-data	Path of the file that you want to upload and execute in the post-publish process.

JSON body example

multipart/form-data

Successful response

Returns a HTTP 200 (Successful) response with the post-publish script file’s object.

Error response

Code	Type	Description
`400`	String	A bad request is sent.

Upload a prepublish script file

A POST method that uploads a prepublish script file use in a task. Once the file is uploaded, you can use the file’s ID in a task to associate with the corresponding task.

Request URL

http://<FMPS_server>:<port>/v16/tasks /pre/upload

Header

Name	Type	Description
`content-type`	String	Type of content that is sent in the request.
`X-Access-Token`	String	The authentication token that is sent in the request.

Header example

{
  "content-type": "multipart/form-data",
  "X-Access-Token": "eyJ0eXAiOiJKhjshjafakjfkadfas"
}

Request body

Name	Type	Description
`file`	form-data	Path of the file that you want to upload and execute in the prepublish process.

JSON body example

multipart/form-data

Successful response

Returns a HTTP 200 (Successful) response with the prepublish script file’s object.

Error response

Code	Type	Description
`400`	String	A bad request is sent.