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.

GET

/xpp/docs/:path/processes/command

Parameter

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"

emoji
Parents
  • 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.

    emoji
  • 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

    localhost:2995/.../first:Automation:Jobs:test:xppversion

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

    We get the following error back

    {
        "errno"-4058,
        "code""ENOENT",
        "syscall""scandir",
        "path""C:\\XPUB\\XPP\\std_jobz\\alljobz\\CLS_Automation\\GRP_Jobs\\JOB_test\\DIV_xppversion"
    }
    I'm trying the xppversion command because it's something simple, but I get similar results for any other command that I try.
    emoji
Reply
  • 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

    localhost:2995/.../first:Automation:Jobs:test:xppversion

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

    We get the following error back

    {
        "errno"-4058,
        "code""ENOENT",
        "syscall""scandir",
        "path""C:\\XPUB\\XPP\\std_jobz\\alljobz\\CLS_Automation\\GRP_Jobs\\JOB_test\\DIV_xppversion"
    }
    I'm trying the xppversion command because it's something simple, but I get similar results for any other command that I try.
    emoji
Children
  • 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:
    localhost:2995/.../first:Automation:Jobs:test/xppversion

    Or the DOC seems to imply that it should be this (for a "generic" command):
    localhost:2995/.../first:Automation:Jobs:test/processes/xppversion

    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).

    emoji
  • Hi Jonathan,

    Yes, I did get the ENOENT code.

    {
        "errno"-4058,
        "code""ENOENT",
        "syscall""scandir",
        "path""D:\\....\\std_jobz\\alljobz\\CLS_Automation\\GRP_Jobs\\JOB_test"
    }
    emoji
  • 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:
    localhost:2995/.../first:Automation:Jobs:test/processes/command?command=xppversion

    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.

    emoji
  • 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"):
    localhost:2995/.../first:Automation:Jobs:test/processes/command?command=xppversion&ecode=1

    emoji
  • 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",
        "code""1"
    }
    emoji
  • Hi Matt,

    Actually, it "did" work (using the ecode=1 parameter).

    The "message" response you've shown coming back from REST is the (error) messages out of running an (invalid) "xppversion -cd path" command, that I had mentioned you should expect with \r\n in the "message" value signifying the carriage returns in the messages (with slight variations due to my having paths on Linux and you on WIndows, and a bigger variation on the second error message due to my using a Linux path starting with a slash and you having a Windows path starting with a D: drive).

    And the response "code" of "1" jives with what I said was the error exit value of running an (invalid) xppversion -cd command. Because you specified the ecode=1 parameter, REST did not treat the exit value of "1" as an error (and that's why you got back the "message" value with the error messages instead of a "failed command" response you got before).

    In any case, I'm glad you finally got some "real" commands working with the REST API.

    emoji