Working with FMPS using the APIs

FrameMaker Publishing Server comes with out-of-the-box web APIs that can be used to publish content from Microsoft SharePoint, OpenText Documentum, or Adobe Experience Manager. The APIs work on resources such as tasks, templates, and presets, to create, retrieve, update, and delete resources. Additional APIs help schedule, kill, or run tasks and more.

API methods

From a client machine, you can query the FMPS using the following methods on IIS to create, retrieve, update, or delete (CRUD) resources. According to the REST protocol, everything on the server, such as tasks, presets, and templates, is treated as a resource. For more information on the REST protocol, see http://en.wikipedia.org/wiki/Representational_state_transfer

In the Web API URLs and task types table, the various GET, POST, DELETE, and PUT requests map to CRUD framework as following:

Type of task

CRUD aspect

Post

Create

Get

Retrieve

Put

Update

Delete

Delete

CRUD framework

The FMPS APIs manage the FMPS according to the CRUD (Create, Read, Update, Delete) framework. For more information on the CRUD framework, see http://en.wikipedia.org/wiki/Create,_read,_update_and_delete

Following are the commands mapping to the CRUD framework:

CRUD aspect

FMPS Web API command

CREATE

curl.exe -k --dump-header h_create_task.txt -v -u <domain>\<username>:<password> --ntlm -H "Content-Type: application/XML" -X POST --data [@]<TaskSample>.xml http://localhost:6234/fmserver/v1/Tasks

RETRIEVE

curl.exe -k --dump-header h_Tasks.txt -v -u <domain>\<username>:<password> --ntlm http://localhost:6234/fmserver/v1/Tasks

UPDATE

curl.exe -k --dump-header h_edit_task.txt -v -u <domain>\<username>:<password> --ntlm -H "Content-Type: application/XML" -X PUT --data [@]<TaskSample>.xml http://localhost:6234/fmserver/v1/Tasks/<TaskName>

DELETE

curl.exe -k --dump-header h_delete_task.txt -v -u <domain>\<username>:<password> --request DELETE http://localhost:6234/fmserver/v1/Tasks/<TaskName>

Web API URLs and task types

The following table includes URLs of each of the Web APIs available to you for building your own FMPS custom client. Each URL represents a Web API that you can query. The methods, such as Get and Post, are the type of operations you are performing on the Web API. The URLs include parameters that you can pass for the task.

Create and update (Post and Put) requests have parameters passed in the body of the HTTP request as an XML or JSON file as well as in the URL. Get and Delete have parameters in the URLs only. The various task type links in the Help URL include the schema required for the various tasks.

FMPS supports the following Web APIs :
Note: The following example commands use cURL. You can use any other command line tool and modify the commands accordingly.

Web API URL (links work on a machine with FMPS installed)

Task Type

Description

http://localhost:6234/fmserver/v1/{TYPE}/presets

Get

Retrieve all presets of type PDF or ROBO

Post

Create a preset of type PDF or ROBO

http://localhost:6234/fmserver/v1/{TYPE}/presets/{NAME}

Get

Retrieve a preset of type PDF or ROBO

Put

Edit a preset of type PDF or ROBO

Delete

Delete a preset of type PDF or ROBO

http://localhost:6234/fmserver/v1/cmsinfolist

Get

Get list of CMS registered for FMPS. This comes from the cmsinfolist.xml in FMPS installation

http://localhost:6234/fmserver/v1/kill/tasks/{TASKNAME}

Post

Kill an already running Task

http://localhost:6234/fmserver/v1/meta/tasks/{TASKNAME}

Get

Retrieve meta info of a task: Creator, Created, Last Run

http://localhost:6234/fmserver/v1/meta/templatetasks/{TEMPLATENAME}?shared={SHARED}

Get

Retrieve meta info of a task: Creator, Created, Last Run

Optional Parameter Shared=true needs to be passed in the URL to indicate a shared template

http://localhost:6234/fmserver/v1/run/tasks/{TASKNAME}

Post

Run a task

http://localhost:6234/fmserver/v1/run/templatetasks/{TEMPLATENAME}?shared={SHARED}

Post

Run a Template Task with template parameters. This creates a temporary task that would be run immediately.

Optional Parameter Shared=true needs to be passed in the URL to indicate a shared template

http://localhost:6234/fmserver/v1/tasks?taskinfo={TASKINFO}&metainfo={METAINFO}&schedulinginfo={SCHEDULINGINFO}&statusinfo={STATUSINFO}

Get

Retrieve list of all Tasks detailsOptional Parameter(s):

