Server

Automation REST Response

Updated: December 5, 2024

When calling Automation operations through REST calls, you may want to throw custom exception and return it with the appropriate http error code or simply return the result when the process succeed with a custom HTTP status code.

Rest Custom Exception in Automation Operation and HTTP Code Error Setting

In order to throw custom exception and HTTP status code, you have to create a custom Exception extending org.nuxeo.ecm.automation.server.jaxrs.RestOperationException. You will be able to set the HTTP status code which will be return into the rest call response.

Example:

I have to create an ExceptionTest extending the RestOperationException:

ExceptionTest.java

/*
 * (C) Copyright 2017 Nuxeo (http://nuxeo.com/) and others.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * Contributors:
 *     vpasquier <[email protected]>
 */
package org.nuxeo.ecm.automation.test.helpers;

import org.nuxeo.ecm.automation.server.jaxrs.RestOperationException;

public class ExceptionTest extends RestOperationException {

    private static final long serialVersionUID = 7123858603327032114L;

    public ExceptionTest(String message, Throwable cause) {
        super(message, cause);
    }

    public ExceptionTest(String message) {
        super(message);
    }

    public ExceptionTest(Throwable cause) {
        super(cause);
    }
}

Given a custom operation HttpStatusOperationTest:

HttpStatusOperationTest.java

/*
 * (C) Copyright 2017 Nuxeo (http://nuxeo.com/) and others.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * Contributors:
 *     vpasquier <[email protected]>
 */
package org.nuxeo.ecm.automation.test.helpers;

import org.nuxeo.ecm.automation.core.Constants;
import org.nuxeo.ecm.automation.core.annotations.Context;
import org.nuxeo.ecm.automation.core.annotations.Operation;
import org.nuxeo.ecm.automation.core.annotations.OperationMethod;
import org.nuxeo.ecm.automation.core.annotations.Param;
import org.nuxeo.ecm.automation.jaxrs.io.operations.RestOperationContext;
import org.nuxeo.ecm.core.api.CoreSession;
import org.nuxeo.ecm.core.api.DocumentModel;
import org.nuxeo.ecm.core.api.PathRef;

import javax.servlet.http.HttpServletResponse;

/**
 * @since 7.1
 */
@Operation(id = HttpStatusOperationTest.ID, category = Constants.CAT_SERVICES,
        label = "Test Custom Http Status", description = "Test Custom Http " +
        "Status")
public class HttpStatusOperationTest {

    public static final String ID = "Test.HttpStatus";

    @Context
    RestOperationContext context;

    @Context
    CoreSession session;

    @OperationMethod()
    public Object run() throws Exception {
        DocumentModel root = session.getDocument(new PathRef("/"));
        // If context is instanceof RestOperationContext when jaxrs call is
        // executed
        if (context != null) {
                ExceptionTest exception = new ExceptionTest("Exception " +
                        "Message");
                exception.setStatus(HttpServletResponse.SC_METHOD_NOT_ALLOWED);
                throw exception;
        }// else context is instanceof OperationContext
        return root;
    }

}

I can decide to throw a custom exception (ExceptionTest) with the appropriate HTTP status code (here 405).

org.nuxeo.ecm.automation.jaxrs.io.operations.RestOperationContext should be inject into your custom operation to check if it's existing or not. Automation operation can be executed in local or remotely. You should check the operation "mode" when you throw this rest exception to keep your logs clear and to know from where location the operation has been called.

Setting HTTP Status Code When Success in Automation Operation

In case you would like to specify a success HTTP status code in return of your custom operation, you can use the RestOperationContext to set it up.

Example:

Given a custom operation HttpStatusOperationTest:

HttpStatusOperationTest.java

/*
 * (C) Copyright 2017 Nuxeo (http://nuxeo.com/) and others.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * Contributors:
 *     vpasquier <[email protected]>
 */
package org.nuxeo.ecm.automation.test.helpers;

import org.nuxeo.ecm.automation.core.Constants;
import org.nuxeo.ecm.automation.core.annotations.Context;
import org.nuxeo.ecm.automation.core.annotations.Operation;
import org.nuxeo.ecm.automation.core.annotations.OperationMethod;
import org.nuxeo.ecm.automation.core.annotations.Param;
import org.nuxeo.ecm.automation.jaxrs.io.operations.RestOperationContext;
import org.nuxeo.ecm.core.api.CoreSession;
import org.nuxeo.ecm.core.api.DocumentModel;
import org.nuxeo.ecm.core.api.PathRef;

import javax.servlet.http.HttpServletResponse;

/**
 * @since 7.1
 */
@Operation(id = HttpStatusOperationTest.ID, category = Constants.CAT_SERVICES,
        label = "Test Custom Http Status", description = "Test Custom Http " +
        "Status")
public class HttpStatusOperationTest {

    public static final String ID = "Test.HttpStatus";

    @Context
    RestOperationContext context;

    @Context
    CoreSession session;

    @OperationMethod()
    public Object run() throws Exception {
        DocumentModel root = session.getDocument(new PathRef("/"));
        // If context is instanceof RestOperationContext when jaxrs call is
        // executed
        if (context != null) {
                context.setHttpStatus(206);
            }
        }// else context is instanceof OperationContext
        return root;
    }

}

I can set into the context the appropriate HTTP status code that will be attached to the rest call response (here 206).


Other Related Documentation