XPP REST Client Query Para

What should a query string format be to execute a POST against XPP Server via XPP Rest API client? The help does not make much sense. When executed, it is asking for a Process ID number 

Run XPP commands on a Division or Job.

NOTE: The 'command' parameter is the program to run and must be located in the 'xz/bin' directory. For example, divtrace, divflags, show_xref, see Command Line Utilities

The caller is responsible for all options.




Field Type Description
command String

The name of the XPP commmand (in xz/bin) to run

optionsoptional String

Additional 'command' options

ecodeoptional String

error code for exit criteria 1 => OK if 0 >= exitcode < 128 (default=0)

path String

The "logical" 4/5-part path to a Division or Job in the form "handle:class:group:job:div"

nowaitoptional String

If "nowait=true", the command will return immediately with the id, code, and time the command started (default="false"). The user can check for command completion, by using the 'xpp/docs/processes/id' endpoint; where 'id' is the id used to get the status of the running program (default="false"). See Command Status for the command to determine the status of a 'nowait' program.

Allowed values: "true", "false"

  • Take for instance when the command server-name:2995/.../ run, it simply returns the contents of the root directory. The results are the same through postman or C# clients.

  • Hey Matt,

    Not entirely sure what you are after...

    The Division and Job Processing - Command is a GET and not a POST call.

    So something like GET ..../xpp/docs/first:xyvision:comp:blkmerge:1-blkmerge/print?options=-df%20.%20-nhdr%20-div%201-blkmerge should print the 1-blkmerge division.
    And you can use any xpp command from the xz/bin folder.
    Hence that the next command given in the doc 'compose' actually uses the same syntax
    GET  ..../xpp/docs/first:xyvision:comp:blkmerge:1-blkmerge/compose will compose that division

    Depending if you launch the 'command' with the 'nowait=true' option or not, the command will run in the background or not.
    If run in the background you will get back a processid, which you can then use to check the status of the command.
    See the Document Management - Waiting command status documentation on how to do that.

    What might help you further if the doc is not helpful, is to have a look at the tests that RWS is using to verify the correct working of the XPP REST installation. You can find them in the 't' folder inside the xz/xpprest folder.

  • Hi Bart,

    I mean a POST command. Here’s another example of calling the XPP sdedit command through the REST API. This command based on the documentation it should import a job ticket in XML into the job specified by the path parameter. Whether the code is ran in C# or a REST cient tool, it does not result in any errors, however, the sdedit command does not run and the job ticket is not created. Instead, the API returns the contents of the root directory specified bt the path parameter, which in this case, is actually an empty string.


  • Hi Bart. We are trying to get XPP commands working through the REST API.

    Following your example, when we send a Get request using the following URL


    where first:Automation:Jobs:test is the path to a new job

    We get the following error back

    I'm trying the xppversion command because it's something simple, but I get similar results for any other command that I try.
  • Matt,

    There must be something obvious that I am missing.
    In your initial entry you say you want to execute the 

    Run XPP commands on a Division or Job.

    and you give the documentation which clearly states that this is a GET call.

    - did you try using a GET?
    - why not?
    - what exactly do you want to do?

  • Hi Matt,

    You must have the wrong syntax for the GET URL, as the "path" value in the returned error clearly shows that "xppversion" was interpreted as the DIV name and not the Command you are attempting to run.

    I think that you need to have a slash before the Command part of the URL, and from the DOC excerpt you gave maybe even a bit more.

    I've not used the REST API myself, but maybe your URL should be something like this:

    Or the DOC seems to imply that it should be this (for a "generic" command):

    What I don't know is if you'll still get back some kind of ENOENT error because for a "generic" command it may assume that the referenced JOB (or DIV) has to already exist. You'll have to see what happens. But if you do still get back something like ENOENT you might want to try to reference an existing JOB (or DIV).

  • Hi Jonathan,

    Yes, I did get the ENOENT code.

  • As I said I'm not a REST API user myself but looking again at the Division and Job Processing intro and specific Command sections of the DOC I do have some more ideas.

    In the intro text it says:
    NOTE: The "logical" path must represent a valid Division or Job

    So, I'm thinking that you won't have any success with this area of the API if you're specifying a "new" JOB (or DIV) and will need to specify an existing JOB (or DIV).

    Next, I think that the URL syntax is still not correct for your "xppversion" test.

    When the JOB/DIV program you want to run is not one of the pre-defined ones (e.g. 'compose', 'loep', etc.) and you want to run a "generic" program (or command located in xz/bin) then I'm thinking that the URL syntax needs to be something like this:

    The DOC for a (generic) Command indicates that the "process" name is "command", and the "command" parameter (or field) is required (command=) and is the "name of the XPP command (in xz/bin) to run".

    Last, I think this test using "xppversion" will still fail somewhat because my understanding is that the program that is run (with Division and Job Processing area of API) is always passed "-cd path" as arguments and I notice that the "xppversion" program does not accept a -cd option.

    For example, when I run "xppversion -cd path" at a command prompt I get:
    ERROR: Cannot open /xpp/xz/bin/-cd
    path  NONE

    And xppversion returns a non-zero (failure) exit status.

    So, you also will probably need to test Division and Job Processing using something other than the xppversion program (if you're looking for a "successful" command), a program that accepts the -cd option.

  • Just one more thought.

    Running "xppversion -cd path" returns an exit value of 1.

    So, if you still want to run your test using "xppversion" then using a URL like this might work (using the 'ecode' parameter field to tell the REST API to accept the 1 exit value as "success"):

  • Hi Jonathan,

    It did not work. The results:

        "message""ERROR: Cannot open D:\\XPP\\xz/bin/-cd\r\nERROR: Cannot open D:\\XPP\\std_jobz\\alljobz/CLS_Automation/GRP_Jobs/JOB_test\r\n",