metainfo=true needs to be passed in the URL to retrieve Creator, Created, Last Run

schedulinginfo=true needs to be passed in the URL to retrieve schedule of the task

statusinfo=true needs to be passed in the URL to retrieve running status of the Task

http://localhost:6234/fmserver/v1/tasks

Post

Create a task with the settings specified in the given file.

http://localhost:6234/fmserver/v1/tasks/{TASKNAME}?metainfo={METAINFO}&schedulinginfo={SCHEDULINGINFO}&statusinfo={STATUSINFO}

Get

Retrieve the given Task details

Optional Parameter(s):

metainfo=true needs to be passed in the URL to retrieve Creator, Created, Last Run

schedulinginfo=true needs to be passed in the URL to retrieve schedule of the task

statusinfo=true needs to be passed in the URL to retrieve running status of the Task

http://localhost:6234/fmserver/v1/tasks/{TASKNAME}

Put

Edit a task with the settings specified in the given file.

Delete

Delete a specific task

http://localhost:6234/fmserver/v1/tasks/{TASKNAME}/logs

Get

Retrieve the list of all logs of the given Task

http://localhost:6234/fmserver/v1/tasks/{TASKNAME}/logs/{LOGNAME}

Get

Retrieve a specific log of the given Task

http://localhost:6234/fmserver/v1/tasks/{TASKNAME}/statuses

Get

Retrieve the list of all status logs of the given Task

http://localhost:6234/fmserver/v1/tasks/{TASKNAME}/statuses/{STATUSNAME}

Get

Retrieve a specific status log of the given Task

http://localhost:6234/fmserver/v1/templatetasks?shared={SHARED}&templateinfo={TEMPLATEINFO}&metainfo={METAINFO}

Get

Retrieve list of all TemplateTasks details

Optional Parameter(s):

shared=true needs to be passed in the URL to indicate a shared template

metainfo=true needs to be passed in the URL to retrieve Creator, Created

templateinfo=true needs to be passed in the URL to retrieve details of the Template Task

http://localhost:6234/fmserver/v1/templatetasks?shared={SHARED}

Post

Create a template task with the settings specified in the given file.

Optional Parameter Shared=true needs to be passed in the URL to indicate a shared template

http://localhost:6234/fmserver/v1/templatetasks/{TEMPLATENAME}?shared={SHARED}&metainfo={METAINFO}

Get

Retrieve meta info of a task: Creator, Created

http://localhost:6234/fmserver/v1/templatetasks/{TEMPLATENAME}?shared={SHARED}

Delete

Delete a template task with the specified name

Optional Parameter Shared=true needs to be passed in the URL to indicate a shared template

Put

Modify a template task with the settings specified in the given file.

Optional Parameter Shared=true needs to be passed in the URL to indicate a shared template

http://localhost:6234/fmserver/v1/schedulinginfo/tasks/{TASKNAME}

Get

Retrieve schedule of a Task

Put

Modify schedule of a Task

Help URL

The Help URL (Localhost:6234\fmserver/v1/help) gives you a list of all the Web APIs available to you:

When you click a Post or Put link, you can see:

  • The sample XML and JSON schema of the file you need to pass with the parameters for creating\modifying a task.

  • The sample response XML and JSON schema files.

When you click a Get link, you see the sample response schemas. For Get requests, the body for request and response is empty.

Enable the Help URL

As explained in the step 3 of Install FrameMaker Publishing Server, add the following value to the application settings of FMPS and set it to true:

FMPSHelpDataEnabled

Using command line to manage tasks with FrameMaker Publishing Server

Note: In the following commands, you will use the username and password fields only if you have enabled authentication. Otherwise, you do not pass domain, username, password, and --ntlm.

Create a task for the FMPS

  1. Create a .xml or JSON file specifying Task Name, Input File, Output file, and your email ID where FMPS will send notifications about the task. Following is the example content for the XML input file:

    <Task xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> 
        <Name>Task_Epub</Name> 
        <FMServerTask xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> 
            <Version>14</Version>        <Jobs> 
                <Job> 
                    <Input> 
                        <InputFile>C:\Sample.Book</InputFile> 
                        
                        <UpdateBook></UpdateBook> 
                    </Input> 
                    <Outputs> 
                        
                                    <Output> 
                            <OutputFile>C:\Epub\</OutputFile> 
                            <OutputFormat>RH_EPUB</OutputFormat> 
                            
                            <Configuration> 
                                <RH_CONFIGURATION> </RH_CONFIGURATION> 
                            </Configuration> 
                        </Output> 
                                                                                    
                    </Outputs> 
                </Job> 
            </Jobs> 
      <Notification> 
        <Emails> 
          <Email>your@email.com</Email> 
        </Emails> 
      </Notification> 
        </FMServerTask> 
    </Task>
  2. Pass the following command with the appropriate values to create a task. Replace <TaskSample>.xml with the XML\JSON file’s name you created in step 1.

    curl.exe -k --dump-header h_create_task.txt -v -u <domain>\<username>:<password> --ntlm -H "Content-Type: application/XML" -X POST --data [@]<TaskSample>.xml http://localhost:6234/fmserver/v1/Tasks

    The task is created. When this task runs successfully. System returns the code 200. The task gets created in 2 places in FMPS Base DIR you specified during application settings. The created task now appears in your UI: console page.

Retrieve all your tasks

  • Pass the following command with the appropriate credentials and domain name.

    curl.exe -k --dump-header h_Tasks.txt -v -u <domain>\<username>:<password> --ntlm http://localhost:6234/fmserver/v1/Tasks

Retrieve a particular task

  • Pass the following command with the appropriate credentials, domain name, and task name.

    curl.exe -k --dump-header h_Tasks.txt -v -u <domain>\<username>:<password> --ntlm http://localhost:6234/fmserver/v1/Tasks/<taskname>

Modify a task

  • To modify a task you have already created, edit the XML\JSON file you passed to create the task and pass it again using the following command:

    curl.exe -k --dump-header h_edit_task.txt -v -u <domain>\<username>:<password> --ntlm -H "Content-Type: application/XML" -X PUT --data [@]<TaskSample>.xml http://localhost:6234/fmserver/v1/Tasks/<TaskName>
    Note: The command to modify a task is similar to the command for creating a task. You just replace POST with PUT.

Delete a task

  • To Delete a task you have already created, pass the following command:

    curl.exe -k --dump-header h_delete_task.txt -v -u <domain>\<username>:<password> --request DELETE http://localhost:6234/fmserver/v1/Tasks/<TaskName>

See all the Web APIs

All the web APIs are listed at the Help URL:Localhost:6234\fmserver/v1/help

FMPS troubleshooting

  1. What products are installed via FMPS?

    1. FrameMaker 2019 release

    2. FrameMaker Server Components

  2. What Server features are installed along with the FMPS installer ?

    1. Installer also installs MS Deploy

    2. IIS and its components are registered for use by FMPS

    3. Installs a basic website (the application settings of the website need to be edited manually via IIS)

  3. Why do I not see IIS installed after the installation of FMPS?

    1. run "aspnet_regiis -i" in C:\Windows\Microsoft.NET\Framework\v4.X.XXXXX

  4. How do I install the FMPS website in IIS manually?

    If for any reason, FMPS fails to install the IIS website, you can execute the deploy command to install the website.

      1. Go to FMPS installation folder

      2. Run the bat file in admin mode with the following syntax:

        deploy.bat addsite -sitename newsite -port 9090 -physicalpath "c:\baseloc" addpool[or setpool] -poolname newpool

      3. newsite, path and newpool need to be provided.

  5. What parameters need to be edited in the application settings of FMPS website in IIS?

    A user name with password needs to be specified in Application settings to run FMPS tasks. You can specify a domain user or a local user.

      1. FMPSDomain - Domain name

      2. FMPSUser - User name

      3. FMPSPassword - Password of the FMPSUser user

      4. FMPSSchFolder - Folder containing FMPS scheduled tasks

      5. FMPSLocation - Full location of $install path of FMPS[FrameServerEx].exe

      6. FMPSBaseDir - Directory that would contain all the tasks related data

      7. debug - Allow debugging true/false

      8. DebugLog - Full path of the debug log that gets populated with error messages.

      9. FMPSHelpDataEnabled - For enabling Server Help to be viewable by any user

  6. How do I debug the problem if my tasks API are giving an unknown error?

    1. Open the debug log from the path of the mentioned variable "debuglog" in IIS -> FMPS website

  7. If a task/log/file is not getting deleted via the APIs, what could be the issue?

    1. There could be a problem with the permissions. You should give full permissions to the domain\user who runs the task.

  8. I can't see IIS installed even after installing FMPS?

    1. You need to restart computer to see IIS

  9. Even after restarting my computer IIS doesn't show up?

    1. IIS installation has failed for some reason, You would need to manually install IIS on your machine

      i. Install IIS on your machine. IIS7 or later versions.

      Goto Add Remove Programs

      ii. Go to Turn Windows Features On/Off

      iii. Check Internet Information Services

      iv. Check IIS > Compatibility > IIS Management scripts

      v. In IIS > Web Management Tool, check IIS Management scripts and tools, IIS Management Service and IIS Management console

      vi. Ensure HTTP Redirection, Static Content is ON in IIS > World Wide Web Services > Common HTTP Features

      vii. In IIS > WWW Services > Application Development Features, check ASP.NET (latest) and version 4 of .Net (if listed .. (Win10)). (Or .Net 3 in case of Server)

      viii. IIS > WWW Services > Security, check Windows Authentication, Basic Authentication.

      ix. Enable WCF components for .NET

      x. In .NET Framework (latest), check WCF HTTP/NON-HTTP activation

  10. I get a message "Object reference not set to an instance of an object". What can be the problem?

    1. The website type you are accessing is not correct. Check if the http port is open or https is correctly configured.

  11. Why do my tasks get created as the DefaultAppPool user though I have specified poolname in my deploy settings?

    1. Go to IIS -> website -> basic settings and set the pool to the desired poolname.

  12. How do I create an application pool in IIS?

    1. IIS -> Application Pools -> Add Application Pool (with default options)

  13. How do I know what ports are being used by FMPS website?

    1. IIS -> FMPS website -> Bindings

    2. For advanced settings: IIS -> FMPS website -> Advanced Settings

  14. How do I enable http ports for the FMPS website to be accessed from other computers?

    1. Say you want to allow Win Server allow for port access 6234

    2. To access the firewall, select Start -> Type in "Firewall" -> Click on "Windows Firewall With Advanced Security"

    3. (Logon as a batch job permission, member of users and IIS_IUSRS)

    4. To configure an inbound traffic rule:

      i. Right click "Inbound Rules" on the left pane

      ii. Choose "New Rule”

      iii. Choose "Port”

      iv. Under "Specific ports" enter your port number (9090)

      v. Continue with "Next" until the end of the wizard, naming the rule when prompted

    5. Check if your port is now accessible - you might need to restart the Windows Firewall service (under "Services")

  15. Why do I not get an email after a task is complete?

    1. Your virus scan may be blocking the emails. Try disabling that setting. For example, in McAfee -> Access protection properties -> (uncheck) Prevent mass mailing worms from sending mails

  16. Why do I get a Server 500 error and the Server console doesn't appear in browser?

    1. Restart IIS

  17. I get a Server 503 error "Service Unavailable" in the browser?

    1. Check whether the following settings reflect the current user name / password:

    2. Application Pool > fmps<version number> >Advanced Settings>Identity>Custom Account >Give the username/password once again

    3. fmps<version number>>Application Settings>FMPSPassword

    4. fmps<version number>>Application Settings>FMPSUsername

  18. I changed my password for the user. Why does stop working with the error "Service not available"?

    1. You need to go to IIS -> Application Pools -> Advanced Settings -> Identity -> Custom Account -> Give the user name / password once again

  19. Why am I not able to see Math ML equations in the published documents?

    1. Check whether you have accepted EULA for Math ML. Open FrameMaker and go to Special > MathML , if the EULA pops up ,accept it.

    2. Check whether JRE is installed on the machine. If not, install it from: http://java.com/en/download/help/index_installing.xml

  20. When I run a task nothing happens and command prompt is not launched. Why?

      1. i. Open IIS -> Application Pools.

        ii. Click on fmps<version number> and then on Advanced Settings.

        iii. If "Enable 32 bit applications" is set to false , change it true and restart the application pool.

    1. (Laptop Specific)

      i. Windows does not allow task scheduler to run if your laptop is not connected to a power source.

      ii. Connect your laptop to power source and try again.

  21. Why is the FMPS Dashboard not displaying properly on Internet Explorer browser.

    1. In IE 11 , open Settings> Compatibility View Settings (For lower versions of IE press F12 to find the compatibility view settings)

    2. Uncheck "Display Intranet sites in Compatibility view".

    3. Open FMPS website

  22. On clicking the Browse button, why does the message "Applet request Denied" display.

    1. Check if Java is installed. If not install the latest version.

    2. If Java is installed , go to Java Control Panel and:

      i. Enable Java content in the browser.

      ii. Add the FMPS WEBsite to the exception list. Restart the browser.

      iii. If the problem is still not solved , Uninstall all previous versions of Java, restart the browser and try again.


August 22, 2018

Legal Notices | Online Privacy Policy